eternityspring/reelbench-skills / skills/video-sync
video-sync
Verified把拉片数据和原片合成一条**能直接看的视频**:一边是画面,一边是这一镜的分镜信息 (镜号、起止、时长、景别、类别、运镜、画面描述、台词),**镜头切了信息跟着切**, 镜头表自动滚动并高亮当前这一镜。 版式只看原片的宽高比:**横版 / 方版 → 画面在上、信息在下;竖版 → 画面在左、信息在右**, 画面永远原样缩放,不裁不拉。 镜头表**随播放滚动**:切点处滚一小段把当前镜头带到锚点、随后停住,高亮条同步滑过去。 实现上只截三张图(底板 + 铺开的长图 ×2),滚动与高亮由 ffmpeg 按时间裁窗, **布局全在 scripts/panel.css 里,改它就能改版式**,不用碰脚本。 吃 video-shots 产出的 shots.json(有 frames/ 就把关键帧当缩略图用)。 零 npm 依赖,用 ffmpeg 合成、无头浏览器渲面板。 Use when asked to 导出视频、合成视频、分镜视频、带分镜信息的视频、解说版视频、 video with shot info、annotated shot video。
| File | Kind | Size |
|---|---|---|
| README.en.md | markdown | 7.7 KB |
| README.md | markdown | 6.8 KB |
| SKILL.md | skill md | 7.4 KB |
| assets/output-portrait.png | binary | 321.2 KB |
| assets/panel-landscape.png | binary | 214.7 KB |
| assets/panel-portrait.png | binary | 89.1 KB |
| references/layout.md | markdown | 6.5 KB |
| references/panel-style.md | markdown | 2.9 KB |
| scripts/panel.css | other | 6.8 KB |
| scripts/panel.html | other | 5.4 KB |
| scripts/selftest.mjs | script | 18.1 KB |
| scripts/video-sync.mjs | script | 29.8 KB |
README.en.md
View on GitHub[](README.md)
[](README.en.md)
# video-sync
Turns a [video-shots](../video-shots/README.en.md) breakdown plus the source film into a
**video you can just watch**: the footage on one side, the current shot's data on the other.
**The panel changes when the film cuts** — the shot list scrolls itself and highlights the shot
that is playing.
## The layout follows the aspect ratio, nothing else
| Source | Layout | |
| --- | --- | --- |
| Landscape (w > h), square | **footage on top, data below** | `vstack` |
| Portrait (h > w) | **footage on the left, data on the right** | `hstack` |
The portrait case — the output is 1580×1080, roughly 3:2, not a vertical clip jammed into 16:9
with black bars:
<img src="assets/output-portrait.png" width="620" alt="side-by-side layout">
Both directions **scale the footage as-is — never cropped, never stretched**; the panel fills the
rest of the canvas. Every dimension is rounded to an even number (h264 requires it) and the
panel's short side never drops below 260px (below that the text stops fitting).
It **never upscales by default**. But the panel is sized off the footage, so a small source gets a
small panel — a 640×360 clip only leaves 640×288, and four columns in that are unreadable. For
those, `--scale 2` takes the footage area to 1280×720 and the panel to 1280×576, aspect ratio
untouched. Details in [`references/layout.md`](references/layout.md).
## Three screenshots, and ffmpeg does the moving
Only two things on the panel ever change: **how far the list has scrolled** and **which row is
lit**. So neither per-frame screenshots nor one-per-shot:
```
measure once row positions, the list viewport, the full table height (the browser knows, the script cannot)
shoot three the static base (header + progress), the whole table dimmed, the whole table lit
compose crop a viewport out of the dimmed strip → scrolling
crop one row out of the lit strip → the highlight
```
For a 53-shot film that is 3 screenshots instead of 53 (12 seconds), and it buys **real continuous
motion**.
**The playing shot sits on the second row**: shots 1 and 2 leave the list still (only the
highlight moves down), and **from the third shot on every cut scrolls exactly one row**. The
scroll takes 0.45s and then stops — a list that creeps through a 16-second take is just
distracting. The highlight bar rides the same easing.
Row height **follows the content** (a longer description makes a taller row), so the highlight is
layered by height: `crop` cannot change height at runtime, so one layer per distinct row height,
and the ones not in use are parked off-screen.
Four traps, documented in [`references/layout.md`](references/layout.md): `drawbox` evaluates its
expressions only once at init (so it cannot animate); a whole-film expression makes ffmpeg's
parser fail outright at around a hundred terms (hence `sendcmd`, one short command per shot); the
`x` you crop at has to be the `x` you overlay back at (otherwise the whole table shifts right by
one indent and loses the same width off its right edge); and an unused highlight layer has to park
outside the **whole panel**, not just outside the list viewport, or a slice of it shows over the
progress bar.
## The layout is yours to change
The panel is an HTML page and **everything about how it looks lives in
[`scripts/panel.css`](scripts/panel.css)** — edit that and the layout changes. No need to touch
the script or rethink the screenshot logic. Re-run `panels` and you have the new design.
| | |
| --- | --- |
| <img src="assets/panel-landscape.png" width="440"> | <img src="assets/panel-portrait.png" width="200"> |
| Landscape: header + four columns (no./time/size/camera · frame · description · rhythm) | Portrait: the same four, narrow and tall |
`panels` also writes `panels/panel.html` — **open it in a browser to preview**, add `#S07` to the
URL to switch shots. Both layouts share one DOM and switch grid areas via `.landscape` /
`.portrait` on `.panel`, so there is no second template to forget about. Conventions in
[`references/panel-style.md`](references/panel-style.md).
Font size scales with the panel (`base = clamp(12, min(width/38, height/26), 26)`), so the CSS
uses **rem everywhere** — this is video, and 13px that reads fine on a monitor is mush on a phone.
## Usage
```bash
# 0. Start from a video-shots run: shots.json (+ frames/ for thumbnails)
# 1. Geometry only, no video work (seconds — check the numbers before committing)
node scripts/video-sync.mjs plan shots.json --video clip.mp4
# 2. Render panels: three stills plus a previewable panel.html
node scripts/video-sync.mjs panels shots.json --video clip.mp4 --frames frames --lang en
# 3. Compose (audio is carried over from the source)
node scripts/video-sync.mjs compose shots.json --video clip.mp4 -o out.mp4
# or in one go
node scripts/video-sync.mjs export shots.json --video clip.mp4 --frames frames -o out.mp4
```
Knobs: `--panel <ratio>` (landscape: panel height ÷ footage height, default 0.8; portrait: panel
width ÷ footage width, default 1.6), `--scale <factor>` (how far to blow up the footage area,
default 1 = never upscale; this is what makes a small source's panel readable),
`--width` / `--height` (caps on the footage area), `--crf`
(quality), `--ease` (easing seconds at each cut), `--anchor` (which row the playing shot sits on,
default 1 = second row), `--lang zh|en`.
Requirements: `node` >= 18 (standard library only) + `ffmpeg` / `ffprobe` + a headless browser
(Chrome / Chromium / Edge; `--chrome` takes a path). **No npm dependencies, no API keys.**
## "It didn't error" is not verification
Pull at least three frames and check **which shot the footage belongs to, whether the panel shows
that same shot number, and whether the highlighted row moved with it**:
```bash
for t in 5 30 60; do ffmpeg -v error -y -ss $t -i out.mp4 -frames:v 1 -q:v 3 /tmp/check-$t.jpg; done
```
A mismatch usually means shots.json and the film are not the same clip.
## Self-test
```bash
node scripts/selftest.mjs
# ✅ 122 assertions passed
```
No ffmpeg, no browser. It checks: geometry (landscape/square/portrait, even dimensions, caps,
knobs, erroring instead of guessing when dimensions are unreadable); the panel page's data
contract (vocabularies and rhythm roles sent as names not enum keys, thumbnails only when the file
exists, `<script>` escaped); the animation commands (every one must stay short, a long take clamps
once the scroll lands, `--ease` takes effect); and the ffmpeg arguments (vstack/hstack, `setsar=1`,
all three stills need `-loop`, no audio mapping on a silent source, the film must be input 0).
## Relationship to video-shots
```
video-shots → shots.json + frames/ → video-sync → out.mp4
(breakdown: cutting and annotating) (compositing: footage + data)
```
**The two skills are independent**: this one **carries its own copy** of the four vocabularies
rather than importing across directories — a skill has to survive being copied out on its own. The
price is that a new term added in `video-shots` has to be added here too, or it shows up as a raw
enum key.
## What it looks like
A 287.4-second English excerpt with its 46-shot breakdown, 1280×1296 (the source is 640×360,
blown up with `--scale 2`). The panel switches with every cut; the list scrolls up and the
highlight rides along:
<video src="https://github.com/eternityspring/reelbench-skills/raw/main/demo-sync/demo-en-sync.mp4" controls muted playsinline width="760"></video>
If the player does not load, grab the file: [`demo-sync/demo-en-sync.mp4`](../../demo-sync/demo-en-sync.mp4)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |