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(ppt): sync narration and animation export guidance
hugohe3211b5e9b35e3
diff --git a/docs/faq.md b/docs/faq.mdindex 56ef00e7..176ccdad 100644--- a/docs/faq.md+++ b/docs/faq.md@@ -78,6 +78,8 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fadepython3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger on-click # presenter-paced reveals```+`on-click` is for live presentations. Narrated/video export via `--recorded-narration` rejects it because PPT Master writes page timings, not object-level click timings; use `after-previous` or `with-previous` for narrated decks.+Full effect list, anchor logic (top-level `<g id="...">`), fallback behavior, and limitations: see [Animations & Transitions](../skills/ppt-master/references/animations.md).## Q: Which AI model works best?diff --git a/docs/technical-design.md b/docs/technical-design.mdindex 14b709d0..0fd47d2d 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -266,6 +266,8 @@ The interesting design choice is the animation **anchor**, not the effect list.**Why recorded narration drives auto-advance from clip duration.** When narration is embedded, the deck targets video export — and a video has no presenter to click. Setting per-slide auto-advance timings to the audio clip's actual duration produces a deck PowerPoint exports cleanly to MP4 without manual timing work. Picking any other duration source (estimated reading speed, fixed per-slide) breaks the audio-visual sync.+**Why recorded narration rejects on-click object animation.** PowerPoint can record click timings during a real rehearsal, but PPT Master does not synthesize object-level click events. The recorded narration path writes page-level audio and slide auto-advance timings only, so click-driven object reveals would leave the export dependent on extra manual PowerPoint rehearsal. For narrated decks, object entrances must be click-free (`after-previous` or `with-previous`).+---## Standalone Workflowsdiff --git a/docs/zh/animations.md b/docs/zh/animations.mdindex 8463456d..8dd88a12 100644--- a/docs/zh/animations.md+++ b/docs/zh/animations.md@@ -81,7 +81,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --auto-advance 5默认开启(`mixed` 效果 + `after-previous` 触发)。共有三种 Start 模式,**与 PowerPoint 动画窗格的 Start 下拉菜单一一对应**:-- **`on-click`**(单击时)—— 进入页面 → 第一次点击显示第一个语义组,后续每次点击按 z-order 显示下一个组。适合现场演讲,演讲者控制节奏。+- **`on-click`**(单击时)—— 进入页面 → 第一次点击显示第一个语义组,后续每次点击按 z-order 显示下一个组。适合现场演讲,演讲者控制节奏。与 `--recorded-narration` 互斥,因为带旁白的视频导出需要无点击播放。- **`with-previous`**(与上一动画同时)—— 所有组在进入页面时一起入场,并行播放各自的入场动画。`--animation-stagger` 不生效。- **`after-previous`**(默认,在上一动画之后)—— 第一组进入页面时入场,后续组在前一个结束后接着出现,并按 `--animation-stagger` 增加额外间隔。适合展厅循环、录屏走查,或者只是想看流动效果不想点击。@@ -121,6 +121,8 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger w- `--animation-stagger` — `after-previous` 模式下两组之间的额外间隔(秒,默认 `0.5`)。其他模式忽略。- `--animation-config` — sidecar 路径。默认自动读取 `<project>/animations.json`(如果存在)。+> Note: `--recorded-narration` 会拒绝 `on-click`;带旁白的视频导出请使用 `after-previous` 或 `with-previous`。+## 锚点机制 — 顶层 `<g id="...">`页内动画锚定在 SVG 的**顶层 `<g id="...">` 内容组**上(如 `<g id="cover-title">`、`<g id="card-1">`),一个组对应一次点击入场。diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex 6890e7af..2512d2d4 100644--- a/docs/zh/audio-narration.md+++ b/docs/zh/audio-narration.md@@ -5,7 +5,7 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg## 你会得到什么- 每页一个音频文件,存放于 `<project_path>/audio/`,文件名与 SVG 对齐(`01_cover.mp3`、`02_market_landscape.mp3` …)。-- 可选重新导出:在 `exports/` 生成新版 PPTX,每页对应的音频已嵌入到该页,且页面切换时间按音频长度自动设置——无人值守自动播放和视频导出都不用再手动调时间。+- 可选重新导出:在 `exports/` 生成新版 PPTX,每页对应的 `m4a` / `mp3` / `wav` 音频已嵌入到该页,且页面切换时间按音频长度自动设置——无人值守自动播放和视频导出都不用再手动调时间。- 演讲者备注原样保留。## 它是怎么做到的@@ -13,10 +13,17 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出候选并给每个写一句中文调性说明(如"稳重男声·适合财报")。语速/风格也会基于 notes 信息密度给出推荐值。3. **一次问完,一次回答**。AI 在一条消息里同时问三件事——生成模式、音色、是否把音频嵌入回 PPTX——每项都标了推荐值。回"好"接受全部默认,或者只说要改的部分(如"音色 2,语速 -5%")。-4. **执行**。脚本写出音频到 `audio/`,再(如果你保留嵌入)重新导出带音频的 PPTX。+4. **执行**。脚本写出逐页音频到 `audio/`,再(如果你保留嵌入)重新导出带音频的 PPTX。不支持长音频导入或自动拆分。完整流程见 [`workflows/generate-audio.md`](../../skills/ppt-master/workflows/generate-audio.md)。+## 两条嵌入路径++| 命令 | 用途 |+|---|---|+| `--recorded-narration audio` | 准备 PowerPoint 的"录制的计时和旁白"。要求每页都有音频,并写入页面自动推进时间。用于旁白视频导出。 |+| `--narration-audio-dir audio` | 底层音频嵌入能力。只嵌入匹配到的文件,允许部分页面有音频。用于测试或后续手工整理。 |+## 怎么触发deck 导出后,在聊天里直接说就行:@@ -79,6 +86,8 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \edge 模式下 `--voice` 是必填项。云端 provider 使用 `--voice-id` 传入对应平台的系统音色或复刻音色 ID。声音复刻本身先在对应平台控制台/API 中完成,`notes_to_audio.py` 使用得到的 voice ID 生成逐页旁白。+进入 PPTX 的旁白音频必须是 PowerPoint 可靠格式:`m4a`(AAC)、`mp3` 或 `wav`。内置生成路径默认使用 `mp3`;如果 provider 产出 `pcm`、`opus` 或 `flac`,需要先转码再嵌入。+## 使用复刻音色四个云端 provider —— **ElevenLabs**、**MiniMax**、**Qwen**、**CosyVoice** —— 都支持用一段较短的音频样本复刻一个新音色,再用这个音色合成新语音。只要你能拿到 `voice_id`,PPT Master 就能用这个音色把整份 deck 念出来。(`edge` 不支持复刻。)@@ -133,7 +142,7 @@ python3 -m pip install edge-tts## 导出为视频-带旁白的 PPTX 在 `exports/` 里就绪后,PowerPoint 自带"创建视频"功能可以直接把它导出成 MP4——不需要任何第三方工具。嵌入的音频会作为每页旁白播放;页间切换时间已经由 PPT Master 在嵌入时按音频长度自动设好(用 `--recorded-narration audio` 重新导出时),所以视频节奏和旁白完全同步。+带旁白的 PPTX 在 `exports/` 里就绪后,PowerPoint 自带"创建视频"功能可以直接把它导出成 MP4——不需要任何第三方工具。嵌入的音频会作为每页旁白播放;页间切换时间已经由 PPT Master 在嵌入时按音频长度自动设好(用 `--recorded-narration audio` 重新导出时),所以视频节奏和旁白完全同步。`--recorded-narration` 会拒绝 `on-click` 对象动画,因为 PPT Master 不生成对象级点击计时。**PowerPoint(Windows / Mac,Office 2016+)**:@@ -147,6 +156,6 @@ python3 -m pip install edge-tts**经验值**:- **不需要麦克风、不需要录制环节**——音频是合成的,重跑可重现。-- **动画保留**:PPT Master 的页间转场和页内元素入场动画是真正的 OOXML 动画,导出视频后正常播放。详见 [转场与动画](./animations.md)。+- **动画保留**:PPT Master 的页间转场和无点击页内元素入场动画是真正的 OOXML 动画,导出视频后正常播放。详见 [转场与动画](./animations.md)。- **单页改音频**:改对应 `notes/<page>.md`,再跑一遍 `notes_to_audio.py` + 嵌入步骤,再重新导出视频——单页迭代通常不到一分钟。- **文件大小**:20 页全高清 deck 通常是 30–80 MB,取决于图片量。需要小文件分享时降到高清就行。diff --git a/docs/zh/faq.md b/docs/zh/faq.mdindex 53d082b8..ff1da1fe 100644--- a/docs/zh/faq.md+++ b/docs/zh/faq.md@@ -78,6 +78,8 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation fadepython3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation-trigger on-click # 改为单击触发,演讲者控制节奏```+`on-click` 适合现场演示。通过 `--recorded-narration` 做旁白/视频导出时会拒绝它,因为 PPT Master 只写页面级计时,不生成对象级点击计时;带旁白的 deck 请使用 `after-previous` 或 `with-previous`。+完整效果列表、`<g id="...">` 锚点机制、降级行为、限制:见 [转场与动画](./animations.md)。## Q: 推荐用什么 AI 模型?diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex b5622872..97b82a20 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -266,6 +266,8 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份**为什么录制旁白让自动推进时长跟着片段时长走。** 嵌入旁白意味着 deck 目标是视频导出——视频里没有演讲者去点击。把每页自动推进时长设为该页音频片段的实际时长,PowerPoint 能干净地导出为 MP4,无需人工配时。任何其他时长来源(估算朗读速度、固定每页时长)都会破坏音画同步。+**为什么录制旁白拒绝 on-click 对象动画。** PowerPoint 可以在真实排练时记录点击计时,但 PPT Master 不合成对象级点击事件。录制旁白路径只写页面级音频和页面自动推进计时,所以单击触发的对象入场会让导出依赖额外的 PowerPoint 人工排练。带旁白的 deck 必须使用无点击入场(`after-previous` 或 `with-previous`)。+---## Standalone Workflows(独立工作流)