--- name: video-reference user-invocable: true description: 按需把一部优秀成片拆成可复用的制作参考:实测镜头节奏与音量起伏,标注段落与声音分工,把原片剧情事实与通用剪辑手法分开,导出不含原片人名和台词的 production_reference.json 供下次做片参考。独立于日常做片流程。触发词:拆片、拆解成片、制作参考、参考模板、production reference。 --- ## 1. 定位 本技能用于按需拆解一部**已经做好的优秀解说成片**,把它的剪辑节奏、声音分工与叙事手法提炼成下次做片可直接参考的方法卡片与实测指标。全程在本地运行,只输出测量数据、拆片标注与脱敏参考文件,不调用 MiMo,也不会给日常做片打分或设卡拦截。 Agent 在此扮演**拆片编辑**:先把“这条成片具体是怎么剪、怎么配的”(原片事实)如实记下来,再从中提炼出“换一部新素材还能怎么借鉴”(可迁移方法)。**事实与方法必须彻底分家**:包含原片人名、剧情和具体台词的事实只留在本地拆片目录里,最终导出的 `production_reference.json` 只保留通用方法与实测节奏数值。 ## 2. 输入 - 待拆解的成片视频文件(支持 `.mp4 / .mov / .mkv / .webm`)。 - 针对**这部成片**跑出的视频理解产物目录 `U`(建议在理解阶段设 `ASR_SEGMENT_SECONDS=5`,分窗越细,测算出的旁白语速越准)。本技能会从中读取可选的 `asr_result.json`、`asr_timing_evidence.json` 与 `background_research.json`(其中登记的角色名、别名及 ASR 台词都会纳入防剧透泄漏扫描);Agent 做人工标注时还应结合故事板拼图(storyboard)与 `vlm_analysis.json` 一起看。 即使没有跑过视频理解,本技能也能单独运行,只是导出的旁白语速字段为空、防泄漏扫描词表仅依赖 Agent 手写的 `entities`,且 `check` 会给出相应警告;此时可用 `frames --span 0,<时长> --step 2` 抽帧生成拼图来辅助看片。 以下 `scripts/...` 路径均相对于本技能目录。 ## 3. 拆片流程 ```bash 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 # 抽出最长的 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 秒滑动窗口切点密度曲线、整体响度(Integrated LUFS)、响度动态范围(LRA)、真峰值以及逐秒短期响度。该步骤需完整解码整部成片(5 分钟 720p 视频约耗时 15–70 秒,4K 视频约 7 分钟);只要成片文件未变就会直接复用缓存,单独调整 `--soft-score` 或 `--hard-score` 阈值无需重新解码。 - **切点初筛逻辑**:`scdet` 场景切换得分 `≥10` 的帧直接判为切点;得分在 `4` 到 `10` 之间时,只有当该帧得分达到前后 `0.3` 秒窗口内其余非相邻帧最高分的两倍以上(明显高出周围帧的局部峰值),才判为切点。这样能过滤掉大部分跟拍晃动、急推拉和闪光灯,把这些拿不准的帧归入待复核窗口 `shots.review_windows`。此外,由于 `scdet` 得分会扣减上一帧的画面变化量,从剧烈运动镜头突然硬切到静止画面时,`scdet` 得分可能被压到只有 1 分左右;因此工具会把帧间画面差(`mafd`)自身突起的峰值也一并收进 `shots.review_windows` 供人工看图确认,但不会直接算作自动切点。 2. **看图复核切点(`frames`)**:任何固定阈值在真实成片面前都会顾此失彼(昏暗夜戏的硬切可能只有 5–7 分,而激烈打斗的一个长镜头里每隔 0.2 秒就能蹦出 7–8 分的峰值),因此必须看图复核。运行 `frames --review` 会把每个待复核窗口逐帧拼成图片,运行 `frames --longest 5` 会在全片最长的 5 个镜头里各均匀抽取 12 帧拼图;图片输出在 `U/reference_frames/` 下,终端会打印每一格对应的时间秒数。看完图后在 `labels.cut_fixes` 中登记修正:`add` 填入算法漏掉的真切点秒数,`remove` 填入算法误报的假切点秒数(与测得切点误差在 `±0.1` 秒内即可匹配);若确认全部准确、无需增删,显式写 `"cut_fixes": {}` 表示已复核。注意:一旦重跑 `measure` 导致待复核窗口发生变化,旧的 `cut_fixes` 不再算数,Agent 必须对照新窗口重新核对更新。复核完成后,后续所有镜头统计指标、段落切点密度和最终导出物都会按修正后的切点重新计算。 3. **标注音轨与段落(`labels`)**:由 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`,如需在做法上区分,写进后面的 `source_facts` 与 `methods` 即可。 - 填完 `labels` 后即可先跑一次 `check`,查看终端打印出的派生统计值 `derived`(各音轨时长占比、各段落切点密度、旁白字速、声音换手落在画面硬切上的比例、全片各叙事功能段落在时间轴上的起止占比 `structure`,以及第一次原声亮相的相对位置 `first_original_at`)。 4. **提炼事实与可迁移方法(`source_facts` 与 `methods`)**:对照刚刚算出的客观派生数据,在同一份 `reference_breakdown.json` 中继续填写原片事实 `source_facts`(必须锚定具体时间区间或测量路径,并显式列出涉及的专有名称 `entities`)与可迁移方法 `methods`(包含做法规则 `rule`、适用场景 `applies_when`、避坑条件 `avoid_when`、作用的下游文件 `applies_to`、支撑证据 `evidence` 与量化参考指标 `targets`)。注意:`targets` 里只写引用路径 `{"from": "<测量路径>"}`(数值叶子或白名单派生对象),建议不要在 `rule` 正文里直接手写阿拉伯数字(手写数字会触发非阻断 warning 提醒核查);导出时脚本会自动把实测数值填进去。 5. **校验并导出(`check` → `export`)**:运行 `check` 确认零 error 后,执行 `export` 导出 `production_reference.json`;导出器在写入文件前会对产物再做一遍全字段防剧透泄漏扫描。 完整字段定义、枚举词表以及好/坏方法写法对比见 `references/reference-schema.md`。 ## 4. 校验与防泄漏规则 `reference.py check` 遇到以下任一错误(error)都会以退出码 `1` 阻断: | 规则编号 | 校验要求 | |---|---| | R1 | 顶层、`labels`、`fact`、`method`、`target`、`cut_fixes` 均采用严格封闭键集与封闭枚举;`fact` 不得混入方法字段,`method` 不得混入事实字段;编号须形如 `f1…` / `m1…` 且全局唯一;`subtitles` 字段类型固定;`skipped_dimensions` 的原因说明必须为非空字符串 | | R2 | `audio_spans` 与 `sections` 必须按时间升序排列、互不重叠、相邻间隙 `≤0.5` 秒且完整覆盖全片时长;字幕取证时间点必须落在全片时长内;`cut_fixes.remove` 必须匹配某个已测得的切点,`add` 不得与已有切点重复 | | R3 | 每条 `fact` 必须在时间锚点 `t: [a, b]`(落在成片时长内)与测量锚点 `measure: [路径]`(解析到 `shots` / `loudness` / `derived` 下的非字符串数值)之间二选一,且必须显式填写 `entities` 数组 | | R4 | 每条 `method` 至少绑定一条支撑证据:引用已定义的 `fact` ID,或引用 `measure:<路径>`(同样仅限上述三个根路径) | | R5 | `target` 只允许写 `from` 键,指向 `shots`、`loudness` 或 `derived` 下的数值叶子节点或白名单派生对象(见 schema),不可使用列表下标 | | R6 | `rule`、`applies_when`、`avoid_when` 以及 `skipped_dimensions` 的原因说明中,不得出现:原片专有名称(忽略空格比对)、与 ASR 台词或背景资料完全重合的连续 8 个汉字(跨标点、跨相邻 ASR 窗口同样拦截)或连续 5 个英文单词、绝对时间码、“第 N 秒”或“N 分 M 秒”(含汉字数字)、本地绝对路径 | | R7 | `methods` 至少提炼一条可迁移方法;五个制作维度(`narrative_structure`、`pacing`、`shots_editing`、`narration_subtitles`、`audio_visual`)按成片实际亮点提炼,未覆盖且未在 `skipped_dimensions` 写明原因的维度仅报 warning 提示 | | R8 | 导出 `production_reference.json` 时,对所有键名和字符串值再跑一遍 R6 防泄漏扫描,且导出物任意层级不得出现 `source_facts`、`labels`、`entities`、`evidence`、`statement`、`from`、`path` 键 | 防泄漏词表会自动汇总 `source_facts[].entities`、`background_research.json` 中的角色与 `character_details` 别名、不超过 5 个字的 `cultural_notes` 词条,以及资料中带《》「」引号的短词。 以下情况仅报警告(warning),不阻断导出:`method` 与 `source_facts` 的描述共有连续 8 字或 5 词(提醒核查是否带入原片情节;通用剪辑表述无需硬换近义词)、五个维度中存在未覆盖也未登记 `skipped_dimensions` 的维度、`method` 未填 `applies_when`、`rule` 正文里直接写了阿拉伯数字、ASR 精度不是 `AVAILABLE_COARSE`、成片含中文对白但理解产物与资料库均未提供人名(此时仅靠手写的 `entities` 把关)、`basis` 为空、理解产物记录的视频文件身份与当前测量的成片不一致、存在待复核切点窗口但未填写 `cut_fixes`。 注意:R6 只能拦住字面重合,拦不住换了词却仍在复述原片剧情的写法;编写 `method` 时要总结“遇到什么素材特征时怎么处理”,不要写成“主角进门后怎么剪”。此外,校验器不检查自然语言语义是否与数据吻合——动笔写“哪类段落切镜更密”前,先核对 `check` 打印出的 `cuts_per_min` 实测值,不要凭印象写出与实测数据相反的结论。 ## 5. 交付物与后续使用 最终导出的 `production_reference.json` 只包含:成片总时长与画布尺寸、`cut_detection`(切点检测参数及人工增删的切点数)、`profile`(核心节奏与响度指标)、全片各叙事段落在时间轴上的相对位置分布 `structure`、字幕版式特征 `subtitles`、可迁移方法列表 `methods` 以及跳过的维度说明 `skipped_dimensions`。其中 `profile` 每项指标都附带数据来源标记 `provenance`:`measured` 表示纯算法实测,`reviewed` 表示经过 `cut_fixes` 人工复核,`labeled` 表示依赖人工音轨或段落标注。 使用方法:将导出的 `production_reference.json` 放进下一次制作任务的 `work_dir`(或通过资源库的 `production_reference` 模板绑定)。下游写稿阶段发现该文件存在时会主动读取,并在 `recap_story_plan.json` 的可选字段 `reference_methods` 中逐条记录对每条方法的采纳决定(`adopt` / `adapt` / `skip`)。借鉴参考方法时始终以新素材的真实画面和台词为准,不要把参考片的切点密度或留白比例当成硬指标生搬硬套。后续做片脚本不会校验这份参考文件,也不会因为它的存在而改变任何检查结果。 `U/` 目录下的 `reference_breakdown.json` 与 `reference_frames/` 抽帧拼图包含原片剧情事实与画面,仅供本机拆片使用,切勿复制进新项目或提交到公共仓库。 ## 6. 能力边界 - 全程纯本地计算,不调用 MiMo 或任何大模型,不修改上游视频理解产物,也不给成片好坏打分或计算“新片与参考片的差距”。 - 镜头切点基于 ffmpeg `scdet` 分数加人工看图复核:慢速叠化转场无法被算法自动检出;间隔不足 `0.3` 秒的连续快切、卡在 `soft_score` 临界线上的切点(不同 ffmpeg 版本可能有微小浮点差异),以及剧烈运动后突入暗场的低分硬切,都不会直接算作自动切点,而是收进 `shots.review_windows` 交由 `frames --review` 人工看图确认。 - 旁白占比与语速属于 `labeled` 级别精度:由人工标注的音轨区间结合 ASR 分段转写估算得出,不等同于逐字对轴的时间戳。 - 防剧透泄漏扫描基于字面字符串比对,Agent 落笔时仍需主动自查,确保 `methods` 只写通用剪辑与叙事手法,不带入原片故事梗概。