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.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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,取决于图片量。需要小文件分享时降到高清就行。