video-recap Checked

时间线有两条不可降级的硬约束：原声只能在可靠句末/静音边界被切入、切出或恢复；旁白必须使用

完整逐段音频，任何 clip 映射裁段、TTS 裁尾或剪映引用更长的加速前素材都阻断。Agent 收到

interrupts_source_sentence / unsafe_clip_sentence_boundary / no_safe_fit /

timeline_audio_mismatch 时，应移动边界、缩短整句或删除该块，而不是增加抢断 override。

### 4.3 多视频与素材库

多视频只支持 cut 模式。项目 brief 会列出稳定的 source_id，clip_plan.json 中每个片段都必须填写来源：

python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep

可选文件系统素材库：

python3 scripts/recap.py ep1.mp4 --material-library-dir .video-materials --save-materials
python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --material-library-dir .video-materials --use-materials

素材检索只是对 JSON / MD / JSONL 做 grep，例如 grep -R "keyword" .video-materials。当前版本不复制原始媒体，也不提供数据库、向量或语义搜索。

### 4.4 继续生成成片

写好所需产物后，重复同一条命令：

python3 scripts/recap.py <video> --work-dir <work_dir>  # 可追加 --edit-mode cut / --no-burn-subtitles

流程会校验当前阶段的硬输入（clip_plan.json / narration.json）；两份创作计划仍是 Agent 与建议型评审使用的工作记录，不是渲染门禁。cut 模式随后生成 edited_source.mp4，再合成旁白并输出 recap_<name>.mp4。

若需要建议型 MiMo 复核：

python3 scripts/recap.py <video> --work-dir <work_dir> --mimo-qc both

合成前复核会读取脚本、计划和 TTS 元数据；成片后还会读取最多六张临时 JPEG。相同输入命中内容缓存，--mimo-qc-refresh 可强制刷新。帧的 base64 与凭证不会写入磁盘。

### 4.5 字幕与克隆旁白

若要把旁白字幕固定在原片字幕区域，先在仓库根目录运行：

python3 tools/measure_subtitle.py <video>

再传入测得的 --subtitle-y-top/--subtitle-y-bot。坐标基于 ffmpeg 自动旋转后的显示画布，区间为半开 [top, bot)，并要求底对齐 ASS 样式；显式设置后，该区域默认使用 60% 透明度的旁白窗口遮罩。

解说模式如需克隆参考声音，使用 --voice-ref <audio>；它与 dub 模式不同。

### 4.6 最终观看与交付复核

脚本、接点检测、样帧和 QC 报告都不能替代观看。每轮准备交付前，必须检查**本轮实际要交付的最终文件**，而不是旧别名、无字幕母版或中间代理：

1. 正常速度完整播放一次短片，不边看边改；先记录真实观看问题。

2. 播放每个拼接点前后约 0.5–1 秒，检查闪帧、原片叠化被截断、动作跳变和半句原声。

3. 完整只听声音一次，检查旁白是否碎成一句一停、场景间声音是否接得上、关键原声是否完整。

4. 单独复看开头、核心情绪/表演点和结尾，确认进入时机、回报停留和收束都成立。

5. REVISION 分别验证本轮修改项已经改变、冻结项没有意外变化；然后再做解码、时长、音画规格等机械检查。

scene score、亮度统计、contact sheet 与自动 QC 只负责定位候选问题；最终判断以真实播放为准。短时间内出现密集候选时，必须判断每个切点来自原片还是本次拼接：原片无关短镜头整段删，相关短镜头扩展到完整动作/反应；人工拼接点优先移动边界、恢复同源连续运动或合并片段，能消除就不保留。修复失败时回到剪点、声音或文案层，不用更多包装掩盖。

5. 英译中原声复刻模式

--edit-mode dub 把英文视频翻译为中文，并用原说话者的克隆音色替换人声；它不是在压低原声上叠加解说。

python3 scripts/recap.py <video> --edit-mode dub --work-dir <work_dir>

准备阶段会转写英文、提取一段参考音频，并写出 dub_brief.md 与 dub_transcript.json。Agent 随后写：

[{"start": 0.0, "end": 2.0, "zh": "中文译文"}]

要求：

• 逐句忠实翻译，不删钩子、不合并、不擅自压缩；原文重复，译文也按时间重复。
• 每句沿用原声 [start, end]，相邻句不重叠。
• 译文尽量控制在约 5 字/秒，使其能在原时间窗内说完。

重复同一命令后输出 dub_<name>.mp4。每句单独克隆并贴回原时间线；只有即将覆盖下一句时才局部加速。当前版本只支持单说话者、整轨替换，不分离背景音乐。

6. 自检命令

python3 scripts/recap.py --doctor

7. 输出与参数

主要输出：

• recap_<video>.mp4：最终成片。
• subtitles.srt / subtitles.ass：字幕。
• work_dir/：全部中间产物，契约见 references/data-schema.md。
• work_dir/recap_story_plan.json / visual_audio_board.json：Agent 创作意图与剪辑决定。
• work_dir/mimo_qc.json：可选的建议型复核，不作为发布门禁。

可透传参数：

--context、--scene-threshold、--style、--edit-mode {full,cut,dub}、--target-duration、

--skip-asr、--mimo-video-overview、--mimo-qc {off,pre-assemble,post-render,both}、

--mimo-qc-refresh、--consolidate、--consolidate-asr、--tts-provider、--mimo-tts-voice、--voice-ref、

--allow-partial-tts、--review-narration、--no-review-narration、--require-narration-review、

--subtitle-y-top、--subtitle-y-bot、--no-burn-subtitles、--output-dir、

--export-jianying、--jianying-bundle-media、--jianying-no-bundle-media、

--material-library-dir、--use-materials、--save-materials。

--style 是原样传给 Agent 的自由文本指导，不是 preset、枚举、开关或有限风格分类。

8. 能力边界

• 编排器不代替 Agent 写 narration.json / clip_plan.json；具体写作遵循创作 brief 与写作阶段契约。
• 语义评审默认建议型、失败开放；只有调用方显式启用严格解说评审时，事实矛盾、残句或评审不可用才会在 TTS 前阻断。确定性校验阶段始终负责硬校验。
• MiMo QC 不能阻断、自动修复或改变退出状态，只提供定位建议。
• 建立内容质量基线不依赖平台分析、留存遥测或发布接入。
• 本技能不是无人值守调度器，不会向任何平台发布内容。
• 各阶段技能不共享代码，只通过 work_dir 产物通信。