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(ppt): harden recorded narration export

hugohe33bf790138348
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
index de016099..89817d85 100644
--- a/docs/audio-narration.md
+++ b/docs/audio-narration.md
@@ -5,7 +5,7 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](
## What you get
- One audio file 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.
+- Optional re-export: a new PPTX in `exports/` with each `m4a` / `mp3` / `wav` file 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
@@ -13,10 +13,17 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](
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 selected provider's voice catalog, and recommends 3–6 candidates with a one-line tone description for each (e.g. "稳重男声,适合财报"). It also recommends a speaking rate or provider defaults 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.
+4. **Generation runs.** The script writes page-level audio to `audio/`, then (if you kept embedding) re-exports the deck with audio attached. Long-audio import and automatic long-audio splitting are not supported.
The full step-by-step is in [`workflows/generate-audio.md`](../skills/ppt-master/workflows/generate-audio.md).
+## Two embedding paths
+
+| 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. |
+
## Triggering it
Just say so in chat after the deck has been exported:
@@ -149,7 +156,7 @@ Cloud TTS providers do not require extra Python packages; they use HTTPS directl
## 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.
+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. `--recorded-narration` rejects `on-click` object animation because it does not generate object-level click timings.
**PowerPoint (Windows / Mac, Office 2016+)**:
@@ -163,6 +170,6 @@ Once the narrated PPTX is in `exports/`, PowerPoint exports it as a video native
**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).
+- **Animations are preserved** — page transitions and click-free 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/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index e882afbf..56f8285e 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -81,7 +81,7 @@ Flags:
Enabled by default (`mixed` effect + `after-previous` trigger). Three Start modes are available — these mirror PowerPoint's animation-pane "Start" dropdown:
-- **`on-click`** — entering a slide → first click reveals the first semantic group; each subsequent click reveals the next group in z-order. Suits live presentations where the speaker paces reveals.
+- **`on-click`** — entering a slide → first click reveals the first semantic group; each subsequent click reveals the next group in z-order. Suits live presentations where the speaker paces reveals. Forbidden with `--recorded-narration` because video-ready exports need click-free playback.
- **`with-previous`** — all groups start together on slide entry, playing their entrance animation in parallel. Stagger ignored.
- **`after-previous`** (default) — first group fires on slide entry, subsequent groups cascade after the previous one finishes, with `--animation-stagger` extra spacing. Suits kiosk playback, recorded walkthroughs, or anyone who wants visual flow without clicking.
@@ -121,6 +121,8 @@ Flags:
- `--animation-stagger` — gap between elements in `after-previous` mode (seconds, default `0.5`). Ignored otherwise.
- `--animation-config` — sidecar path. Default: `<project>/animations.json` when present.
+> Note: `--recorded-narration` rejects `on-click`; use `after-previous` or `with-previous` for video-ready narrated decks.
+
## Anchor Logic — Top-Level `<g id="...">`
Per-element animations are anchored on **top-level `<g id="...">` content groups** in the SVG (e.g. `<g id="cover-title">`, `<g id="card-1">`). One group = one click reveal.
diff --git a/skills/ppt-master/references/shared-standards.md b/skills/ppt-master/references/shared-standards.md
index 8faccd91..ff86fbf1 100644
--- a/skills/ppt-master/references/shared-standards.md
+++ b/skills/ppt-master/references/shared-standards.md
@@ -323,7 +323,10 @@ python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio
```
- `notes_to_audio.py` reads split `notes/*.md` files and writes one audio file per slide to `audio/`. Default `edge` output is MP3; configured cloud providers may output MP3 or WAV depending on provider settings.
+- `--recorded-narration audio` prepares PowerPoint's recorded timings and narrations: every slide needs matching `m4a` / `mp3` / `wav` audio, every duration must be readable by `ffprobe`, and `on-click` object animation is rejected.
- `--recorded-narration audio` embeds matching audio, keeps speaker notes, and sets slide timings from audio duration.
+- `--narration-audio-dir audio` is the lower-level embedding path for partial audio coverage; it does not prepare a complete recorded-timings export.
+- Long-audio import and automatic long-audio splitting are not supported.
Full reference: [`animations.md`](animations.md).
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index 00f95207..1659b838 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -60,12 +60,16 @@ Behavior:
- Recorded narration is opt-in:
- `notes_to_audio.py` uses `edge-tts` by default, or a configured cloud TTS provider (`elevenlabs`, `minimax`, `qwen`, `cosyvoice`), and generates one audio file per slide into `audio/`
- Narration text is read strictly from the matching `notes/*.md` file; the script only skips Markdown heading lines (`# ...`) and does not summarize, rewrite, or filter delivery notes
+ - `--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
- - This is intended for PowerPoint's video export option "Use recorded timings and narrations"
+ - `--narration-audio-dir audio` is the lower-level embedding path: it embeds whatever files match and allows partial audio coverage
+ - 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`
- Page transitions are controlled by `-t/--transition`; per-element entrance animations are controlled by `-a/--animation`
- Per-element animation applies to top-level SVG `<g id="...">` groups in z-order; aim for 3–8 content groups per slide. Page chrome (background / header / footer / decorations / watermark / page number, by id token) is skipped automatically
- Start mode is set by `--animation-trigger`, mirroring PowerPoint's Start dropdown: `after-previous` (default, cascade with `--animation-stagger` spacing on slide entry), `on-click` (presenter-paced), `with-previous` (all together on slide entry)
+- `on-click` is for live presentations only; recorded narration rejects it because the tool does not generate object-level click timings
- Flat SVG roots without top-level groups fall back to at most 8 visible primitives; beyond that, animation is skipped on the slide
- `mixed` is deterministic: the first animated group on each slide uses `fade`, then later groups cycle through a curated visible-effect pool across the whole deck; `random` samples from that same pool
- `--animation-duration` controls per-element entrance length (default `0.4`); `--animation-stagger` adds gap between elements in `after-previous` mode (default `0.5`)
diff --git a/skills/ppt-master/scripts/docs/troubleshooting.md b/skills/ppt-master/scripts/docs/troubleshooting.md
index 9ce486d2..f53ef502 100644
--- a/skills/ppt-master/scripts/docs/troubleshooting.md
+++ b/skills/ppt-master/scripts/docs/troubleshooting.md
@@ -56,7 +56,12 @@ python3 scripts/notes_to_audio.py <project_path> --voice zh-CN-XiaoxiaoNeural
python3 scripts/svg_to_pptx.py <project_path> --recorded-narration audio
```
-If slide timings do not follow the narration, confirm `ffprobe` is available; without it, audio can still embed, but duration-based auto-advance is skipped.
+`--recorded-narration` prepares PowerPoint recorded timings and narrations. If it fails, check:
+- every slide has a matching `m4a`, `mp3`, or `wav` file in `audio/`
+- `ffprobe` is installed and can read each audio duration
+- the deck is not using `--animation-trigger on-click`
+
+Use `--narration-audio-dir audio` only when you intentionally want lower-level, partial audio embedding instead of PowerPoint recorded timings.
## Dependency Checklist
diff --git a/skills/ppt-master/scripts/notes_to_audio.py b/skills/ppt-master/scripts/notes_to_audio.py
index c277f16a..b10462fb 100644
--- a/skills/ppt-master/scripts/notes_to_audio.py
+++ b/skills/ppt-master/scripts/notes_to_audio.py
@@ -149,8 +149,8 @@ def main() -> int:
help="MiniMax T2A model ID (default: speech-2.8-hd)")
parser.add_argument("--minimax-base-url", default=None,
help="MiniMax T2A endpoint or base URL")
- parser.add_argument("--minimax-output-format", default="mp3", choices=["mp3", "wav", "flac", "pcm"],
- help="MiniMax audio format (default: mp3)")
+ parser.add_argument("--minimax-output-format", default="mp3", choices=["mp3", "wav"],
+ help="MiniMax audio format for PPT narration (default: mp3)")
parser.add_argument("--minimax-sample-rate", type=int, default=32000,
help="MiniMax sample rate (default: 32000)")
parser.add_argument("--minimax-bitrate", type=int, default=128000,
@@ -183,8 +183,8 @@ def main() -> int:
help="CosyVoice model ID (default: cosyvoice-v3-flash)")
parser.add_argument("--cosyvoice-base-url", default=None,
help="CosyVoice SpeechSynthesizer endpoint or base URL")
- parser.add_argument("--cosyvoice-output-format", default="mp3", choices=["mp3", "wav", "pcm", "opus"],
- help="CosyVoice audio format (default: mp3)")
+ parser.add_argument("--cosyvoice-output-format", default="mp3", choices=["mp3", "wav"],
+ help="CosyVoice audio format for PPT narration (default: mp3)")
parser.add_argument("--cosyvoice-sample-rate", type=int, default=24000,
help="CosyVoice sample rate (default: 24000)")
parser.add_argument("--cosyvoice-volume", type=int, default=None,
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
index f6603eb5..2621ae99 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_builder.py
@@ -633,13 +633,16 @@ def create_pptx_with_native_svg(
if use_narration_timings:
duration = probe_audio_duration(audio_path)
- if duration:
- slide_xml = apply_recorded_timing(
- slide_xml,
- advance_after=duration + narration_padding,
- transition_duration=slide_transition_duration,
- transition_effect=slide_transition or 'fade',
+ if duration is None:
+ raise RuntimeError(
+ f"Unable to read narration duration with ffprobe: {audio_path}"
)
+ slide_xml = apply_recorded_timing(
+ slide_xml,
+ advance_after=duration + narration_padding,
+ transition_duration=slide_transition_duration,
+ transition_effect=slide_transition or 'fade',
+ )
slide_xml_path.write_text(slide_xml, encoding='utf-8')
narration_slides_created.add(slide_num)
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
index 3a088589..1182b4cd 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_cli.py
@@ -11,7 +11,7 @@ from pathlib import Path
from .pptx_dimensions import CANVAS_FORMATS, get_project_info
from .pptx_discovery import find_svg_files, find_notes_files
from .pptx_builder import create_pptx_with_native_svg
-from .pptx_narration import find_narration_files
+from .pptx_narration import NARRATION_EXTENSIONS, find_narration_files, probe_audio_duration
from .pptx_slide_xml import TRANSITIONS
from .animation_config import load_animation_config, validate_animation_config
@@ -21,6 +21,39 @@ except ImportError:
_ANIMATIONS = {}
+def _as_dict(value: object) -> dict:
+ return value if isinstance(value, dict) else {}
+
+
+def _recorded_narration_on_click_slides(
+ ref_files: list[Path],
+ animation_config: dict | None,
+ animation: str | None,
+ animation_trigger: str,
+ animation_cli_overrides: dict[str, bool],
+) -> list[str]:
+ """Return slides whose effective recorded-video animation trigger is on-click."""
+ slides_cfg = _as_dict(_as_dict(animation_config).get('slides'))
+ blocked: list[str] = []
+ for svg_path in ref_files:
+ slide_cfg = _as_dict(slides_cfg.get(svg_path.stem))
+ anim_cfg = _as_dict(slide_cfg.get('animation'))
+
+ slide_animation = animation
+ if not animation_cli_overrides.get('animation') and 'effect' in anim_cfg:
+ cfg_effect = str(anim_cfg.get('effect'))
+ slide_animation = None if cfg_effect == 'none' else cfg_effect
+ if slide_animation is None:
+ continue
+
+ slide_trigger = animation_trigger
+ if not animation_cli_overrides.get('animation_trigger') and anim_cfg.get('trigger'):
+ slide_trigger = str(anim_cfg.get('trigger'))
+ if slide_trigger == 'on-click':
+ blocked.append(svg_path.stem)
+ return blocked
+
+
def main() -> None:
"""CLI entry point for the SVG to PPTX conversion tool."""
transition_choices = (
@@ -85,9 +118,15 @@ Speaker notes (enabled by default):
Recorded narration:
%(prog)s examples/ppt169_demo -s final --recorded-narration audio
- Keeps speaker notes when enabled
+ - Prepares PowerPoint recorded timings and narrations
+ - Requires one m4a/mp3/wav file per slide
- Embeds per-slide audio matched by SVG filename / slide number
- Sets slide auto-advance from audio duration so video export can use
"recorded timings and narrations"
+ - Rejects on-click object animations; use after-previous or with-previous
+ %(prog)s examples/ppt169_demo --narration-audio-dir audio
+ - Lower-level audio embedding: embeds matched files but allows partial matches
+ - Use only when you do not need a complete recorded-timings export
''',
)
@@ -153,11 +192,11 @@ 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='Embed per-slide narration audio from this directory')
+ help='Low-level audio embedding from this directory; allows partial matches')
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='Shortcut: embed narration audio and use its durations as recorded timings')
+ help='Prepare PowerPoint recorded timings and narrations from a complete audio directory')
parser.add_argument('--narration-padding', type=float, default=0.5,
help='Seconds to add after each narration before auto-advance (default: 0.5)')
@@ -251,10 +290,53 @@ Recorded narration:
narration_audio_dir = Path(narration_audio_dir_arg)
if not narration_audio_dir.is_absolute():
narration_audio_dir = project_path / narration_audio_dir
+ if args.recorded_narration and not narration_audio_dir.is_dir():
+ print(
+ f"Error: Recorded narration directory does not exist: {narration_audio_dir}",
+ file=sys.stderr,
+ )
+ sys.exit(1)
narration_audio = find_narration_files(narration_audio_dir, ref_files)
if verbose:
print(f" Narration audio directory: {narration_audio_dir}")
print(f" Narration audio matched: {len(narration_audio)}/{len(ref_files)} slide(s)")
+ if args.recorded_narration:
+ missing = [path.stem for path in ref_files if path.stem not in narration_audio]
+ if missing:
+ print(
+ "Error: Recorded narration requires one supported audio file per slide. "
+ f"Matched {len(narration_audio)}/{len(ref_files)} slide(s). "
+ f"Supported extensions: {', '.join(NARRATION_EXTENSIONS)}",
+ file=sys.stderr,
+ )
+ for stem in missing[:20]:
+ print(f" Missing audio for: {stem}", file=sys.stderr)
+ if len(missing) > 20:
+ print(f" ... and {len(missing) - 20} more", file=sys.stderr)
+ sys.exit(1)
+ unreadable = [
+ f"{stem}: {audio_path}"
+ for stem, audio_path in sorted(narration_audio.items())
+ if probe_audio_duration(audio_path) is None
+ ]
+ if unreadable:
+ print(
+ "Error: Recorded narration requires readable audio durations. "
+ "Install ffprobe/ffmpeg or replace the listed audio files.",
+ file=sys.stderr,
+ )
+ for item in unreadable[:20]:
+ print(f" {item}", file=sys.stderr)
+ if len(unreadable) > 20:
+ print(f" ... and {len(unreadable) - 20} more", file=sys.stderr)
+ sys.exit(1)
+ elif narration_audio_dir_arg and verbose:
+ missing = [path.stem for path in ref_files if path.stem not in narration_audio]
+ if missing:
+ print(
+ f" [warn] Narration audio matched {len(narration_audio)}/{len(ref_files)} slide(s); "
+ "unmatched slides will export without audio."
+ )
if args.animation_config:
config_path = Path(args.animation_config)
@@ -325,6 +407,26 @@ Recorded narration:
'animation_trigger': args.animation_trigger is not None,
}
+ if args.recorded_narration and gen_native:
+ on_click_slides = _recorded_narration_on_click_slides(
+ ref_files,
+ animation_config,
+ animation,
+ animation_trigger,
+ animation_cli_overrides,
+ )
+ if on_click_slides:
+ print(
+ "Error: --recorded-narration cannot be used with on-click object animations. "
+ "Use --animation-trigger after-previous or --animation-trigger with-previous.",
+ file=sys.stderr,
+ )
+ for slide in on_click_slides[:20]:
+ print(f" on-click trigger: {slide}", file=sys.stderr)
+ if len(on_click_slides) > 20:
+ print(f" ... and {len(on_click_slides) - 20} more", file=sys.stderr)
+ sys.exit(1)
+
# svg_files is per-product (native vs legacy may now read different
# directories); everything else is shared.
shared_kwargs = dict(
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_narration.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_narration.py
index 7ec45cec..38f05314 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_narration.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_narration.py
@@ -15,11 +15,8 @@ IMAGE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relation
AUDIO_CONTENT_TYPES = {
".m4a": "audio/mp4",
- ".mp4": "audio/mp4",
".mp3": "audio/mpeg",
".wav": "audio/wav",
- ".aif": "audio/aiff",
- ".aiff": "audio/aiff",
}
NARRATION_EXTENSIONS = tuple(AUDIO_CONTENT_TYPES.keys())
diff --git a/skills/ppt-master/scripts/tts_backends/backend_common.py b/skills/ppt-master/scripts/tts_backends/backend_common.py
index 2d2298f4..cf012d8c 100644
--- a/skills/ppt-master/scripts/tts_backends/backend_common.py
+++ b/skills/ppt-master/scripts/tts_backends/backend_common.py
@@ -62,7 +62,9 @@ def download_audio(url: str, output_path: Path) -> None:
def extension_from_format(audio_format: str) -> str:
normalized = audio_format.strip().lower()
- if normalized in {"mp3", "wav", "flac", "pcm", "opus"}:
+ if normalized in {"mp3", "wav"}:
return f".{normalized}"
- raise RuntimeError(f"Unsupported audio format for PPT narration: {audio_format}")
-
+ raise RuntimeError(
+ f"Unsupported audio format for PPT narration: {audio_format}. "
+ "Use mp3 or wav, or transcode provider output before embedding."
+ )
diff --git a/skills/ppt-master/workflows/generate-audio.md b/skills/ppt-master/workflows/generate-audio.md
index b8877762..f6a3a064 100644
--- a/skills/ppt-master/workflows/generate-audio.md
+++ b/skills/ppt-master/workflows/generate-audio.md
@@ -4,7 +4,7 @@ description: Generate per-slide narration audio with AI-recommended voice select
# Generate Audio Workflow
-> Standalone post-export step. Run when the user asks for "生成音频" / "录制旁白" / "narrated PPT" / "video export with voice", or proactively offer it after a deck is exported. Produces one audio file per slide via `edge-tts` by default, or a cloud TTS provider (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) when the user chooses high-quality narration or a cloned voice, then optionally re-exports the PPTX with the audio embedded and per-slide auto-advance timings.
+> Standalone post-export step. Run when the user asks for "生成音频" / "录制旁白" / "narrated PPT" / "video export with voice", or proactively offer it after a deck is exported. Produces one audio file per slide via `edge-tts` by default, or a cloud TTS provider (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) when the user chooses high-quality narration or a cloned voice, then optionally re-exports a video-ready PPTX with audio embedded and per-slide auto-advance timings.
This workflow is **independent**: it reads `notes/*.md` and queries the selected TTS voice catalog — no upstream conversation context required. Safe to invoke in a fresh session.
@@ -12,6 +12,9 @@ This workflow is **independent**: it reads `notes/*.md` and queries the selected
- `notes/total.md` exists and has been split into per-page files at `notes/*.md` (post-processing Step 7.1 done).
- Default mode: `edge-tts` is installed (`python3 -m pip install edge-tts`).
+- The workflow is page-level only: one notes file becomes one audio file. Do not use a single long audio track or attempt automatic long-audio splitting.
+- PPT narration assets must be PowerPoint-reliable audio: `m4a` (AAC), `mp3`, or `wav`. The built-in TTS path defaults to `mp3`; provider formats such as `pcm`, `opus`, or `flac` must be transcoded before embedding.
+- PowerPoint recorded narration export requires `ffprobe` so slide timings can be written from actual audio duration.
- High-quality cloud mode: provider API key is set before use:
- ElevenLabs: `ELEVENLABS_API_KEY`
- MiniMax: `MINIMAX_API_KEY`
@@ -146,6 +149,8 @@ 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.
+
---
## Step 5: Completion report