Log in
TechniqueBy HypernaturalVersion 3, updated

Check pinned frames

hn/python-check-pinned-frames

Check whether video renders landed on their pinned first and last frames and how far each runs past the shot's length: per-frame SSIM against both stills, the frame where it lands on the last still, and the overage in frames and seconds. Use after image-to-video renders with a first frame, or first and last frames, pinned, to decide whether to trim the tail or re-brief a take that lands late.

SKILL.md

Give it the renders of one shot, the pinned first and last stills, and the shot's length; get back, per render, its frame count against the shot's, the overage, SSIM of frame 0 against the first still, and the frame where it best matches the last still. Models run long: this says whether the extra is a hold after landing (trim it) or slower action (the take lands late). For a first-frame-only render, pass the original shot's last frame as the last still. SSIM here locates frames; it doesn't judge framing. Read it next to python-measure-layout-drift, which does.

Run it

Write references/pinned-frames.md's script into the job's scripts/ as pinned_frames.py, as is, and run it with exec python:

exec python scripts/pinned_frames.py --videos <shot>_seedance_a.mp4 <shot>_seedance_b.mp4 \
    --first <shot>_first.png --last <shot>_last.png --frames 78 --fps 24 \
    --out <video folder>/measurements.json

--frames and --fps are the shot's length, not the render's. --out merges into an existing measurements file, keyed by render name.

What you get

FieldMeaning
fps, frames, durationthe render's own (frames counted, not estimated)
target_frames, overage_frames, overage_sthe shot's length and how far past it the render runs
ssim_frame0_vs_firstdid it open on the pinned first frame
best_last_index, landing_time_s, best_last_ssimwhere it matches the last still best, and how well
ssim_final_vs_lastthe render's final frame against the last still
tail_after_landingframes after the landing: a hold you can trim

Reading the numbers

  • Opening: first-frame i2v holds frame 0 at ~0.996 (Kling v3) to ~0.997 (Seedance 2.5); pinned H3 Max lip-sync chunks only 0.94–0.98, since H3 re-renders the face. A ref2vid mode with no first frame redraws the opening (0.2–0.5); so can a take that kept the layout but zoomed 2%, so when frame 0 reads low, run python-measure-layout-drift before rejecting it.
  • Lands, then holds (tail_after_landing ≥ overage_frames): trim the tail to the shot's length.
  • Lands late (landing_time_s past the shot's end): the action is slow. Don't speed it up (it reads badly); re-brief it to act in real time and hold the final pose, or start the trim later to skip an idle opening.
  • Pinned end frames sit past the requested length: 17 H3 Max lip-sync takes pinned first and last to one still ran 0.06–0.71 s over. Their final frames read 0.94–0.97 against the still, about what frame 0 does, since H3 re-renders the face; the frame at the cut only 0.89–0.97, still settling into the end pose. python-measure-layout-drift read 0.998 on the same final frames: the layout lands even where the pixels don't. Trim to the shot's length, and judge a join on the pose at the cut (python-assemble-lipsync-chunks).
  • best_last_ssim well under the opening's means it never reached the last still: look at the take before trimming.

Tips and traps

  • Check the render's frame rate first (ffprobe-inspect-media): a 25 or 30 fps render against a 24 fps shot changes every frame count here.
  • Both curves are computed in greyscale at 480 px wide: good for finding frames, too coarse for grading detail (python-measure-detail does that).
  • Put the landing frame and overage in the take's facts in the review.

Check it

Run it on the source shot itself with its own first and last frames: frame 0 reads ~1.0, it lands on its last frame, and the overage is 0.

FAQs

Check whether video renders landed on their pinned first and last frames and how far each runs past the shot's length: per-frame SSIM against both stills, the frame where it lands on the last still, and the overage in frames and seconds. Use after image-to-video renders with a first frame, or first and last frames, pinned, to decide whether to trim the tail or re-brief a take that lands late.

Install Hypernatural Desktop, a free Mac app, and connect it to Claude Code, Codex or Claude Desktop. Then describe the video you want and your agent finds the skill itself, or paste this page's link (https://hypernatural.ai/skill/hn/python-check-pinned-frames) and it installs hn/python-check-pinned-frames and follows it.

Nothing. The skill is free and runs with tools on your own Mac, like python, ffmpeg and ffprobe.

Yes. Ask your agent to adjust it for your job, or to save its own version. You can publish your version under your own handle so anyone can install it.

Go make something cool.

Install the app, open your agent, describe the video. That's the whole onboarding.

Sticker HypernaturalSticker BannerSticker TVBoy