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

feat(svg-to-pptx): add _narrated name suffix to narration exports

hugohe3905ca9c87c89
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
index 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 it
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 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.md
index 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.md
index 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.md
index 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 preserve
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 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.py
index 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.py
index 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 in
diff --git a/skills/ppt-master/workflows/generate-audio.md b/skills/ppt-master/workflows/generate-audio.md
index 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.
---