/video-recap

name: video-recap
description: 从输入视频一气呵成生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm，并要求剪辑、添加旁白、配音、总结或制作短剧/电视剧/电影/纪录片/科普解说时使用。在同一个自包含技能内完成视频理解、导演立意与选镜剪辑、解说撰稿与校验、TTS 配音及音画混音合成。触发词：视频解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。

1. 定位与流程

本技能是自包含的视频解说与剪辑生产技能，将视频理解、故事立意、画面剪辑、旁白撰稿、配音合成与音画混音收敛在同一条连贯工作流中，各阶段共享同一工作目录 `work_dir` 下的 JSON 与 MP4 产物：

understand.py（视频理解）─▶ Agent 制定故事/声画方案并写 clip_plan.json 或 narration.json ─▶ [cut.py（剪辑与重出简报）] ─▶ validate.py（本地底线校验）─▶ voiceover.py（TTS 配音）─▶ assemble.py（混音与字幕渲染）

日常使用可直接调用总入口 `scripts/recap.py` 自动串联全流程并在创作节点暂停，也可按需单独调用本技能 `scripts/` 下的单阶段入口（`understand.py`、`cut.py`、`validate.py`、`voiceover.py`、`assemble.py`）。

把现有成片拆解为制作参考（`production_reference.json`）不在默认生产链上。当用户要求拆片学习时：先对样片跑 `understand.py`（建议设 `ASR_SEGMENT_SECONDS=5`），再用独立的拆片技能依次执行测量（`measure`）、标注、校验（`check`）与导出（`export`），将导出的 `production_reference.json` 复制进下一轮运行的 `work_dir`，或登记为资源库里的 `production_reference` 模板并经 `--project` 绑定。主流程不会自动跑拆片，也不拿新成片去跟参考片做机械比对。

全流程支持断点续跑：Agent 写完 `clip_plan.json` 或 `narration.json` 后，重跑同一条 `recap.py` 命令即可往下走。续跑时脚本会核对 `recap_run_manifest.json` 中记录的源视频路径、文件大小、修改时间及运行参数，一旦发现工作目录来自其他视频或不同参数组合会直接拒绝复用；视频理解缓存也只在源片与配置完全一致时命中。每次暂停时终端打印的续跑命令保留了原始调用写法，并自动把视频与路径参数转为绝对路径、补齐 `--work-dir`，复制粘贴到任意目录都能直接跑。

画面流程 `--edit-mode full|cut` 与声音策略 `--audio-mode narration|source-mix` 相互独立：`narration` 走标准解说配音链，`source-mix` 不生成配音而直接混入原声与可选配乐。系统仅支持下表列出的五条合法路线，其余组合在启动时直接报错拦截：

| 输入 | `--edit-mode` | `--audio-mode` | Agent 暂停点 | 流程 | 详见 | |---|---|---|---|---|---| | 单视频 | full | narration | 1 次：写 `narration.json` | 理解 → 写稿 → 校验 → 配音 → 合成 | §4 | | 单视频 | cut | narration | 2 次：先写 `clip_plan.json`，剪完再对成片写 `narration.json` | 理解 → 剪辑 → 重出输出时间简报 → 写稿 → 校验 → 配音 → 合成 | §4 | | 多视频 | cut | narration | 2 次：同上，且每条片段必须带 `source_id` | 逐源理解 → 剪辑 → 写稿 → 校验 → 配音 → 合成 | §4.5 | | 单视频 | full | source-mix | 无暂停 | 直接合成当前整段视频（不跑理解或 TTS） | §4.7 | | 单 / 多视频 | cut | source-mix | 1 次：写 `clip_plan.json` | 理解 → 剪辑 → 合成（不写旁白） | §4.7 |

2. 创作职责

创作拍板权完全归 Agent。动笔前先判断本轮的**创作控制模式**（`CREATE` 开放创作 / `DIRECTED` 定向创作 / `REVISION` 定稿返修，与 `--edit-mode` 独立），并在进入配音和渲染前作为同一个创作大脑一气呵成完成五项判断：

1. **导演判断**：明确观众点进来看什么、全程跟谁的视角（POV）走、核心悬念是什么、情绪从哪儿起到哪儿落，以及哪张底牌留到最后掀开。 2. **故事编辑**：每一拍（beat）都必须交代“局势发生了什么实质转折”，绝不写流水账式的场景摘要。 3. **画面剪辑**：挑出最扎人的动作、变脸反应与最佳入出点，砍掉拖泥带水的过场。 4. **声音/旁白**：先定每一拍由画面、原声对白、动作声、沉默还是旁白当家，再按“垫半句、让半句、接半句”动笔写词。 5. **观众复核**：站在第一次点进来的观众视角，分别做关旁白看画面、闭眼纯听声音和首尾兑现自检。

三种控制模式的分工、REVISION 下的锁定不回退规则、具体剪辑与写作技法，以及 `recap_story_plan.json`、`visual_audio_board.json`、`style_card.json` 的格式规范详见 `references/creative-editing-playbook.md`。这些 JSON 用来沉淀可复查的创作决定，确保选镜、原声留白与解说词从头到尾咬住同一个故事意图。

3. 环境与远程调用说明

# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
export MIMO_API_KEY=***

同一个 `MIMO_API_KEY` 即可驱动默认全链路。为保证数据流向透明，本技能涉及远程网络调用的环节说明如下：

• **视频理解（`understand.py`）**：将切分后的音频窗口发往 MiMo ASR（`mimo-v2.5-asr`），将抽帧 JPEG 连同 `background_research.json` 摘要发往 MiMo VLM（`mimo-v2.5`）。若工作目录已有完整分析产物，传 `--brief-only` 或 `--edited-storyboard-only` 则纯本地运行、不发起任何网络请求。
• **旁白配音（`voiceover.py`）**：按 `--tts-provider`（默认 `auto` 优先选已配置的 MiMo，其次 Fish Audio，绝不自动选 `index-tts`）将解说文本发往对应 TTS 服务：
• `mimo-tts`：发往 MiMo TTS（`mimo-v2.5-tts`）；若显式传了 `--voice-ref <audio>`，还会将该参考音频切片发往 `mimo-v2.5-tts-voiceclone`（使用前请确认已获声音授权）。
• `fish-audio`：需配置 `FISH_API_KEY`，将每段解说文本与 `FISH_TTS_REFERENCE_ID` 发往 `FISH_TTS_API_URL`（默认 `https://api.fish.audio/v1/tts`）。
• `index-tts`：仅在显式指定 `--tts-provider index-tts` 时启用，将文本与 `INDEX_TTS_VOICE` 发往用户自建的 `INDEX_TTS_ENDPOINT`（详见 `references/index-tts.md`）。
• **解说校验（`validate.py`）、视频剪辑（`cut.py`、`shot_review.py`）与音画合成（`assemble.py`）**：纯本地确定性逻辑与 `ffmpeg` / `ffprobe` 调用，不发起任何网络请求。

以 `tp-` 开头的 Token Plan 密钥默认发往中国区集群，可通过 `MIMO_TOKEN_PLAN_CLUSTER` 切换集群。全量配置项见 `references/config-playbook.md`，所有中间产物格式见 `references/data-schema.md`。下文中的 `scripts/...` 均相对于本技能目录。

4. 一气呵成的创作与剪辑流程

4.1 背景调研与视频理解

只要能从文件名或用户指令里认出片名、剧集名或科普主题，开跑前先按 `references/research-guide.md` 查清人物关系与前情，写入 `work_dir/background_research.json`。这样后续跑画面分析时就能直接叫准角色姓名、看懂潜台词，不会满屏只写出“黑衣男子”“年轻女子”。多视频连剪时同样写在项目根 `work_dir` 下，脚本会自动同步到各源子目录 `sources/<source_id>/`。

随后启动理解与编排入口：

python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"

脚本完成音频提取、静音与句末停顿锚点检测（`speech_boundary_anchors.json`）、场景切分、VLM 帧分析与 ASR 转写后，生成故事板拼图 `storyboard/storyboard_*.jpg` 与创作简报 `agent_narration_brief.md` 并自动暂停。

4.2 导演意图与选镜计划（cut 第一阶段）

通读 `agent_narration_brief.md` 并直接查看故事板抽帧图片后，先写 `recap_story_plan.json`（至少列出 2 个候选方案并选定主视角 POV、开场钩子、情绪弧线与留白底牌）与 `visual_audio_board.json`（逐拍明确选哪个瞬间、为何进出、声音谁当家）。

在 `cut` 模式第一阶段，接着编写基于**原片时间轴（SOURCE）**的 `work_dir/clip_plan.json`（此时还不写 `narration.json`）：

{
  "target_duration": "3m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | knowledge: unknown→threat | POV=沈曼 | 撞见未婚夫搂着千金谈联姻 | 入点=推门看清两人动作 | 出点=转身攥紧户口本"
    }
  ],
  "required_evidence": {
    "nodes": [
      {"id": "e1", "source": "/abs/source.mp4", "start": 14.2, "end": 18.6, "track": "video", "content": "推门撞见两人拥抱"}
    ],
    "before": []
  }
}

选镜与切点必须严守以下底线：

• **`reason` 七段式结构**：依次写明 `beat_id | 叙事功能 | 局势状态变化（A→B） | POV=人物 | 本段实质看点 | 入点=具体动作/原声锚点 | 出点=具体反应/落点`，倒逼每段画面都服务于故事推进。
• **必保画面与原声证据（`required_evidence`）**：拍板决定必须留住的高光动作、变脸瞬间或关键原声问答，写入顶层 `required_evidence`（`nodes` 登记 `id`/`source` 绝对路径/`start`/`end`/`track`/`content`，`before` 登记不可颠倒的先后对）；边界吸附一旦裁掉任何必保区间或打乱先后顺序，脚本会直接报错阻断。
• **开场晚进场与镜头取舍**：默认按时间顺序“晚进场”（直接从冲突爆发、荒诞反差或关键动作切入，砍掉推门进屋、寒暄起势等慢热铺垫）；仅当正序冲突出现过晚时才允许摘 `<= 2.5s` 的冷开场悬念镜，且必须做到不铺垫也能看懂、不与正片重复同一机位画面、只留悬念绝不提前剧透反转结果。旁白压低原声时，优先选听者变脸反应、动作细节或稳态镜头，避免把角色正脸滔滔不绝张嘴却被消音的画面垫在旁白底下；同款点头或呆看反应镜不重复超过两次。
• **句末安全切点与呼吸尾垫**：切点必须落在原片首尾、句末停顿锚点或静音窗口内，或者属于同源相邻片段无缝顺接；吸附句末时会自动在停顿窗口内预留最多 `0.30s` 反应/呼吸气口且绝不跨越硬切点，片段最短时长不低于 `0.8s`。片尾最后一拍必须在结局动作或台词落定后留出 `1.5–2.5s` 表情余韵，并在跨入下一场前干净收尾。踩进原声台词中间会触发 `unsafe_clip_sentence_boundary` 阻断并给出 `nearest_safe`；若回退硬切吸附会同时暴露 `<= 0.20s` 闪帧与截断台词，则直接报 `shot_speech_conflict` 阻断。
• **高频快切与碎镜头排查**：`cut.py` 渲染 `edited_source.mp4` 后会自动调用 `shot_review.py` 生成 `shot_review.json`，并对时长 `<= 0.20s`（约 1–5 帧）的极短残镜