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
feat(svg-to-pptx): add _narrated name suffix to narration exports
hugohe3905ca9c87c89
diff --git a/docs/audio-narration.md b/docs/audio-narration.mdindex 89817d85..b23bb60f 100644--- a/docs/audio-narration.md+++ b/docs/audio-narration.md@@ -21,8 +21,8 @@ The full step-by-step is in [`workflows/generate-audio.md`](../skills/ppt-master| Command | Purpose ||---|---|-| `--recorded-narration audio` | Prepare PowerPoint's recorded timings and narrations. Requires complete per-slide audio and writes page auto-advance timings. Use this for narrated/video export. |-| `--narration-audio-dir audio` | Lower-level audio embedding. Embeds matched files and allows partial coverage. Use this for testing or manual PowerPoint finishing. |+| `--recorded-narration audio` | Prepare PowerPoint's recorded timings and narrations. Requires complete per-slide audio and writes page auto-advance timings. Use this for narrated/video export. The re-export is saved as `exports/<name>_<timestamp>_narrated.pptx`. |+| `--narration-audio-dir audio` | Lower-level audio embedding. Embeds matched files and allows partial coverage. Use this for testing or manual PowerPoint finishing. Exports get the same `_narrated` name suffix. |## Triggering itdiff --git a/docs/technical-design.md b/docs/technical-design.mdindex 1b4c92ca..838fe8e2 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -47,6 +47,7 @@ Output:exports/├── presentation_<timestamp>.pptx ← Native shapes (DrawingML) — canonical output, edit & deliver from here├── presentation_<timestamp>_native_charts.pptx ← Native chart/table objects instead of flattened shapes (opt-in via --native-objects)+ ├── presentation_<timestamp>_narrated.pptx ← Narrated version — embedded per-slide audio + auto-advance timings (via --recorded-narration audio)└── presentation_<timestamp>_svg.pptx ← SVG snapshot pptx — pixel-perfect visual reference (opt-in via --svg-snapshot)# Always written in default-flow mode (no -o)@@ -379,6 +380,7 @@ The post-processing stage works with five artifacts. Each one serves a workflow| `svg_final/` | IDE inline preview (VSCode/Cursor open `.svg` directly), browser open of a single page | `.pptx` is not openable in IDEs; `svg_output/` won't render fully because of external icon / image refs || `exports/<name>_<ts>.pptx` (native) | primary deliverable — editable in PowerPoint with DrawingML shapes | only artifact whose shapes the user can resize / recolor / restyle natively in PowerPoint || `exports/<name>_<ts>_native_charts.pptx` (opt-in via `--native-objects`) | when `data-pptx-native` chart/table markers should ship as real editable PowerPoint objects instead of flattened shapes | data-backed chart/table objects the user can edit in PowerPoint; name marks it apart from the plain shape export |+| `exports/<name>_<ts>_narrated.pptx` (via `--recorded-narration audio`) | narrated deck for auto-play and PowerPoint video export | embedded per-slide audio plus auto-advance timings; name marks it apart from silent exports || `exports/<name>_<ts>_svg.pptx` (preview, opt-in via `--svg-snapshot`) | cross-platform single-file distribution, multi-page browse, email attachment | self-contained, multi-page, opens in PowerPoint / Keynote / WPS / LibreOffice; an `svg_final/` folder is harder to distribute. Off by default — live preview already provides the SVG visual reference for dev/diagnostic work || `backup/<ts>/svg_output/` (always written in default-flow mode) | re-export from frozen SVG sources without re-running the LLM, archival | the only persisted copy of the Executor's raw SVG source after the project has been edited downstream |diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex 2512d2d4..5e1cab1e 100644--- a/docs/zh/audio-narration.md+++ b/docs/zh/audio-narration.md@@ -21,8 +21,8 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg| 命令 | 用途 ||---|---|-| `--recorded-narration audio` | 准备 PowerPoint 的"录制的计时和旁白"。要求每页都有音频,并写入页面自动推进时间。用于旁白视频导出。 |-| `--narration-audio-dir audio` | 底层音频嵌入能力。只嵌入匹配到的文件,允许部分页面有音频。用于测试或后续手工整理。 |+| `--recorded-narration audio` | 准备 PowerPoint 的"录制的计时和旁白"。要求每页都有音频,并写入页面自动推进时间。用于旁白视频导出。重导出文件保存为 `exports/<name>_<timestamp>_narrated.pptx`。 |+| `--narration-audio-dir audio` | 底层音频嵌入能力。只嵌入匹配到的文件,允许部分页面有音频。用于测试或后续手工整理。导出文件同样带 `_narrated` 后缀。 |## 怎么触发diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 601bf760..91089ede 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -47,6 +47,7 @@exports/├── presentation_<timestamp>.pptx ← 原生形状版(DrawingML)— 唯一标准产物,编辑/交付从这里走├── presentation_<timestamp>_native_charts.pptx ← 原生图表/表格对象版(而非压平形状,加 --native-objects 时生成)+ ├── presentation_<timestamp>_narrated.pptx ← 旁白版 — 逐页嵌入音频并写入自动推进时间(加 --recorded-narration audio 时生成)└── presentation_<timestamp>_svg.pptx ← SVG 快照版 pptx — 像素级视觉参考(加 --svg-snapshot 时生成)# 默认流程(未指定 -o)始终写入@@ -379,6 +380,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集。Executor 在一份| `svg_final/` | IDE 内即时预览(VSCode/Cursor 直接打开 `.svg`)、浏览器单页预览 | `.pptx` 在 IDE 里打不开;`svg_output/` 因图标 / 图片是外部引用,IDE 中渲染不完整 || `exports/<name>_<ts>.pptx`(native) | 主交付物——PowerPoint 中以 DrawingML 形状形态可编辑 | 唯一一份用户可在 PowerPoint 中原生改尺寸 / 改色 / 改样式的产物 || `exports/<name>_<ts>_native_charts.pptx`(需 `--native-objects` 显式开启) | 让带 `data-pptx-native` 标记的图表/表格以真·PowerPoint 原生对象交付,而非压平形状 | 带数据、可在 PowerPoint 中直接编辑的图表/表格对象;命名与普通压平形状导出区分开 |+| `exports/<name>_<ts>_narrated.pptx`(经 `--recorded-narration audio` 生成) | 自动放映与 PowerPoint 视频导出用的旁白版 deck | 逐页嵌入音频并写入自动推进时间;命名与无声导出区分开 || `exports/<name>_<ts>_svg.pptx`(preview,需 `--svg-snapshot` 显式开启) | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开;`svg_final/` 是文件夹,分发不便。默认关闭——live preview 已经覆盖 dev / 诊断场景的 SVG 视觉参考需求 || `backup/<ts>/svg_output/`(默认流程下始终生成) | 不重跑 LLM 的前提下从冻结 SVG 源重建 pptx、长期存档 | 项目下游被改动后,Executor 原始 SVG 唯一的留存副本 |diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 5093b8dc..5e8eb84b 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -646,6 +646,8 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path># exports/<project_name>_<timestamp>_svg.pptx ← SVG preview pptx (reads svg_final/)# Add --native-objects to emit real editable chart/table objects instead of flattened shapes:# exports/<project_name>_<timestamp>_native_charts.pptx ← native chart/table objects (data-pptx-native markers)+# Re-export with --recorded-narration audio (generate-audio workflow) embeds per-slide narration:+# exports/<project_name>_<timestamp>_narrated.pptx ← narrated pptx (embedded audio + auto-advance timings)```> The native pptx consumes `svg_output/` directly so the converter can preservediff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.mdindex 6722df32..849c36e6 100644--- a/skills/ppt-master/scripts/docs/svg-pipeline.md+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md@@ -69,6 +69,7 @@ Behavior:- `--recorded-narration audio` prepares PowerPoint's "recorded timings and narrations": every slide must have matching `m4a` / `mp3` / `wav` audio, `ffprobe` must read every duration, and `--animation-trigger on-click` is rejected- `--recorded-narration audio` keeps speaker notes, embeds each matching audio file, and writes slide auto-advance timings from audio duration- `--narration-audio-dir audio` is the lower-level embedding path: it embeds whatever files match and allows partial audio coverage+ - Either narration flag names the default-flow export `<project_name>_<timestamp>_narrated.pptx`, telling it apart from silent exports in the same directory- This is intended for direct PowerPoint video export with "Use recorded timings and narrations"- Long-audio import and automatic long-audio splitting are not supported; keep narration assets page-level- Voice choices can be listed with `python3 scripts/notes_to_audio.py --list-common-voices`, `python3 scripts/notes_to_audio.py --list-voices --locale zh-CN`, or provider-specific `--provider <name> --list-voices`diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.pyindex 4512650a..ac92bb8d 100644--- a/skills/ppt-master/scripts/project_manager.py+++ b/skills/ppt-master/scripts/project_manager.py@@ -175,7 +175,7 @@ class ProjectManager:"- `live_preview/`: browser preview runtime files and history (lock.json, server.log, edits.jsonl, annotations.jsonl)\n""- `sources/`: source materials and normalized markdown\n""- `analysis/`: machine-extracted intermediate analysis (PPTX intake, image_analysis.csv) — the pipeline's canonical must-read source/asset facts\n"- "- `exports/`: main native pptx (timestamped); `_svg.pptx` sibling added with `--svg-snapshot`, `_native_charts.pptx` name with `--native-objects`\n"+ "- `exports/`: main native pptx (timestamped); `_svg.pptx` sibling added with `--svg-snapshot`, `_native_charts.pptx` name with `--native-objects`, `_narrated.pptx` name when narration audio is embedded\n""- `backup/<timestamp>/`: svg_output/ archive (always written in default-flow mode; safe to delete old timestamps)\n"),encoding="utf-8",diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.pyindex ef4d3a7e..17946303 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py@@ -255,11 +255,14 @@ Recorded narration:parser.add_argument('--no-notes', action='store_true',help='Disable speaker notes embedding (enabled by default)')parser.add_argument('--narration-audio-dir', type=str, default=None,- help='Low-level audio embedding from this directory; allows partial matches')+ help='Low-level audio embedding from this directory; allows partial matches. '+ 'Default-flow exports get the _narrated name suffix.')parser.add_argument('--use-narration-timings', action='store_true',help='Set slide auto-advance timings from narration audio durations')parser.add_argument('--recorded-narration', type=str, default=None,- help='Prepare PowerPoint recorded timings and narrations from a complete audio directory')+ help='Prepare PowerPoint recorded timings and narrations from a complete audio '+ 'directory. Default-flow exports get the _narrated name suffix '+ '(<project>_<ts>_narrated.pptx) to tell them apart from silent exports.')parser.add_argument('--narration-padding', type=float, default=0.5,help='Seconds to add after each narration before auto-advance (default: 0.5)')@@ -361,10 +364,13 @@ Recorded narration:# --native-objects yields a materially different file (real editable# PowerPoint chart/table objects instead of flattened shapes), so mark# it in the default-flow name to tell it apart from a plain shape export- # and the _svg snapshot. Flag-driven (not content-sniffed) so the name is- # predictable; an explicit -o keeps the caller's exact name untouched.+ # and the _svg snapshot. Narration flags likewise mark _narrated (audio+ # embedded per slide + auto-advance timings); both entry points share+ # the tag. Flag-driven (not content-sniffed) so the name is predictable;+ # an explicit -o keeps the caller's exact name untouched.native_tag = "_native_charts" if args.native_objects else ""- native_path = exports_dir / f"{project_name}_{timestamp}{native_tag}.pptx"+ narrated_tag = "_narrated" if (args.recorded_narration or args.narration_audio_dir) else ""+ native_path = exports_dir / f"{project_name}_{timestamp}{native_tag}{narrated_tag}.pptx"# svg_output/ snapshot always goes under backup/<ts>/ in default-flow# mode (no -o). --svg-snapshot only controls the optional legacy# SVG-rendered pptx, which now sits alongside the native pptx indiff --git a/skills/ppt-master/workflows/generate-audio.md b/skills/ppt-master/workflows/generate-audio.mdindex cba0ffb2..7bdc90f9 100644--- a/skills/ppt-master/workflows/generate-audio.md+++ b/skills/ppt-master/workflows/generate-audio.md@@ -149,7 +149,7 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \If `notes_to_audio.py` errors with a missing dependency or missing provider API key, fix the prerequisite and re-run — do NOT swallow the error.-`--recorded-narration audio` prepares PowerPoint's recorded timings and narrations: every slide must have a matching supported audio file, every duration must be readable by `ffprobe`, and object animations must not use `--animation-trigger on-click`. Use `after-previous` or `with-previous` for narrated/video export.+`--recorded-narration audio` prepares PowerPoint's recorded timings and narrations: every slide must have a matching supported audio file, every duration must be readable by `ffprobe`, and object animations must not use `--animation-trigger on-click`. Use `after-previous` or `with-previous` for narrated/video export. The re-export is saved as `exports/<project_name>_<timestamp>_narrated.pptx`, telling it apart from silent exports.---