mathruffian-dot/claude-motion-explainer

Review loop (HyperFrames version)

You can't watch videos, but you can look at frames. Never report a video as complete without having seen the contact sheet of the current version.

Adapted from whaleyxbt/claude-motion's review-loop skill (MIT, see LICENSE in same folder). The original npm run … commands are replaced with kinocut MCP's HyperFrames tools and the scripts/sheet.py in this folder. Sections marked "(new in this version)" are not part of the original.

The SHEET below refers to python "<this skill folder>/scripts/sheet.py" (e.g., ~/.claude/skills/review-loop/scripts/sheet.py). All paths are absolute.

Loop

0. Run machine check first (new in this version): In the project folder, run hyperframes check. It runs lint, runtime, layout overflow, motion, and contrast checks all at once (official has deprecated validate/inspect in favor of check). Fix any errors before proceeding. See the official hyperframes-cli skill for details.
   • Mask reveals inevitably report container_overflow during entrance—this is intentional—add data-layout-allow-overflow to the mask container. But if text_box_overflow persists after settling, the container is too short (Chinese characters and superscripts are particularly prone to clipping); increase the container height.
1. Draft: hyperframes_render, parameters quality: "draft", output_path set to <project>/out/draft.mp4.
2. Contact sheet: SHEET --video <project>/out/draft.mp4 --timeline <project>/timeline.js --out <project>/out/sheets Takes a frame 0.3 seconds after each beat (when motion has settled), arranges them into 4×2 grids as out/sheets/beats-N.png, each cell labeled with beat name and time. Each cell defaults to 360 px wide, the actual width on mobile dynamics.
3. Open each sheet using Read and check every item against the checklist below.
4. Zoom in on suspicious areas:
   • Scan a transition: SHEET --video … --from 3 --to 5 --every 0.2 --name scrub
   • Look at specific moments: SHEET --video … --at 3.7,3.75,3.8 --name exact
   • View a single frame at full resolution: hyperframes_still, frame set to the frame number (seconds × fps)
   • When you don't want to re-render the video, use hyperframes_snapshot with at to directly screenshot from the composition, then combine with SHEET --images … --labels ….
5. Fix issues and return to step 0. Only stop after a full cycle finds no problems.
6. Final version: hyperframes_render, quality: "high" to produce the final video, then run step 2 again on the final video and perform the sound check (see below).

Checklist

Composition

• Each cell has only one focal point. When two elements compete for attention, one must wait.
• No unintended collisions or overlaps, especially during transitions where exiting and entering elements share the same space.
• Safe zone: important content should not be within about 60 px of the edge.
• The first frame is a real image, not black (it will be the thumbnail on social platforms).

Text

• Not clipped by masks, containers, or screen edges (unless intentional).
• When scaled to mobile width (the contact sheet cell size), key messages remain readable.
• Text is not in motion when it is meant to be read.
• (New in this version) Chinese: no typos; all characters are traditional (no simplified mixed in); punctuation is full‑width; no missing glyphs (showing squares or a noticeably different font).

Rhythm

• Every readable state holds long enough (see section 4 of motion-design). If text is still moving in the middle frames of a hold, the hold is too short.
• Scene transitions overlap; there is no cut to a blank screen.
• Exits are faster than entrances.

Consistency

• Only colors from the :root palette are used; accent colors correctly highlight the cell's focus.
• The same element looks identical across all scenes where it appears.

Sound (only when audio is present)

• Waveform: Use video_audio_waveform to check if peak levels fall on the TL beats.
• Loudness (new in this version, replaces original npm run wave): ffmpeg -hide_banner -nostats -i <final video> -af ebur128=peak=true -f null - Look at the summary's Integrated loudness and True peak. Target is −14 LUFS ±1, true peak ≤ −1 dBFS.
• Voiceover accent and emotion: ask the user to listen with their ears; do not rely on scores (new in this version).

Reporting

When done, clearly state: what was checked, what was fixed, and which sheet shows the result. Never claim a fix is complete without re‑rendering and personally verifying it.