review-loop

Review loop (HyperFrames edition)

You can't watch the video, but you can see the frames. Never report a video as complete without having looked at the contact sheet of the "current version" output.

Adapted from whaleyxbt/claude-motion's review-loop skill (MIT, see LICENSEin the same folder). The original's npm run … commands have been replaced with the HyperFrames CLI and ffmpeg, as well as this folder's scripts/sheet.py. Sections marked "(new in this version)" are not from the original.

Below, SHEET refers to python "<此技能資料夾>/scripts/sheet.py". This skill folder is usually at ~/.claude/skills/review-loop(Claude Code) or ~/.agents/skills/review-loop(Codex). Use absolute paths for all paths. Requires Python + Pillow and ffmpeg.

Loop

1. Run machine checks first(new in this version): in the project folder, run npx hyperframes check. It runs lint, runtime, layout overflow, motion, and contrast checks in one go (the official docs have already marked validate／inspect as outdated; use checkinstead). Fix any errors first, then continue. For details, see the official hyperframes-cli skill。
   • Mask reveals will always report container_overflowmid-entrance; this is intentional design, so add data-layout-allow-overflowto the mask container. But if it still reports text_box_overflowafter settling, the container is too short and will clip the text (Chinese characters and superscripts are especially prone), so make the container taller.
2. Draft: in the project folder, run npx hyperframes render --quality draft --output renders/draft.mp4。
3. Contact sheet: capture the moment each beat "settles", assemble into a 4×2 beats-N.png, and label each cell with its timestamp. Each cell is 360 px wide by default, i.e., the actual width on mobile feeds. Beat timing depends on the project type:
   • motion-explainer series projects(with audio_meta.json): 0.15 seconds before the end of each narration clause. SHEET --video <專案>/renders/draft.mp4 --at "$(python <motion-explainer 系列技能資料夾>/scripts/review_times.py --project <專案>)" --out <專案>/review --name draft
   • Projects managing beats with timeline.js A project about managing rhythm（motion-design section 1): 0.3 seconds after each beat. SHEET --video <專案>/renders/draft.mp4 --timeline <專案>/timeline.js --out <專案>/review
4. Open and look at every sheet(using your image-reading tool), and check each item against the checklist below. Just looking at filenames or logs doesn't count as having looked.
5. Zoom in on anything suspicious:
   • Scan a transition:SHEET --video … --from 3 --to 5 --every 0.2 --name scrub
   • View a specific moment:SHEET --video … --at 3.7,3.75,3.8 --name exact
   • View a single frame at full resolution:ffmpeg -v error -ss <秒數> -i <專案>/renders/draft.mp4 -frames:v 1 frame.png
   • If you don't want to re-export the video, you can screenshot directly from the composition:npx hyperframes snapshot --at 3.7,5.2 --no-end --describe false -o <資料夾>, then stitch them together with SHEET --images … --labels … .
6. After fixing, go back to step 0. Only stop after a full round with no issues found.
7. Final version: export the final video at high quality (motion-explainer projects follow section 8 of their guide), run step 2 again on the final video, then do an audio check (see below).

Checklist

Composition

• Each frame has only one focal point. When two things compete for attention, one of them must wait.
• No unintentional collisions or overlaps, especially during transitions where exiting and entering elements share the same space.
• Safe zone: important content should be no less than about 60 px from the edge.
• Frame 0 is the actual frame, not black (it is the thumbnail on the social platform).

Text

• Not cut off by masks, containers, or frame edges (unless intentional).
• When scaled down to phone width (sheet cells), key messages are still readable.
• When it should be read, the text is not moving.
• (New in this version) Chinese: no typos; all Traditional Chinese glyphs, no Simplified mixed in; full-width punctuation; no missing glyphs (tofu boxes or obviously different fonts).

Rhythm

• Every state meant to be read stays long enough (see motion-design Section 4). If text is still moving in the middle of a hold, the hold is too short.
• Scenes overlap and connect; they do not cut to a blank screen.
• Exits are faster than entrances.

Consistency

• Use only colors from the :root palette; the accent color marks the focus of that frame.
• The same element looks the same in every scene where it appears.

Audio (only when there is audio)

• Waveform:ffmpeg -v error -i <成片> -filter_complex "showwavespic=s=1600x240" -frames:v 1 wave.png; open the image and check whether the audio peaks land on the beat (for example, the accent lands at the moment the number appears).
• Loudness (new in this version, replacing the original's npm run wave）： ffmpeg -hide_banner -nostats -i <成片> -af ebur128=peak=true -f null - See the final summary's Integrated loudness and True peak. Target is −14 LUFS ±1, true peak ≤ −1 dBFS.
• For the accent and emotion of the Chinese voiceover, ask the user to listen with their ears; do not substitute a score (new in this version).

Reporting

When done, state clearly: what was checked, what was fixed, and which sheet shows the result. Do not claim a fix is done unless it was re-exported and seen with your own eyes.