# Multi Voice Dubbing

多角色对话配音：按 cast 和逐行对白为不同角色分配音色与情绪，合成多声线音轨和带角色名字幕。...

- Repository: https://github.com/ZJU-REAL/Easel (4293 stars)
- Category: Media
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ZJU-REAL/Easel --skill multi-voice-dubbing -g -a claude-code -y`
Codex: `npx skills add ZJU-REAL/Easel --skill multi-voice-dubbing -g -a codex -y`
Cursor: `npx skills add ZJU-REAL/Easel --skill multi-voice-dubbing -g -a cursor -y`
Gemini CLI: `npx skills add ZJU-REAL/Easel --skill multi-voice-dubbing -g -a gemini-cli -y`

## Description

多角色对话配音：按 cast 和逐行对白为不同角色分配音色与情绪，合成多声线音轨和带角色名字幕。 当用户说“多角色/双人/剧本/对话配音、多人对白、不同角色不同声音、有声剧配音”时使用。 单一公共音色用 tts-voiceover；克隆本人音色用 voice-clone；整部短剧制作由 short-drama 编排。

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

# 多角色 / 对话配音（Multi-voice Dubbing）

把「多人对话 / 多角色脚本」合成为**多声线音轨**, , 每个角色一个符合其人设的声音，
不再是「全程一个声音」。核心引擎 `skills/shared/scripts/multivoice.py`：
逐行调 `tts.py`（edge-tts 免费多音色）或 `voice_clone.py`（云端表现力 provider / 克隆音色）合成，
把每行 emotion 喂进 provider 的**真情感通道**，`ffmpeg` 拼成一轨 + 生成对齐的说话人字幕。

> 创意（谁说什么、什么情绪）由你 LLM 产出；音色映射在 cast。确定性 IO（逐行合成/拼接/字幕）走引擎。
> 产物 `voice.mp3` 可直接当 narration 喂 `auto-short-video/assemble.py` 或加进任意视频；`voice.srt` 是带角色名的字幕。

## 配音质量分层（重要：治「像 AI 平读」）

**edge-tts 没有情感引擎**，只能变速变调，再怎么调也像机器平读。要"像人"必须用有情感通道的**云 provider**（用户自备 key，**无需 GPU**）：

| 引擎（cast 里 `engine`）| 质量 | 需要 | 情感机制 |
|---|---|---|---|
| `edge`（默认，免费兜底）| ⚠️ 平、机器感，仅供草稿 | 无 key、外网 | 仅 rate/pitch/volume 微调 |
| `clone`+`openai-compatible`→**SiliconFlow CosyVoice2**（推荐）| 好、中文自然 | VOICE_API_KEY（便宜/新用户赠额）| 内联 `<\|endofprompt\|>` 指令 |
| `clone`+`gemini` | 好、**真免费** | GEMINI_API_KEY（Google 免费层，国内需代理）| 自然语言前缀 |
| `clone`+`minimax` / `dashscope` | 好、有情绪 | 各家 key | emotion 枚举 / instruct |

**推荐 SiliconFlow**（云端 CosyVoice2、无需 GPU、中文最稳）配置落 `.env`：
```bash
VOICE_PROVIDER=openai-compatible
VOICE_BASE_URL=https://api.siliconflow.cn/v1
VOICE_API_KEY=<你的key>
VOICE_MODEL=FunAudioLLM/CosyVoice2-0.5B
VOICE_INSTRUCT_MODE=inline
```
cast 里角色：`--engine clone --provider openai-compatible --voice-id FunAudioLLM/CosyVoice2-0.5B:alex`（8 音色 alex/anna/benjamin/…）。

- **逐行 emotion 自动驱动演绎**：`lines.json` 每行的 `emotion`（愤怒/崩溃大哭/冷笑/温柔…）→ 引擎按 provider 转成对应情感参数。写具体越贴戏越好。
- 想要「像人」→ 至少给主角/关键角色配一个云 provider（`engine=clone`）；配了 key 才有情绪，没 key 自动回退 edge（平）并告警。
- provider 配置见 `voice_clone.py` 头部（各家 env）；`voice_clone.py check --provider <名>` 离线校验 key 是否齐。

## 谁会用到

短剧对白（short-drama 已内部委派）、**论文双人问答讲解**（paper-explainer：主讲+提问者）、
访谈/播客脚本、有声剧、任何「多个说话人」的口播。单人整段口播用 **tts-voiceover** 即可。

## 输入

| 字段 | 必填 | 说明 |
|------|------|------|
| cast.json | 是 | 选角表：每个说话人 → 音色（edge 音色 + pitch/rate，或克隆音色）。含「旁白/主讲」条目 |
| lines.json | 是 | 逐行对白：有序 `[{speaker, text, emotion}]`（speaker 用 cast 里的名字；emotion 如 冷/怒/紧张/温柔，自动匹配语气） |
| 输出路径 | 否 | voice.mp3（默认与调用方约定）；voice.srt 同名 |

The rest: https://github.com/ZJU-REAL/Easel/blob/HEAD/skills/builtin/multi-voice-dubbing/SKILL.md