--- name: video-recap description: 从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm,并要求剪辑、添加旁白、配音、总结或制作短剧/电视剧/电影/纪录片/科普解说时使用。在同一个自包含技能内完成视频理解、导演立意与选镜剪辑、解说撰稿与校验、TTS 配音及音画混音合成。触发词:视频解说、视频旁白、生成解说、视频 recap、video recap、voiceover、narration、recap。 --- ## 1. 定位与流程 本技能是自包含的视频解说与剪辑生产技能,将视频理解、故事立意、画面剪辑、旁白撰稿、配音合成与音画混音放在同一工作目录 `work_dir` 下串联完成: ```text 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`),再用独立的拆片技能执行测量、标注、校验与导出,将导出的 `production_reference.json` 放入下一轮运行的 `work_dir`,或登记为资源库里的 `production_reference` 模板并经 `--project` 绑定。主流程不会自动拆片,也不拿新成片与参考片做机械打分比对。 全流程支持断点续跑:写完 `clip_plan.json` 或 `narration.json` 后重跑同一条 `recap.py` 命令即可继续。续跑时脚本会核对 `recap_run_manifest.json` 记录的源视频身份与参数,若工作目录来自其他视频或不同参数组合会拒绝复用;暂停时终端打印的续跑命令已将路径转为绝对路径并补齐 `--work-dir`。 画面流程 `--edit-mode full|cut` 与声音策略 `--audio-mode 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`。 ## 3. 环境与远程调用说明 ```bash # 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.6-flash`,可通过 `MIMO_MODEL` 切换 `mimo-v2.6-pro` 等)。若工作目录已有完整分析产物,传 `--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