# Video Voiceover

把带时间戳的 narration.json 合成为中文解说音频。使用 MiMo TTS（mimo-v2.5-tts）或 Fish...

- Repository: https://github.com/zenstory-ai/video-recap-skills (601 stars)
- Category: Media
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add zenstory-ai/video-recap-skills --skill video-voiceover -g -a claude-code -y`
Codex: `npx skills add zenstory-ai/video-recap-skills --skill video-voiceover -g -a codex -y`
Cursor: `npx skills add zenstory-ai/video-recap-skills --skill video-voiceover -g -a cursor -y`
Gemini CLI: `npx skills add zenstory-ai/video-recap-skills --skill video-voiceover -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add zenstory-ai/video-recap-skills`

## Description

把带时间戳的 narration.json 合成为中文解说音频。使用 MiMo TTS（mimo-v2.5-tts）或 Fish Audio（s2.1-pro-free）或显式配置的通用 IndexTTS HTTP 服务逐段生成语音， 按时间窗动态适配语速并处理响度；输入输出时间线上的旁白，产出 tts_segments 与 tts_meta.json。 外发说明：每段旁白文字会发给所选 TTS 服务（MiMo / Fish Audio / 用户自托管的 IndexTTS），--voice-ref 的参考音频会发给 MiMo。 另含实验性的英译中 dub 路径：只在显式选择 dub 模式并传 --confirm-voice-rights 时运行，会把源视频音频发到 MiMo ASR， 并以原说话人的声音为参考经 MiMo voiceclone 克隆配音；只可用于用户有权使用、且说话人同意被克隆声音的内容。 触发词：配音、语音合成、TTS、解说配音、 voiceover、text to speech、旁白配音。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## 1. 定位

本技能读取带时间戳的旁白稿，为每一段生成独立音频，并把语音适配到对应时间窗，随后记录下游合成所需的放置元数据。
默认引擎是 MiMo TTS（`mimo-v2.5-tts`）；也可显式选择 Fish Audio（默认模型 `s2.1-pro-free`）。

## 2. 远程服务与数据外发

本技能按所选 TTS 或 dub 路径联网。表中的实读文本指 `narration.json` 段落去掉格式与舞台提示后的文字。

| 路径 | 服务与凭据 | 发送内容 |
|------|------------|----------|
| 默认解说 TTS（`--tts-provider auto\|mimo-tts`） | MiMo chat 接口 `<MIMO_TTS_API_URL 或 MIMO_API_URL>/chat/completions`，`MIMO_TTS_API_KEY` 或 `MIMO_API_KEY`，模型 `mimo-v2.5-tts` | 每段实读文本、一句自然语言语气/语速指令（由段的 `emotion` 与时间窗算出）、内置音色名（默认 `冰糖`）；`auto` 下 MiMo key 缺失且设置了 `FISH_API_KEY` 时改走 Fish Audio 行 |
| 解说声音克隆（`--voice-ref <audio>` / `VOICE_REF`） | 同上，模型 `mimo-v2.5-tts-voiceclone` | 上述内容，外加参考音频（转成 24 kHz 单声道 WAV，最长 30 秒）的 base64，每段请求都带 |
| Fish Audio（`--tts-provider fish-audio`） | `FISH_TTS_API_URL`（默认 `https://api.fish.audio/v1/tts`），`FISH_API_KEY` | 每段实读文本、数值语速、音色 ID `FISH_TTS_REFERENCE_ID`；不发送本地音频 |
| 自托管 IndexTTS（`--tts-provider index-tts`） | 用户自己部署、由 `INDEX_TTS_ENDPOINT` 指定的 HTTP(S) 服务 | `{"voice": INDEX_TTS_VOICE, "text": 实读文本}`；不发送本地音频 |
| 实验性 dub（见 §8） | MiMo ASR（`MIMO_API_URL`，`MIMO_API_KEY`，`mimo-v2.5-asr`）与 MiMo voiceclone（TTS 接口与凭据，`mimo-v2.5-tts-voiceclone`） | 源视频整条音轨按 6 秒分窗送 ASR；每句中文译文连同从源音频截取的约 10 秒原说话人声音（克隆参考）送 voiceclone |

`--voice-ref` 与 dub 都会把一个真实人物的声音发给 MiMo 用于克隆：只在用户有权使用该音频、且声音主人同意被克隆时使用。

## 3. 环境要求

```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/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。

## 4. 输入契约

默认输入为 `work_dir/narration.json`。每段必须包含 `start`、`end` 与 `narration`，可选字段包括
`pause_after_ms` 和 `overlaps_speech`。时间统一表示音频最终放置的**输出时间线秒数**。

cut 流程先剪后配：`narration.json` 本身就是按剪后成片的输出时间写的，不存在另一份映射稿。

## 5. 运行命令

The rest: https://github.com/zenstory-ai/video-recap-skills/blob/HEAD/skills/video-voiceover/SKILL.md