video-voiceover

## 1. 定位 本技能读取带时间戳的旁白稿，为每一段生成独立音频，并把语音适配到对应时间窗，随后记录下游合成所需的放置元数据。 默认引擎是 MiMo TTS（`mimo-v2.5-tts`）；也可显式选择 Fish Audio（默认模型 `s2.1-pro-free`）。 ## 2. 环境要求 ```bash export MIMO_API_KEY=*** # 也可使用仅供 TTS 的 MIMO_TTS_API_KEY # 或改用 Fish Audio TTS export TTS_PROVIDER=fish-audio export FISH_API_KEY=*** export FISH_TTS_REFERENCE_ID=<voice-model-id> # 可选；覆盖内置“娱乐扒妹”音色 # 或显式选择自托管 index-tts 端点，配置见 references/index-tts.md export TTS_PROVIDER=index-tts ``` 下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。 ## 3. 输入契约 默认输入为 `work_dir/narration.json`。每段必须包含 `start`、`end` 与 `narration`，可选字段包括 `pause_after_ms` 和 `overlaps_speech`。时间统一表示音频最终放置的**输出时间线秒数**。 cut 流程先剪后配：`narration.json` 本身就是按剪后成片的输出时间写的，不存在另一份映射稿。 ## 4. 运行命令 ```bash python3 scripts/voiceover.py --work-dir <work_dir> --narration <narration.json> \ [--tts-provider auto|mimo-tts|fish-audio|index-tts] \ [--mimo-voice 冰糖 | --voice-ref <reference-audio>] \ [--preserve-approved-text] ``` 单独运行且省略 `--narration` 时，默认读取 `work_dir/narration.json`；`--narration` 只用于指定其他路径的同格式稿件。 ## 5. 输出契约 - `tts_segments/*.wav`：每段旁白对应一个音频文件。 - `tts_meta.json`：包含 `segments`、`engine` 与 `narration`。每段记录 `audio_path`、时间、 `pause_after_ms` 和放置字段。 - 干净运行写入 `partial: false` 与 `failures: []`。 - 使用 `--allow-partial-tts` 跳过失败段时，写入 `partial: true` 和 `failures: [{index,start,end,text,error}]`，让缺失语音保持可见。 - `--preserve-approved-text` 是显式的批准稿保护策略。每段保留原始 `authored_text` 证据；TTS 实际读取的 `spoken_text` 只经过既有的格式/舞台提示清理。若完整语音超过时间窗及 累计语速预算，命令失败并报告段序号、原稿、实读...