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: add audio narration & video export guide

hugohe3cd87e295e4ee
diff --git a/README.md b/README.md
index 19c8242b..43da57a8 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,8 @@ 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 (90+ locales via `edge-tts`), 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).
+
> **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.
>
> **What you'll do**: install Python, install an AI IDE, drop in your material.
@@ -239,6 +241,7 @@ Multiple backends are supported across Core / Extended / Experimental tiers. Run
| 🎨 | [Create a Custom Template](./skills/ppt-master/workflows/create-template.md) | Standalone workflow for building your own brand or industry template |
| 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats |
| 🎬 | [Animations & Transitions](./skills/ppt-master/references/animations.md) | Page transitions and per-element entrance animations |
+| 🎙️ | [Audio Narration & Video Export](./docs/audio-narration.md) | TTS narration in 90+ locales, embed audio, export as MP4 |
| 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands |
| 💼 | [Examples](./examples/README.md) | 22 projects, 309 pages |
| 🏗️ | [Technical Design](./docs/technical-design.md) | Architecture, design philosophy, why SVG |
diff --git a/README_CN.md b/README_CN.md
index f0b39412..2e26b046 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -40,6 +40,8 @@
> **动画** —— 导出的 deck 支持**页间转场**和**页内元素入场动画**,输出为真正的 OOXML 动画(不是嵌入视频)。默认进入页面后元素按顺序自动级联入场,无需点击;在 PowerPoint 和 Keynote 中原生播放,无需额外工具。详见 [转场与动画使用指南 →](./docs/zh/animations.md)。
+> **旁白与视频** —— 把演讲者备注按页生成语音旁白(基于 `edge-tts`,支持 90+ 语种 locale),把音频嵌回 PPTX,再用 PowerPoint 自带"导出视频"产出带旁白和转场的 MP4,全程无需第三方工具。详见 [音频旁白与视频导出 →](./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 对话的地方。
>
> **你要做的**:装 Python、装一个 AI IDE、把资料放进来。
@@ -243,6 +245,7 @@ OPENAI_MODEL=gpt-image-2
| 🎨 | [创建自定义模板](./skills/ppt-master/workflows/create-template.md) | 独立工作流,构建你自己的品牌或行业模板 |
| 📐 | [画布格式](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9、小红书、朋友圈等 10+ 种格式 |
| 🎬 | [转场与动画](./docs/zh/animations.md) | 页间转场和页内元素入场动画 |
+| 🎙️ | [音频旁白与视频导出](./docs/zh/audio-narration.md) | 90+ 语种 TTS 旁白、音频嵌入 PPTX、导出为 MP4 |
| 🛠️ | [脚本与工具](./skills/ppt-master/scripts/README.md) | 所有脚本和命令 |
| 💼 | [示例](./examples/README.md) | 22 个项目,309 页 |
| 🏗️ | [技术路线](./docs/zh/technical-design.md) | 架构、设计哲学、为什么选 SVG |
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
new file mode 100644
index 00000000..619b6a6e
--- /dev/null
+++ b/docs/audio-narration.md
@@ -0,0 +1,91 @@
+# Audio Narration & Video Export
+
+PPT Master can turn the speaker notes into per-slide MP3 narration via [`edge-tts`](https://github.com/rany2/edge-tts) (Microsoft Edge's online neural voices), embed the audio back into the PPTX, and let PowerPoint export the deck as an MP4 video — with synced narration and slide transitions, no extra tools.
+
+## What you get
+
+- One MP3 per slide under `<project_path>/audio/`, named to match the SVG (`01_cover.mp3`, `02_market_landscape.mp3`, …).
+- Optional re-export: a new PPTX in `exports/` with each MP3 embedded into the matching slide and slide auto-advance timings set to the audio length, so kiosk/auto-play and video export work without manual timing.
+- The original speaker notes are preserved.
+
+## How it works
+
+1. **Speaker notes are written as pure spoken narration.** PPT Master's notes spec deliberately produces TTS-friendly prose — no bracketed stage markers, no `Key points:` / `Duration:` meta-lines — so what is read aloud is exactly what's on the page.
+2. **AI picks the voice for you.** When you ask for narration, the AI checks the deck's primary language (`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …), pulls the locale-filtered `edge-tts` voice catalog, and recommends 3–6 candidates with a one-line tone description for each (e.g. "稳重男声,适合财报"). It also recommends a speaking rate based on notes density.
+3. **One question, one answer.** You are asked once — voice, rate, and "embed audio back into PPTX (yes/no)" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.
+4. **Generation runs.** The script writes MP3s to `audio/`, then (if you kept embedding) re-exports the deck with audio attached.
+
+The full step-by-step is in [`workflows/generate-audio.md`](../skills/ppt-master/workflows/generate-audio.md).
+
+## Triggering it
+
+Just say so in chat after the deck has been exported:
+
+```
+You: 给这个 PPT 生成音频
+You: Generate narration for this deck and re-export with audio embedded.
+You: Add Japanese voice narration; pick a calm female voice.
+```
+
+The AI handles the rest.
+
+## Languages
+
+Anything `edge-tts` supports — roughly 90 locales including all major Chinese variants (`zh-CN` / `zh-TW` / `zh-HK` Cantonese), English (US/UK/AU/IN), Japanese, Korean, French, German, Spanish, Portuguese, Russian, Arabic, etc. List voices for any locale yourself with:
+
+```bash
+python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale ja-JP
+```
+
+## Manual usage (advanced)
+
+If you want to skip the AI flow and call the script directly:
+
+```bash
+# 1. Make sure speaker notes are split (post-processing Step 7.1):
+python3 skills/ppt-master/scripts/total_md_split.py <project_path>
+
+# 2. Generate MP3s
+python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
+ --voice zh-CN-YunjianNeural --rate +0%
+
+# 3. (Optional) Re-export PPTX with audio embedded
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final \
+ --recorded-narration audio
+```
+
+`--voice` is required — the script will error out if you forget it. Use `--list-voices --locale <locale>` to see what's available.
+
+## Dependency
+
+```bash
+python3 -m pip install edge-tts
+```
+
+Already listed in `skills/ppt-master/requirements.txt`. `edge-tts` calls Microsoft's online TTS service — an internet connection is required at generation time. The MP3s themselves are local files; nothing about playback or PowerPoint export depends on the network afterwards.
+
+## Tips
+
+- **Pacing**: PPT Master's default speaker-notes are 2–5 sentences per slide; `+0%` rate sounds natural. If a deck is very dense (long technical paragraphs), try `-5%`.
+- **Mid-deck regeneration**: change a single slide's `notes/<page>.md`, re-run `notes_to_audio.py` (it overwrites all MP3s, so re-run for the whole deck — the cost is small).
+- **Mixed-language decks** (Chinese with English technical terms etc.): `edge-tts` neural voices handle the embedded foreign words reasonably well in most locales — pick the dominant language voice and try one slide first.
+
+## Export as video
+
+Once the narrated PPTX is in `exports/`, PowerPoint exports it as a video natively — no third-party tool needed. The embedded audio plays as each slide's narration, and the per-slide auto-advance timings (set from audio length when you let the AI re-export with `--recorded-narration audio`) drive the video's pacing.
+
+**PowerPoint (Windows / Mac, Office 2016+)**:
+
+1. Open the narrated `.pptx` from `exports/`.
+2. **File → Export → Create a Video**.
+3. Pick a quality (4K / Full HD / HD / Standard) and "Use Recorded Timings and Narrations" — PPT Master has already set both for you.
+4. **Create Video** → save as `.mp4` (or `.wmv` on Windows).
+
+**Keynote (Mac)**: open the deck → **File → Export To → Movie…** — Keynote also honors embedded audio and per-slide timings, output `.m4v` / `.mov`.
+
+**Tips**:
+
+- **No mic, no recording session needed** — the audio is generated, not recorded, so re-runs are deterministic.
+- **Animations are preserved** — page transitions and per-element entrance animations from PPT Master are real OOXML and play correctly in the exported video. See [Animations & Transitions](../skills/ppt-master/references/animations.md).
+- **Want to tweak just one slide's audio?** Edit `notes/<page>.md`, re-run `notes_to_audio.py` and the embedding step, then re-export the video — total turnaround is usually under a minute per slide.
+- **File size**: a 20-page deck at Full HD typically lands at 30–80 MB depending on imagery. Drop to HD if you need a smaller file for sharing.
diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.md
new file mode 100644
index 00000000..e52940c7
--- /dev/null
+++ b/docs/zh/audio-narration.md
@@ -0,0 +1,93 @@
+# 音频旁白与视频导出
+
+PPT Master 可以把演讲者备注转成逐页 MP3 旁白(基于 [`edge-tts`](https://github.com/rany2/edge-tts) —— 微软 Edge 的在线神经网络语音),再把音频嵌入回 PPTX,由 PowerPoint 自带的"导出视频"一键产出带旁白和转场的 MP4,全程无需第三方工具。
+
+## 你会得到什么
+
+- 每页一个 MP3 文件,存放于 `<project_path>/audio/`,文件名与 SVG 对齐(`01_cover.mp3`、`02_market_landscape.mp3` …)。
+- 可选重新导出:在 `exports/` 生成新版 PPTX,每页对应的 MP3 已嵌入到该页,且页面切换时间按音频长度自动设置——无人值守自动播放和视频导出都不用再手动调时间。
+- 演讲者备注原样保留。
+
+## 它是怎么做到的
+
+1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。
+2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)拉取该 locale 下的 `edge-tts` 音色清单,挑出 3–6 个候选并给每个写一句中文调性说明(如"稳重男声·适合财报")。语速也会基于 notes 信息密度给出推荐值。
+3. **一次问完,一次回答**。AI 在一条消息里同时问三件事——音色、语速、是否把音频嵌入回 PPTX——每项都标了推荐值。回"好"接受全部默认,或者只说要改的部分(如"音色 2,语速 -5%")。
+4. **执行**。脚本写出 MP3 到 `audio/`,再(如果你保留嵌入)重新导出带音频的 PPTX。
+
+完整流程见 [`workflows/generate-audio.md`](../../skills/ppt-master/workflows/generate-audio.md)。
+
+## 怎么触发
+
+deck 导出后,在聊天里直接说就行:
+
+```
+你: 给这个 PPT 生成音频
+你: 帮我用日语给这个 deck 配一个温柔女声的旁白
+你: Generate narration for this deck and re-export with audio embedded.
+```
+
+剩下的 AI 全包。
+
+## 支持的语言
+
+凡是 `edge-tts` 支持的 locale 都行——大约 90 个,覆盖中文全部主要变体(`zh-CN` 普通话 / `zh-TW` 台湾普通话 / `zh-HK` 粤语)、英文(美/英/澳/印)、日语、韩语、法语、德语、西班牙语、葡萄牙语、俄语、阿拉伯语等。任何 locale 的全量音色清单都可以这样查:
+
+```bash
+python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale ja-JP
+```
+
+## 进阶:手动调用脚本
+
+如果你想跳过 AI 流程直接跑命令:
+
+```bash
+# 1. 确保备注已切分(后处理 Step 7.1)
+python3 skills/ppt-master/scripts/total_md_split.py <project_path>
+
+# 2. 生成 MP3
+python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
+ --voice zh-CN-YunjianNeural --rate +0%
+
+# 3.(可选)重新导出 PPTX 嵌入音频
+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final \
+ --recorded-narration audio
+```
+
+`--voice` 是必填项——脚本会拒绝未指定音色的调用。用 `--list-voices --locale <locale>` 查可用音色。
+
+## 依赖
+
+```bash
+python3 -m pip install edge-tts
+```
+
+已写入 `skills/ppt-master/requirements.txt`。`edge-tts` 调用微软的在线 TTS 服务,**生成时**需要联网;生成后的 MP3 是本地文件,PowerPoint 播放和视频导出都不依赖网络。
+
+## 经验值
+
+- **语速**:PPT Master 默认每页 2–5 句备注,`+0%` 听感最自然。如果某页特别密集(长技术段落),可以试 `-5%`。
+- **改某一页**:改对应的 `notes/<page>.md`,再跑一次 `notes_to_audio.py`(脚本会重新生成全量 MP3,整套 deck 跑一遍成本很低)。
+- **混合语言 deck**(中文里夹英文术语等):主流 locale 的神经语音对嵌入的外语词处理得不错——按主语言挑音色,先用一页试听再批量。
+
+---
+
+## 导出为视频
+
+带旁白的 PPTX 在 `exports/` 里就绪后,PowerPoint 自带"创建视频"功能可以直接把它导出成 MP4——不需要任何第三方工具。嵌入的音频会作为每页旁白播放;页间切换时间已经由 PPT Master 在嵌入时按音频长度自动设好(用 `--recorded-narration audio` 重新导出时),所以视频节奏和旁白完全同步。
+
+**PowerPoint(Windows / Mac,Office 2016+)**:
+
+1. 打开 `exports/` 里那份带旁白的 `.pptx`。
+2. **文件 → 导出 → 创建视频**。
+3. 选清晰度(4K / 全高清 / 高清 / 标准)以及"使用录制的计时和旁白"——PPT Master 已经替你录好了。
+4. **创建视频** → 保存为 `.mp4`(Windows 也支持 `.wmv`)。
+
+**Keynote(Mac)**:打开 deck → **文件 → 导出到 → 影片…** ——Keynote 同样会读取嵌入的音频和分页计时,输出 `.m4v` / `.mov`。
+
+**经验值**:
+
+- **不需要麦克风、不需要录制环节**——音频是合成的,重跑可重现。
+- **动画保留**:PPT Master 的页间转场和页内元素入场动画是真正的 OOXML 动画,导出视频后正常播放。详见 [转场与动画](./animations.md)。
+- **单页改音频**:改对应 `notes/<page>.md`,再跑一遍 `notes_to_audio.py` + 嵌入步骤,再重新导出视频——单页迭代通常不到一分钟。
+- **文件大小**:20 页全高清 deck 通常是 30–80 MB,取决于图片量。需要小文件分享时降到高清就行。