reelbench-skills (video-shots + video-sync)

What It Does

reelbench-skills is a two-skill pack from eternityspring (the author of shuohao-skills, the 3,218-star AI short-drama production suite) for film analysis work in Claude Code and Codex. video-shots performs shot breakdown: ffmpeg scene detection measures the cut points, durations, and a per-shot motion value from a frame-difference curve, the model only judges shot size, category, camera move, and frame description from keyframe contact sheets, and 15 deterministic quality gates then audit every judgment, with the hardest one blocking any claimed camera move whose measured frame change is near zero. video-sync composites the resulting shots.json with the source video into an annotated MP4: the picture on one side, the current shot's data on the other, switching at every cut with a scrolling highlighted shot list. The target user is an AI video creator or editor studying reference films (the Chinese workflow term is 拉片, film dissection).

The Good

The measured-versus-judged split is real, enforced, and it works on day one. Running seed on the bundled 202.9-second demo film produced 22 detected cut points merged into 23 shots, a motion curve of 1,013 samples at 5Hz, and a draft table where exactly the four model fields (size, category, camera, frame) were left empty while every machine field (start, end, seconds, motion) was filled. We planted six violations in the committed demo data and the validator caught all six, each failing with the named gate: a hand-edited duration field ("Durations add up"), a vague frame description ("Frame description is checkable"), an undeclared boundary move ("Boundaries come from detection"), an off-vocabulary shot size ("Shot size vocabulary"), a dialogue category with its dialogue stripped ("Categories carry evidence"), and the signature case, claiming push-in on shot S48 whose measured motion is 0, which the tool blocked with "Camera vs. measured motion". That last gate is a working anti-hallucination tripwire for the most common failure of model-based film analysis.

Outputs are deterministic and self-contained, and the committed demo reproduces. Two consecutive markdown renders produced identical md5 checksums (515f486ed2fe917ac3a9cb3bd6abdce4), as did two consecutive HTML report renders (9d20cf0e74aeb91ab33ef9284b92d7ae). The generated report contains zero external URLs, so the offline double-click claim holds at the HTML level. Our render differs from the committed demo-report/shots-report.html by only 20 diff lines in a 92KB file (the video path and title), and the composed video-sync output matched the committed reference exactly: h264 1280x1296, 30.144 seconds, aac audio carried over.

The self-verification culture is unusually deep for a 29-hour-old repo. video-shots ships a 724-line selftest with 436 assertions and a break-through case for every one of the 15 gates; video-sync ships 285 lines with 109 assertions covering geometry, panel data contracts, and ffmpeg command generation. Both suites pass clean from a bare clone with no install step. The committed demo data passes all 15 gates with exactly the two hints the SKILL.md promises (a static-annotated shot with high measured motion, and six flat-rhythm close-ups at the end), and we audited the demo JSON independently: 53 shots, 202.9 seconds total, 3.83-second average, zero timeline contiguity violations, zero duration-field mismatches, shortest shot 0.33 seconds, longest 16.06 seconds, all matching the README claims.

Zero-dependency discipline with a clean install lifecycle. There is no package.json anywhere in the repo, zero fetch or HTTP calls in the main scripts (verified by grep), and no API keys. install.sh symlinks both skills into ~/.claude/skills and ~/.codex/skills (auto-detecting which agents exist), refuses to overwrite real directories that are not symlinks, and uninstalls to zero residue, all verified in an isolated HOME. The universal skills CLI path also works: npx skills add with the hermes-agent target landed 15 files whose SKILL.md, all four references, and the main script were byte-identical to raw.githubusercontent.com main (7 of 7 compared files).

The Bad

Docs drift appeared within hours of the code. Both READMEs (Chinese and English) say "14 quality gates" in the skill table and the example section, while the code and SKILL.md ship 15: the rhythm-annotation gate was added in the 07:36 UTC commit on 2026-09-12 and the READMEs were not updated. The video-sync SKILL.md claims 106 selftest assertions while the suite now runs 109. Small numbers, but this is a skill whose entire value proposition is precise reconciliation.

The default detection threshold misses more than half the cuts on the repo's own demo film. Default seed found 23 shots on demo-video.mp4; the author's committed breakdown of the same film has 53 shots (46 seedCuts after threshold tuning plus 10 manually declared cuts for dissolves and end cards). The SKILL.md documents the fix in Step 1 (drop the threshold toward 0.15 for dark or slow films, rerun, it takes seconds), so this is a tuning requirement rather than a hidden defect, but a first-run user trusting defaults gets a substantially incomplete table on the flagship example.

The workflow contracts are Chinese-primary. Bilingual READMEs exist and the --lang en flag switches gate names, violation messages, CLI output, and the report interface to English, but the SKILL.md contracts themselves, the 191-line taxonomy of judgment criteria, and the analysis-pass guidance are Chinese-only. Non-Chinese readers can run the pipeline but cannot read the rules the model is told to follow.

The ecosystem surface is narrow and unregistered. The frontmatter declares runtimes claude-code and codex only; the README documents git clone plus install.sh for those two and never mentions Hermes, OpenClaw, or the universal skills CLI even though the latter works (we verified the hermes-agent install). The repo has no skills.sh registry entry (search returns count 0), no git tags, no releases, no CI, and 9 commits from a single author across 29 hours, so consumers pin nothing and get whatever main holds.

Install weight skews toward demo screenshots. video-sync is 93 percent README images by bytes (1,075,109 asset bytes against 86,309 functional bytes); video-shots is 66 percent (522,605 against 261,859). Agents that install these skills carry 1.6MB of illustration PNGs their runtime never reads.

Smoke Test Results

Host-based runs (the sbx sandbox daemon was not authenticated to Docker, the documented fallback): macOS 26.5.2 aarch64, Node 24.13.1, ffmpeg and ffprobe 8.0.1, Chrome present. All commands ran against a fresh shallow clone.

Run A: Fresh environment, no installs

$ node --version && ffmpeg -version | head -1
✅ v24.13.1, ffmpeg 8.0.1
$ node skills/video-shots/scripts/selftest.mjs
✅ 436 项断言全部通过（15 道门每道都有击穿用例） (436 assertions pass, every gate has a break case)
$ node skills/video-sync/scripts/selftest.mjs
✅ 109 项断言全部通过 (SKILL.md claims 106)
$ HOME=/tmp/reelbench-sbx-home ./scripts/install.sh
✅ 4 symlinks created (.claude + .codex, both skills)
$ HOME=/tmp/reelbench-sbx-home ./scripts/install.sh --uninstall
✅ 0 links remaining
$ find . -name package.json -not -path './.git/*' | wc -l
✅ 0 (zero npm dependencies)
$ grep -c 'fetch(' skills/*/scripts/*.mjs
✅ 0 network calls in both main scripts
$ ls '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
✅ present (needed only by video-sync panels)

Pass rate: 8 of 8. Both selftest suites pass from a bare clone with no install step.

Full fresh log →

Run B: With deps installed (real ffmpeg pipeline)

$ node video-shots.mjs seed demo-video.mp4 --track track.json > shots.json
✅ [seed] 202.9s / 30fps / 1680x720 → 检测 22 个切点，合并后 23 镜 (22 cuts, 23 shots)
$ python3 inspect_seed.py shots.json
✅ exactly 4 empty fields (size/category/camera/frame); machine fields filled; 1,013 motion samples
$ node video-shots.mjs frames shots.json --video demo-video.mp4
✅ 46 keyframes (2 per shot)
$ node video-shots.mjs sheet shots.json --cols 4 --rows 6
✅ contact sheet S01–S23 built (176KB)
$ node video-shots.mjs recut shots.json --track track.json --split 63.5 --merge 2.97
✅ 23 → 23 shots (1 split + 1 merge), manualCuts [63.5], renumbering contiguous, 0 duration mismatches
$ node video-shots.mjs recut shots.json --track track.json --merge 45.97
✅ exit 1: "这个时刻上没有镜头边界（容差 0.1 秒）" (no boundary at that time, tolerance 0.1s)
$ node video-sync.mjs plan shots.json --video demo-en.mp4
✅ landscape 1280x720 → vstack, panel 576px, output 1280x1296

Pass rate: 7 of 7. The whole measured pipeline runs on real video, and recut refuses a merge at a non-boundary instead of guessing.

Full with-deps log →

Run C: Functional verification (gates, negatives, determinism, compose)

$ node video-shots.mjs validate examples/demo-shots.json --track examples/demo-track.json --frames demo-report/frames --lang en
✅ 15 of 15 gates green, exactly 2 hints (S46 static-vs-motion, S48–S53 flat rhythm); 53 shots / 202.9s / 3.83s avg / 15.7 per minute
$ python3 check_demo_stats.py demo-shots.json
✅ independent audit: 0 contiguity violations, 0 duration mismatches, shortest 0.33s, longest 16.06s
$ bash negatives.sh
✅ 6 of 6 planted violations blocked with named gates (incl. "push-in" on motion=0 shot → Camera vs. measured motion)
$ render --md (twice) && md5
✅ byte-identical (515f486ed2fe917ac3a9cb3bd6abdce4)
$ render --html (twice) && md5
✅ byte-identical (9d20cf0e74aeb91ab33ef9284b92d7ae); 0 external URLs; 20 diff lines vs committed report
$ node video-sync.mjs panels shots.json --video demo-en.mp4 --frames frames --lang en
✅ static.png + list-dim.png + list-lit.png + layout.json + panel.html via headless Chrome
$ node video-sync.mjs compose shots.json --video demo-en.mp4 -o out.mp4
✅ h264 1280x1296, aac, 30.144s; identical geometry and duration to the committed demo-en-sync.mp4
$ bash fidelity.sh
✅ 7 of 7 files byte-identical to raw.githubusercontent.com main

Functional pass rate: 9 of 9. One definitional note: "15.7 cuts per minute" is computed as shots per minute (53 divided by 3.382); cuts strictly counted would be 15.4. The number is self-consistent with the README and the tool's own definition.

Full functional log →

What the runs tell you

Every script in the pack works first try on a real film with no install step and no network access, and the gate system does what the README's core claim says it does. What no host run can verify is the model-judgment loop itself (an agent reading contact sheets and filling the four fields inside a live session), which is why functional verification is partial despite the 9 of 9 script pass rate.

Setup Walkthrough

1. git clone --depth 1 https://github.com/eternityspring/reelbench-skills.git && cd reelbench-skills (65MB with demo videos; the skills themselves are 800KB and 1.1MB).
2. ./scripts/install.sh (add --claude or --codex to restrict; video-shots to install one skill). It warns about missing binaries but still installs.
3. Install prerequisites if missing: brew install node ffmpeg on macOS (Node 18+; Chrome, Chromium, or Edge needed only for video-sync panels).
4. In your agent, ask for a shot breakdown of a video (the skill routes on 拉片, 拆镜头, shot breakdown, shot list). The workflow runs seed, frames, contact sheets, batch judgment, then validate until all gates pass.
5. Verify your install anytime with node skills/video-shots/scripts/selftest.mjs (436 assertions, under a second, no model calls).

Gotchas: expect threshold tuning on dark or slow source films (Step 1 of the SKILL.md explains the 0.15-to-0.4 range; a 3-minute film reseeds in seconds). On macOS, headless Chrome prints CVDisplayLink errors during panels; they are harmless. The report needs the source video path (or an in-page file picker) to embed the player; the report file itself never contains the video.

Alternatives

1. eternityspring/shuohao-skills - the same author's generation-side suite (character bibles, outlines, screenplays, storyboards); use it to make films and reelbench-skills to dissect reference films; the two are companion pieces.
2. heygen-com/hyperframes (reviewed by GearScope) - an HTML-to-video rendering framework for producing video from code; it generates rather than analyzes, so it solves the opposite half of the workflow.
3. Manual ffmpeg plus a spreadsheet - what this skill replaces; scdet and scene filters give you the cut points, but the motion reconciliation, vocabulary gates, and the interactive report are exactly the parts you would have to rebuild yourself.