tzezhang1-crypto/claude-motion-explainer-video

Review Loop (HyperFrames Version)

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

Adapted from whaleyxbt/claude-motion's review-loop skill (MIT, see LICENSE in the same folder). The original npm run … commands have been 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 must be absolute.

The Loop

0. Run machine checks first (New in this version): Execute hyperframes check in the project folder. It runs lint, runtime, layout overflow, motion, and contrast checks in one pass (the official validate/inspect commands are deprecated; use check instead). Fix any errors before proceeding. See the official hyperframes-cli skill for details.
   • Mask reveals during entrance will inevitably report container_overflow—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 and will clip text (especially Chinese and superscripts); increase the container height.
1. Draft: hyperframes_render with 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 Captures one frame 0.3 seconds after each beat (once motion has settled), arranges them in 4×2 grids as out/sheets/beats-N.png, each labeled with beat name and time. Each frame defaults to 360 px wide—the actual width on mobile dynamic islands.
3. Use Read to open each sheet and inspect every cell 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, set frame to the frame number (seconds × fps)
   • To avoid re-rendering, use hyperframes_snapshot with at to capture directly from the composition, then combine with SHEET --images … --labels ….
5. Fix issues and go back to step 0. Only stop when a full pass finds no problems.
6. Final version: hyperframes_render with quality: "high" to produce the final video, then run step 2 on it, followed by audio checks (see below).

Checklist

Composition

• Each frame has a single focal point. When two elements compete, one must wait.
• No unintentional collisions or overlaps, especially during transitions where exit and entry elements share the same space.
• Safe area: Important content should not be closer than ~60 px from the edges.
• Frame 0 shows the actual image, not black (it will be the thumbnail on social platforms).

Text

• Not clipped by masks, containers, or frame edges (unless intentional).
• When shrunk to mobile width (sheet cells), key information remains readable.
• Text is not moving when it should be read.
• (New in this version) Chinese: no typos; all characters are in Traditional Chinese script (no Simplified Chinese mixed in); punctuation uses full-width forms; no missing font glyphs (rendered as boxes or clearly different fonts).

Rhythm

• Each state that needs to be read stays on screen 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.
• Scenes overlap seamlessly, never cutting to a blank frame.
• Exits are faster than entrances.

Consistency

• Only use colors from the :root palette; accent colors must highlight the key point in that frame.
• The same element looks identical in every scene it appears.

Audio (only if there is sound)

• Waveform: Use video_audio_waveform to check if peaks align with beats in the TL.
• Loudness (New in this version, replaces the original npm run wave):
  ffmpeg -hide_banner -nostats -i <final video> -af ebur128=peak=true -f null -
  Check the summary for Integrated loudness and True peak. Target: −14 LUFS ±1, true peak ≤ −1 dBFS.
• For Chinese voiceover accent and emotion, the user must listen with their ears—do not substitute scores (New in this version).

Reporting

When finished, clearly state: what was checked, what was fixed, and which sheet shows the result. Never claim a fix was made without re-exporting and personally inspecting the result.