video-reference

1. 定位

本技能把一部已完成的成片拆成下一次制作可参考的方法与数值，按需在本地运行。它只写自己的测量、标注与导出物，不调用 MiMo，也不对生产流程评分或拦截。

Agent 的角色是拆片编辑：先如实记录"这部片子怎么做的"（事实），再提炼"换一部素材还能怎么用"（方法）。 两者必须分开：事实只留在本地工作目录，导出物只含方法和测得的数值。

2. 输入

• 成片文件（.mp4 / .mov / .mkv / .webm）。
• 对这部成片跑出的视频理解产物目录 U（建议 ASR_SEGMENT_SECONDS=5，窗口越短，旁白语速越准）。 本技能读取其中可选的 asr_result.json、asr_timing_evidence.json、background_research.json、understanding_index.json （其 characters 的名字、别名与 ASR 提及都进入人名泄漏扫描）； 标注时 Agent 还应看故事板 / contact sheet 与 vlm_analysis.json。

没有理解产物也能跑，但旁白语速为空，泄漏扫描只剩 Agent 自己写的 entities，check 会给出警告； 看画面可用 frames --span 0,<时长> --step 2 生成的抽帧拼图。

下面的 scripts/... 均相对于本技能目录。

3. 流程

python3 scripts/reference.py measure <成片> --work-dir U        # 一次 ffmpeg：切点 + 响度，按文件身份缓存
python3 scripts/reference.py frames  <成片> --work-dir U --review          # 逐帧看被压下的疑似切点
python3 scripts/reference.py frames  <成片> --work-dir U --longest 5       # 看最长镜头里有没有漏切
python3 scripts/reference.py check   --work-dir U [--json]      # 校验并打印派生值
python3 scripts/reference.py export  --work-dir U --out <下次运行的 work_dir>/production_reference.json

1. measure 写 U/reference_measurements.json（只由脚本写）：镜头切点、镜长分布、每分钟切点数、10 秒切点曲线、 整体响度 / LRA / 真峰值、逐秒短期响度。它要解码整片：5 分钟 720p 约 15–70 秒，4K 约 7 分钟；成片不变时复用， 只改 --soft-score/--hard-score 不重新解码。切点规则：scdet 分数 ≥10 必算；≥4 且是前后 0.3 秒内其他帧（相邻帧除外） 两倍以上的孤立峰才算。运动镜头、急推拉、闪光会被压下，并列进 shots.review_windows；scdet 分数会减去前一帧的帧差， 从快速运动切进静止镜头的硬切可能只有 1 分，所以帧差本身的单侧峰（mafd_peaks）也进待复核窗口，但不会自动算切点。
2. 复核切点：固定阈值在真实成片上两头都错（暗场硬切只有 5–7 分；快速运动的单个镜头每 0.2 秒一个 7–8 分的峰）， 所以每次都要看图。frames --review 逐帧拼出每个待复核窗口，frames --longest 5 在最长的 5 个镜头里均匀取 12 帧； 页面在 U/reference_frames/，命令打印每格对应的秒数。看完写 labels.cut_fixes：add 漏掉的切点秒数， remove 误报的切点秒数（±0.1 秒内对上测得的切点）；看过无需改动就写 {}。重新 measure 后待复核窗口数变了，旧的 cut_fixes 不再算数，按新窗口重看一遍。之后所有镜头数值、段内切点密度和导出都用复核后的切点。
3. 标注：Agent 写 U/reference_breakdown.json 的 labels——音轨归属 audio_spans、叙事段落 sections、 字幕形态 subtitles、标注依据 basis。audio_spans 的边界放在声音实际起止处（听得到的人声起点与止点）， 不放在字幕或旁白块的开始处（按字幕出现帧定的旁白结束点实测晚 0.24–0.42 秒）。U/speech_boundary_anchors.json 存在时， 用它的 acoustic_pauses（start 是人声停下处，end 是下一句开口处）对齐边界；switch_on_cut_share 只容差 ±0.25 秒， 边界放错它就只反映标注习惯。原片自带的画外音、内心独白也是原片音轨，记 original_dialogue；要区分时写进 fact 和方法。 只有 labels 时就可以跑 check，它会打印 derived（各音轨占比、段内切点密度、 旁白语速、声音切换与画面切点的对齐比例、分数位置的结构、第一次原声出现位置）。
4. 事实与方法：在同一文件写 source_facts（带时间或测量锚点、显式 entities）和 methods （rule、applies_when、avoid_when、applies_to、evidence、targets）。targets 只写 {"from": "<测量路径>"}， 数值由 export 从当前测量填入，Agent 永远不手写数字。
5. check → export：零 error 才导出；导出后对产物再做一次泄漏扫描。