video-reference

1## 1. 定位
2 
3本技能把一部**已完成的成片**拆成下一次制作可参考的方法与数值，按需在本地运行。它只写自己的测量、标注与导出物，不调用 MiMo，也不对生产流程评分或拦截。
4 
5Agent 的角色是**拆片编辑**：先如实记录"这部片子怎么做的"（事实），再提炼"换一部素材还能怎么用"（方法）。
6两者必须分开：事实只留在本地工作目录，导出物只含方法和测得的数值。
7 
8## 2. 输入
9 
10- 成片文件（`.mp4 / .mov / .mkv / .webm`）。
11- 对**这部成片**跑出的视频理解产物目录 `U`（建议 `ASR_SEGMENT_SECONDS=5`，窗口越短，旁白语速越准）。
12  本技能读取其中可选的 `asr_result.json`、`asr_timing_evidence.json`、`background_research.json`、`understanding_index.json`
13  （其 `characters` 的名字、别名与 ASR 提及都进入人名泄漏扫描）；
14  标注时 Agent 还应看故事板 / contact sheet 与 `vlm_analysis.json`。
15 
16没有理解产物也能跑，但旁白语速为空，泄漏扫描只剩 Agent 自己写的 `entities`，check 会给出警告；
17看画面可用 `frames --span 0,<时长> --step 2` 生成的抽帧拼图。
18 
19下面的 `scripts/...` 均相对于本技能目录。
20 
21## 3. 流程
22 
23```bash
24python3 scripts/reference.py measure <成片> --work-dir U        # 一次 ffmpeg：切点 + 响度，按文件身份缓存
25python3 scripts/reference.py frames  <成片> --work-dir U --review          # 逐帧看被压下的疑似切点
26python3 scripts/reference.py frames  <成片> --work-dir U --longest 5       # 看最长镜头里有没有漏切
27python3 scripts/reference.py check   --work-dir U [--json]      # 校验并打印派生值
28python3 scripts/reference.py export  --work-dir U --out <下次运行的 work_dir>/production_reference.json
29```
30 
311. **measure** 写 `U/reference_measurements.json`（只由脚本写）：镜头切点、镜长分布、每分钟切点数、10 秒切点曲线、
32   整体响度 / LRA / 真峰值、逐秒短期响度。它要解码整片：5 分钟 720p 约 15–70 秒，4K 约 7 分钟；成片不变时复用，
33   只改 `--soft-score/--hard-score` 不重新解码。切点规则：scdet 分数 ≥10 必算；≥4 且是前后 0.3 秒内其他帧（相邻帧除外）
34   两倍以上的孤立峰才算。运动镜头、急推拉、闪光会被压下，并列进 `shots.review_windows`；scdet 分数会减去前一帧的帧差，
35…