Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(audio): surface voice cloning as a first-class capability

hugohe301406c285fc5
diff --git a/.env.example b/.env.example
index eb2c0e5d..c4a1f52e 100644
--- a/.env.example
+++ b/.env.example
@@ -133,9 +133,15 @@
# Audio narration TTS (notes_to_audio.py) / 旁白音频 TTS
# ─────────────────────────────────────────────────────────────
# edge-tts is the default narration backend and needs no API key.
-# Use cloud providers only when you want high-quality or cloned voices.
+# Use cloud providers only when you want high-quality or cloned voices —
+# all four (ElevenLabs / MiniMax / Qwen / CosyVoice) accept a cloned voice_id.
+# Clone the voice in the provider's console first, then pass --voice-id to
+# notes_to_audio.py. See docs/audio-narration.md "Use a cloned voice".
# edge-tts 是默认旁白后端,无需 API Key。
-# 需要高质量云端旁白或复刻音色时再配置云端提供商。
+# 需要高质量云端旁白或复刻音色时再配置云端提供商——
+# ElevenLabs / MiniMax / Qwen / CosyVoice 四家都支持传入复刻 voice_id。
+# 先在 provider 控制台复刻得到 voice_id,再用 --voice-id 传给 notes_to_audio.py。
+# 详见 docs/zh/audio-narration.md "使用复刻音色"。
#
# ELEVENLABS_API_KEY=your-elevenlabs-api-key
# MINIMAX_API_KEY=your-minimax-key
diff --git a/README.md b/README.md
index 4734b02d..55e62f4f 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,9 @@ Drop in a PDF, DOCX, URL, or Markdown — get back a **natively editable PowerPo
> **Animations** — exported decks support **page transitions** and **per-element entrance animations** as real OOXML, not embedded video. By default, elements cascade in automatically on slide entry — no clicking needed. Plays natively in PowerPoint and Keynote, no extra tooling. See [Animations & Transitions →](./skills/ppt-master/references/animations.md).
-> **Narration & Video** — generate per-slide voice narration from the speaker notes (`edge-tts` by default, optional cloud TTS providers for high-quality or cloned voices), embed the audio back into the PPTX, and let PowerPoint export the deck as an MP4 video — synced narration + transitions, no third-party tools. See [Audio Narration & Video Export →](./docs/audio-narration.md).
+> **Narration & Video** — generate per-slide voice narration from the speaker notes (`edge-tts` by default, optional cloud TTS providers for high-quality narration), embed the audio back into the PPTX, and let PowerPoint export the deck as an MP4 video — synced narration + transitions, no third-party tools. See [Audio Narration & Video Export →](./docs/audio-narration.md).
+>
+> **Voice Cloning** — bring your own cloned voice from ElevenLabs / MiniMax / Qwen / CosyVoice and have the entire deck narrated in *your* voice (or a presenter's, with permission). Clone once in the provider's console, then pass the `voice_id` — PPT Master reads every slide's notes in that voice and embeds the result back into the PPTX. See [Use a cloned voice →](./docs/audio-narration.md#use-a-cloned-voice).
> **How it works** — PPT Master is a workflow (a "skill") that works inside AI IDEs like Claude Code, Cursor, VS Code + Copilot, or Codebuddy. You chat with the AI — "make a deck from this PDF" — and it follows the workflow to produce a real editable `.pptx` on your computer. No coding on your side; the IDE is just where the conversation happens.
>
diff --git a/README_CN.md b/README_CN.md
index 62ac6474..e5b6aa5d 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -40,7 +40,9 @@
> **动画** —— 导出的 deck 支持**页间转场**和**页内元素入场动画**,输出为真正的 OOXML 动画(不是嵌入视频)。默认进入页面后元素按顺序自动级联入场,无需点击;在 PowerPoint 和 Keynote 中原生播放,无需额外工具。详见 [转场与动画使用指南 →](./docs/zh/animations.md)。
-> **旁白与视频** —— 把演讲者备注按页生成语音旁白(默认 `edge-tts`,也可配置云端 TTS 使用高质量或复刻音色),把音频嵌回 PPTX,再用 PowerPoint 自带"导出视频"产出带旁白和转场的 MP4,全程无需第三方工具。详见 [音频旁白与视频导出 →](./docs/zh/audio-narration.md)。
+> **旁白与视频** —— 把演讲者备注按页生成语音旁白(默认 `edge-tts`,也可配置云端 TTS 获得高质量音色),把音频嵌回 PPTX,再用 PowerPoint 自带"导出视频"产出带旁白和转场的 MP4,全程无需第三方工具。详见 [音频旁白与视频导出 →](./docs/zh/audio-narration.md)。
+>
+> **声音复刻** —— 用 ElevenLabs / MiniMax / Qwen / CosyVoice 复刻出你自己的声音(或在授权前提下复刻演讲者的声音),让整份 deck 用 *你的声音* 念出来。在 provider 控制台复刻一次,把得到的 `voice_id` 传进来,PPT Master 就会用这个音色逐页朗读备注并嵌入回 PPTX。详见 [使用复刻音色 →](./docs/zh/audio-narration.md#使用复刻音色)。
> **运作方式** —— PPT Master 是一套在 AI IDE(Claude Code / Cursor / VS Code + Copilot / Codebuddy 等)里运行的工作流(一个 "skill")。你在 IDE 的对话框里跟 AI 说"用这份 PDF 做一份 PPT",AI 按这套工作流在你本机生成一个真正可编辑的 `.pptx`。你不写任何代码——IDE 只是你和 AI 对话的地方。
>
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
index 3bfae87f..6831a227 100644
--- a/docs/audio-narration.md
+++ b/docs/audio-narration.md
@@ -95,6 +95,42 @@ python3 skills/ppt-master/scripts/notes_to_audio.py --provider elevenlabs --list
For MiniMax, Qwen, and CosyVoice, pass the provider-specific system voice or cloned voice ID/name with `--voice-id`. Voice cloning itself is performed in the provider's console/API first; `notes_to_audio.py` uses the resulting voice ID to generate per-slide narration.
+## Use a cloned voice
+
+Four cloud providers — **ElevenLabs**, **MiniMax**, **Qwen**, **CosyVoice** — let you clone a voice from a short sample and then synthesize new speech in that voice. PPT Master narrates the entire deck in your cloned voice as long as you can hand it a `voice_id`. (`edge` does not support cloning.)
+
+**The split of responsibilities**: voice cloning itself happens in the provider's console or API — you upload a sample (typically 10 s – a few minutes of clean audio) and the provider returns a `voice_id`. PPT Master is on the *consumption* side: it takes that `voice_id` and reads every slide's notes in that voice. PPT Master never uploads your sample anywhere.
+
+| Provider | Where to clone | Sample length |
+|---|---|---|
+| ElevenLabs | [elevenlabs.io](https://elevenlabs.io) → Voices → Add Voice → Instant / Professional Voice Cloning | 1 min (Instant) / 30 min+ (Professional) |
+| MiniMax | [platform.minimaxi.com](https://platform.minimaxi.com) → 语音克隆 (Voice Clone) | ~10 s – 5 min |
+| Qwen TTS | [DashScope console](https://dashscope.console.aliyun.com) → 语音合成 → 声音复刻 | ~10 s – 5 min |
+| CosyVoice | [DashScope console](https://dashscope.console.aliyun.com) → 语音合成 → 音色复刻 | ~10 s – 5 min |
+
+**How to use it after cloning** — in chat, just say so. The AI will skip the voice-recommendation step and use your `voice_id` directly:
+
+```
+You: 用 MiniMax 我克隆的音色生成旁白,voice_id 是 xxxxxxx
+You: Generate the narration with my cloned ElevenLabs voice id abc123
+```
+
+Or call the script directly:
+
+```bash
+python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
+ --provider minimax --voice-id <your-cloned-voice-id> \
+ --minimax-model speech-2.8-hd
+```
+
+Replace `--provider minimax` with `elevenlabs` / `qwen` / `cosyvoice` as needed; `--voice-id` accepts the cloned voice the same way it accepts a system voice.
+
+**Notes**:
+
+- **Authorization** — only clone voices you own or have explicit permission to use. Each provider's terms forbid impersonation.
+- **Language coverage** — the cloned voice inherits the speaker's accent. For multilingual decks (e.g. Chinese with English terms), pick a provider whose model handles your sample's language mix; ElevenLabs `eleven_multilingual_v2` and CosyVoice tend to be the most forgiving.
+- **One-time setup, reusable forever** — the `voice_id` doesn't expire. Clone once, narrate any number of decks.
+
## Dependency
```bash
diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.md
index 3bcc3898..801266b0 100644
--- a/docs/zh/audio-narration.md
+++ b/docs/zh/audio-narration.md
@@ -79,6 +79,42 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final \
edge 模式下 `--voice` 是必填项。云端 provider 使用 `--voice-id` 传入对应平台的系统音色或复刻音色 ID。声音复刻本身先在对应平台控制台/API 中完成,`notes_to_audio.py` 使用得到的 voice ID 生成逐页旁白。
+## 使用复刻音色
+
+四个云端 provider —— **ElevenLabs**、**MiniMax**、**Qwen**、**CosyVoice** —— 都支持用一段较短的音频样本复刻一个新音色,再用这个音色合成新语音。只要你能拿到 `voice_id`,PPT Master 就能用这个音色把整份 deck 念出来。(`edge` 不支持复刻。)
+
+**职责切分**:声音复刻本身在 provider 的控制台或 API 完成——你上传一段样本(一般 10 秒到几分钟的干净录音),平台给你返回一个 `voice_id`。PPT Master 在*消费*侧:拿到 `voice_id` 后用这个音色逐页朗读备注。PPT Master 不会把你的样本上传到任何地方。
+
+| Provider | 复刻入口 | 样本时长 |
+|---|---|---|
+| ElevenLabs | [elevenlabs.io](https://elevenlabs.io) → Voices → Add Voice → Instant / Professional Voice Cloning | 1 分钟(Instant)/ 30 分钟以上(Professional) |
+| MiniMax | [platform.minimaxi.com](https://platform.minimaxi.com) → 语音克隆 | 10 秒 – 5 分钟 |
+| Qwen TTS | [DashScope 控制台](https://dashscope.console.aliyun.com) → 语音合成 → 声音复刻 | 10 秒 – 5 分钟 |
+| CosyVoice | [DashScope 控制台](https://dashscope.console.aliyun.com) → 语音合成 → 音色复刻 | 10 秒 – 5 分钟 |
+
+**复刻完之后怎么用** —— 在聊天里告诉 AI 即可,AI 会跳过音色推荐环节直接用你的 `voice_id`:
+
+```
+你: 用 MiniMax 我克隆的音色生成旁白,voice_id 是 xxxxxxx
+你: 用我在 ElevenLabs 复刻的 voice id abc123 生成
+```
+
+也可以直接跑脚本:
+
+```bash
+python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
+ --provider minimax --voice-id <你的复刻 voice id> \
+ --minimax-model speech-2.8-hd
+```
+
+把 `--provider minimax` 换成 `elevenlabs` / `qwen` / `cosyvoice` 就能切到对应平台;`--voice-id` 接收复刻音色和接收系统音色的方式完全一样。
+
+**注意**:
+
+- **授权** —— 只复刻你自己拥有的、或拿到了明确授权的声音。每个 provider 的服务条款都禁止冒用他人声音。
+- **语言覆盖** —— 复刻出来的音色会继承说话人的口音。对中英混合等多语 deck,建议挑一个对你样本语言组合处理较好的 provider;ElevenLabs `eleven_multilingual_v2` 和 CosyVoice 通常最宽容。
+- **一次复刻、长期复用** —— `voice_id` 不过期。复刻一次,可以给任意多份 deck 配旁白。
+
## 依赖
```bash
diff --git a/skills/ppt-master/workflows/generate-audio.md b/skills/ppt-master/workflows/generate-audio.md
index 23a559f7..646a6f2c 100644
--- a/skills/ppt-master/workflows/generate-audio.md
+++ b/skills/ppt-master/workflows/generate-audio.md
@@ -78,6 +78,8 @@ For each candidate, write a **one-line Chinese description** covering: 性别 ·
Send a single message to the user that asks all three questions at once and provides a recommended value for each. Do NOT split into multiple rounds.
+**Cloned-voice fast path**: if the user mentioned a cloned voice / 克隆音色 / 复刻音色 / "my own voice" along with a `voice_id`, skip the voice-recommendation list — set the provider to whichever the user named (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`), pin the `voice_id` they gave you, and only confirm rate + embed-or-not.
+
**Message template** (Chinese; translate to user's chat language if different):
> 检测到 notes 主语言为 **<语言>**(locale: `<locale>`)。基于 deck 调性(<风格>),我推荐以下配置: