review-loop

Review loop (HyperFrames edition)

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

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

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 deprecated; use checkinstead). Fix any errors first, then continue. For details, see the official hyperframes-cli skill。
   • Mask reveals will always report container_overflowduring entry; this is intentional design—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 text (Chinese characters and superscripts are especially prone to this); increase the container height.
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," stitch them 4×2 into beats-N.png, and label each cell with its time. Each cell defaults to 360 px wide, i.e., the actual width on a mobile feed. 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 that manage beats with timeline.js Projects that manage 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-file reading tool) and check each item against the checklist below. Merely looking at filenames or logs does not count as having looked.
5. Zoom in on anything suspicious:
   • Scan a transition:SHEET --video … --from 3 --to 5 --every 0.2 --name scrub
   • Look at a specific moment:SHEET --video … --at 3.7,3.75,3.8 --name exact
   • View a single cell 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 capture directly from the composition:npx hyperframes snapshot --at 3.7,5.2 --no-end --describe false -o <資料夾>, then stitch them with SHEET --images … --labels … .
6. After fixing, return to step 0. Stop only after a full round with no issues found.
7. Final version: export the finished video at high quality (motion-explainer projects follow section 8 of their guide), run step 2 again on the finished video, then do an audio check (see below).

Checklist

Composition

• Each cell 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 area: keep important content at least about 60 px from the edges.
• Frame 0 is the actual image, not black (it is the thumbnail on the social platform).

Text

• Not clipped by masks, containers, or frame edges (unless intentional).
• When shrunk to phone width (the sheet's cells), the key message is 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 (no 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 a mid-hold cell, the hold is too short.
• Scenes overlap and connect, not cut to a blank screen.
• Exit is faster than entrance.

Consistency

• Use only colors from the :root palette; the accent color marks what this cell is highlighting.
• 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 (e.g., 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 Chinese narration's accent and emotion, ask the user to listen with their ears; do not substitute a score (new in this version).

Report

When done, state clearly: what was checked, what was fixed, and which sheet shows the result. Do not claim a fix is done unless you have re-exported and looked at it yourself.