video-sync

1## video-sync
2 
3把 **shots.json + 原片** 合成一条视频：画面一边，**当前镜头的分镜信息**另一边，
4镜头切了信息跟着切，镜头表自动滚动并高亮。
5 
6**版式只看宽高比，不看别的：**
7 
8| 原片 | 版式 | 合成方式 |
9| --- | --- | --- |
10| 横版（宽 > 高）、方版 | **画面在上，信息在下** | `vstack` |
11| 竖版（高 > 宽） | **画面在左，信息在右** | `hstack` |
12 
13两个方向都保证**画面原样缩放、不裁不拉**，面板补足剩下的地方。
14 
15**只截三张图，动的部分交给 ffmpeg。** 面板上会变的只有两样：滚到哪、哪一行亮。
16所以量一次行位置、截一张底板、截两张把镜头表铺开的长图（一张压暗、一张全亮），
17滚动＝从暗底长图裁一个视窗，高亮＝从亮条长图裁一行盖上去，位置由 `sendcmd`
18在每个切点下发一条小表达式驱动。53 镜的片子截图从 53 次降到 3 次（12 秒）。
19 
20**当前镜头钉在第二行**：第 1、2 镜不滚（高亮往下挪一行），第 3 镜起每切一次往上滚一行。
21**动在切点，静在镜头里**——切点处滚 `--ease`（默认 0.45）秒到位就停住，
2216 秒的长镜头里让列表一直爬，观众要盯着它晃 16 秒。
23 
24**行高由内容决定**，描述写得长行就高；高亮条按行高分层（`crop` 的高度运行时改不动）。
25 
26`{baseDir}` = 本文件所在目录。脚本 `{baseDir}/scripts/video-sync.mjs`，零依赖，`node` 直接跑。
27 
28**边界（不做的事）**：不做拉片（那是 `video-shots` 的活，本 skill 吃它的 shots.json）、
29不剪辑不转场不配乐、不烧字幕到画面上、不做逐帧渲染（动效由 ffmpeg 按时间裁窗做出来）。
30 
31---
32 
33### Step 0 — 先有拉片数据
34 
35要一份 `shots.json`（`video-shots` 的产出）和**对应的原片**。有 `frames/`（每镜关键帧）
36更好——镜头表里会用起手帧当缩略图，没有就留空格。
37 
38**shots.json 必须和这条片子对得上**：`meta.durationSeconds` 与原片不符就别合，
39先回去把拉片做对。
40 
41### Step 1 — 先看几何，再动视频
42 
43```bash
44node {baseDir}/scripts/video-sync.mjs plan shots.json --video <片>
45```
46 
47只算不合成，几秒出结果：版式、画面区、面板区、输出尺寸。**先确认这三个数字合理再往下走**——
48合成一条 3 分钟的片子要一两分钟，算错了再重来不值。
49 
50不满意就调：`--panel <比例>`（横版是面板高÷画面高，默认 0.8；竖版是面板宽÷画面宽，默认 1.6）、
51`--width` / `--height`（画面区的上限，默认 1920 / 1080）。
52 
53**原片太小就放大画面区**：面板是跟着画面区算的，640×360 的片子面板只有 640×288，
54四列挤在一起读不了。`--scale 2` 把画面区放到 1280×720、面板放到 1280×576，宽高比不动。
55默认是 1（只缩不放）。`plan` / `panels` / `compose` / `export` 都要带上同一个 `--scale`。
56 
57### Step 2 — 渲面板
58 
59```bash
60…