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(video): support real-time slideshow capture delivery

hugohe3ef8d8d83317b
diff --git a/docs/animations.md b/docs/animations.md
index 26ba12e8..a31873f2 100644
--- a/docs/animations.md
+++ b/docs/animations.md
@@ -179,8 +179,9 @@ merely to demonstrate that the feature exists.
This validation proves the editable PPTX contains the native cue; it does not
prove PowerPoint's MP4 audio track contains it. For direct narrated video with
-resolved cues, use the post-export sound mix in
-[Audio Narration & Video Export](./audio-narration.md).
+resolved cues, follow [Audio Narration & Video Export](./audio-narration.md)
+and choose either the verified native-export sound mix or an explicit
+PowerPoint slideshow capture with system audio. Do not combine the two paths.
## Customize Specific Objects
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
index f2c714f9..3dfcaea6 100644
--- a/docs/audio-narration.md
+++ b/docs/audio-narration.md
@@ -14,7 +14,8 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](
- When narration-cue synchronization is selected, canonical `animations.json` and page-local SRT derive `narration_animations.json`, whose click-free object animations wait for the relevant subtitle cue. Narration-independent custom motion keeps canonical timing instead. When neither animation sidecar exists, narrated export creates no sidecar and inherits the base export's resolved motion. With page-local SRT, these paths can produce a deck-wide `<project_path>/audio/total.srt` aligned to the final PPTX timeline; after PowerPoint exports a video, `video_subtitles.py` can align the frozen narration text against its actual audio track for a delivery sidecar SRT.
- 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 from the configurable page-start floor, audio length, and page-tail padding, so kiosk/auto-play and video export work without manual timing. Narration never starts before the page transition finishes.
- Optional native video export on Windows: `powerpoint_video.py` delegates the final narrated PPTX to PowerPoint 2016+ and waits until its native MP4 encoder succeeds or fails. This raw MP4 preserves the visual animation/narration path, but PowerPoint does not reliably include native transition or object-animation sounds in its audio track.
-- When direct MP4 delivery has resolved animation sound cues, `video_sound_mix.py` produces an independent float SFX WAV, a final mixed MP4, and a JSON receipt proving the stem reached the actual final audio while the video stream stayed unchanged.
+- On the native-export path, when direct MP4 delivery has resolved animation sound cues, `video_sound_mix.py` produces an independent float SFX WAV, a final mixed MP4, and a JSON receipt proving the stem reached the actual final audio while the video stream stayed unchanged.
+- As an explicit manual alternative, desktop Windows PowerPoint can play the final narrated deck full-screen while a recorder captures the presentation picture and one application/system-audio source. This records the narration and native cues PowerPoint actually plays, so it must not be followed by `video_sound_mix.py`.
- The original speaker notes are preserved.
## How it works
@@ -22,7 +23,7 @@ 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. "steady male voice for financial reporting"). It also recommends a speaking rate or provider defaults based on notes density.
3. **Settings resolve once.** Default Generate and Enhance Native ask once for provider, voice, rate, embedding, and optional video export. Quick uses explicit values and automatically resolves unspecified provider, voice, rate, and embedding choices; video remains off unless direct video delivery was requested.
-4. **Generation runs.** Edge, ElevenLabs, MiniMax, and timestamp-capable CosyVoice voices write each page's audio and SRT from provider timing returned by the same synthesis; Qwen and explicit CosyVoice audio-only mode write audio only. A complete run atomically writes `audio/manifest.json` for provenance. For Generate PPTX with narration-cue synchronization, page-local SRT and canonical custom animation let the AI map current SVG content groups to numbered SRT cues and derive click-free `narration_animations.json`; narration-independent custom motion keeps canonical timing, while no animation sidecar inherits the base export's resolved motion. It then re-exports the deck with audio attached and, when page-local SRT exists, merges it using timing values read from that final PPTX. When automatic video export was selected and compatible Windows PowerPoint is available, it continues through PowerPoint's native encoder. If the final narrated trace and PPTX contain sound cues, the raw MP4 is then calibrated by page narration, mixed with the exact embedded cue bytes, limited, and verified before any delivery SRT is aligned against the final video. Long-audio import and automatic long-audio splitting are not supported.
+4. **Generation runs.** Edge, ElevenLabs, MiniMax, and timestamp-capable CosyVoice voices write each page's audio and SRT from provider timing returned by the same synthesis; Qwen and explicit CosyVoice audio-only mode write audio only. A complete run atomically writes `audio/manifest.json` for provenance. For Generate PPTX with narration-cue synchronization, page-local SRT and canonical custom animation let the AI map current SVG content groups to numbered SRT cues and derive click-free `narration_animations.json`; narration-independent custom motion keeps canonical timing, while no animation sidecar inherits the base export's resolved motion. It then re-exports the deck with audio attached and, when page-local SRT exists, merges it using timing values read from that final PPTX. Automatic video delivery continues through PowerPoint's native encoder and, when cues exist, the verified sound mix. An explicitly selected slideshow capture instead records PowerPoint's real-time full-screen picture and system audio, skips that mixer, and aligns any delivery SRT against the accepted capture. Long-audio import and automatic long-audio splitting are not supported.
Subtitles remain external artifacts: PPT Master does not embed them into the PPTX or burn them into the MP4. Automatic video export delegates to installed Windows PowerPoint; it is not a separate renderer.
@@ -136,8 +137,9 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
--inherit-motion-from "<base_postflight_report>"
# Quick Generate appends --quick-generate --with-notes to the selected command.
-# For direct MP4 delivery with resolved sound cues, also append
-# --conversion-trace <final_narrated_trace> to that selected export command.
+# For the native-export mix branch with resolved sound cues, also append
+# --conversion-trace <final_narrated_trace>. Slideshow capture does not need
+# that trace for sound delivery.
# 6. When page-local SRT exists, merge it using the final PowerPoint timings
python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \
@@ -149,9 +151,9 @@ python3 skills/ppt-master/scripts/powerpoint_video.py --check
python3 skills/ppt-master/scripts/powerpoint_video.py \
<final_narrated_pptx> -o exports/<raw_powerpoint_video>.mp4
-# 8. When final resolved motion has sound cues, build the independent SFX stem
-# and verified mixed video. Defaults: transitions about 35%, object cues
-# about 25%, final limiter -1 dBFS.
+# 8. On the native-export branch, when final resolved motion has sound cues,
+# build the independent SFX stem and verified mixed video. Defaults:
+# transitions about 35%, object cues about 25%, final limiter -1 dBFS.
python3 skills/ppt-master/scripts/video_sound_mix.py <project_path> \
--pptx <final_narrated_pptx> \
--trace <final_narrated_trace> \
@@ -159,7 +161,8 @@ python3 skills/ppt-master/scripts/video_sound_mix.py <project_path> \
-o exports/<final_mixed_video>.mp4 --force
# 9. When page-local SRT exists, align the frozen narration text against the
-# final video's audio track: mixed when step 8 ran, otherwise raw.
+# final video's audio track: mixed when step 8 ran, accepted capture when
+# slideshow recording was selected, otherwise raw.
python3 skills/ppt-master/scripts/video_subtitles.py <project_path> \
--video "<final_delivery_video>" --language <language> --force
```
@@ -283,6 +286,12 @@ Cloud TTS providers do not require extra Python packages; they use HTTPS directl
Automatic MP4 export adds no Python package. It requires Windows PowerPoint 2016+ and Windows PowerShell; macOS and systems without compatible PowerPoint keep the narrated PPTX and use manual export.
+Real-time slideshow capture adds no PPT Master package. It requires desktop
+Windows PowerPoint plus a recorder that can capture the presentation picture
+and application/system audio. [OBS Studio](https://obsproject.com/kb/quick-start-guide)
+and [Windows Game Bar](https://support.microsoft.com/en-us/accessibility/windows/use-a-screen-reader-to-record-your-screen-with-xbox-game-bar)
+are examples, not project dependencies.
+
Post-export animation-sound mixing requires `ffmpeg` / `ffprobe` on `PATH` and
`numpy`. Final-video subtitle alignment separately requires `stable-ts`:
@@ -298,6 +307,14 @@ python3 -m pip install numpy stable-ts
## Export as video
+Choose one delivery path:
+
+| Path | Use it when | Sound result |
+|---|---|---|
+| Native `CreateVideo` | You want the automated, reproducible path | Narration is native; resolved transition/object cues require `video_sound_mix.py`. |
+| Real-time PowerPoint slideshow capture | You explicitly want the video to contain exactly what PowerPoint plays | The capture already contains narration and native cues; never run `video_sound_mix.py` on it. |
+| Manual **Create a Video** UI | Automation is unavailable but PowerPoint's encoder is acceptable | Same sound boundary as native `CreateVideo`; this is not screen recording. |
+
Once the narrated PPTX is in `exports/`, Windows PowerPoint 2016+ can export it automatically through:
```bash
@@ -316,7 +333,26 @@ unity with reduced cue levels, applies a peak limiter, and publishes an
independent SFX stem plus a machine-readable verification receipt. Align
subtitles against the mixed MP4, not the raw intermediate.
-**Manual PowerPoint fallback (Windows / Mac, Office 2016+)**:
+### Record the live PowerPoint slideshow
+
+This is an explicit real-time capture path. PowerPoint remains the renderer and
+audio player; the recorder only captures its output.
+
+1. Open the final narrated PPTX in desktop Windows PowerPoint and start Slide Show from the beginning. Use the deck's automatic slide and click-free object timings; do not capture edit or Presenter View.
+2. Capture only the full-screen presentation at the deck aspect ratio. Hide notifications and keep the pointer out of frame. The normal target is 1920x1080 at a stable 30 fps.
+3. Enable exactly one application/system-audio capture source and disable the microphone unless live speech was explicitly requested. Do not capture both desktop and application audio, which creates echo; 48 kHz is a preferred recorder setting, not a requirement.
+4. Start before the first slide and stop after the final sound tail. Preserve that raw capture, then trim only the leading and trailing handles.
+5. Confirm that the final file has video and audio streams, narration is intelligible, every configured cue is audible exactly once, animations/transitions completed, and no dropped frames or desktop UI are visible.
+6. When page-local SRT exists, run `video_subtitles.py` against the final trimmed capture. It aligns the frozen narration text to the actual recorded audio.
+
+The current capture acceptance is human-audited; PPT Master does not claim a
+machine cue receipt for it. If cue levels mask narration or clip, repair the
+PPTX/cue assets and record again, or use native export plus the deterministic
+gain/limiter mix. A Linux host can prepare the complete narrated PPTX, audio,
+timings, and subtitles, but this capture step still needs a real desktop
+Windows PowerPoint playback endpoint.
+
+### Manual Create a Video fallback (Windows / Mac, Office 2016+)
1. Open the narrated `.pptx` from `exports/`.
2. **File → Export → Create a Video**.
@@ -333,7 +369,7 @@ path when animation fidelity matters.
**Tips**:
-- **No mic, no recording session needed** — the audio is generated, not recorded. Re-runs reuse the same notes and settings, but cloud models may still produce small nondeterministic differences.
-- **Animation fidelity on Windows** — PowerPoint's Windows video export preserves PPT Master's native visual page transitions and click-free object animation. Animation sound is a separate audio-delivery boundary handled by the post-export mix. Mac movie export has the limitation noted above. See [Animations & Transitions](./animations.md).
+- **Generated narration does not need a microphone** — native export needs no recording session. Real-time slideshow capture records application/system audio with the microphone disabled. Re-runs reuse the same notes and settings, but cloud models may still produce small nondeterministic differences.
+- **Animation fidelity on Windows** — PowerPoint's Windows video export preserves PPT Master's native visual page transitions and click-free object animation. Animation sound uses either the verified post-export mix or the mutually exclusive real-time slideshow capture above. Mac movie export has the limitation noted above. See [Animations & Transitions](./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/technical-design.md b/docs/technical-design.md
index 2d6c9876..52efb1a7 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -688,6 +688,7 @@ The post-processing and export stages keep authoring, validation, preview, deliv
| `exports/<name>_<ts>_narrated.pptx` (via `--recorded-narration` or `--narration-audio-dir`) | embeds matched narration audio; complete recorded mode directly supports auto-play and PowerPoint video export | `--recorded-narration` requires matching audio for every slide and writes duration-plus-padding auto-advance; low-level `--narration-audio-dir` permits partial or zero coverage and writes auto-advance only with `--use-narration-timings` |
| `exports/<narrated_stem>.mp4` (optional via `powerpoint_video.py`) | raw native visual-animation and narration video on Windows PowerPoint 2016+ | delegates to PowerPoint's native encoder and waits for completion; it is final when no native animation sound cues exist, but the encoder does not reliably include those cues in the audio track |
| `exports/<raw_stem>_sfx.wav`, `<raw_stem>_mixed.mp4`, `<raw_stem>_sound_mix.json` (triggered via `video_sound_mix.py`) | sound-enabled direct MP4 delivery when final resolved motion contains transition/object cues | derives timing from the final narrated trace plus page-level raw-video calibration, extracts exact PPTX relationship bytes, copies the video stream, and verifies the actual mixed audio rather than treating PPTX configuration as MP4 acceptance |
+| `exports/<capture_name>.mp4` (explicit operator-supplied slideshow capture) | real-time PowerPoint picture plus the narration and native cues actually played through one application/system-audio path | bypasses `CreateVideo` but not PowerPoint; requires human picture/audio/all-cue acceptance, has no sound-mix receipt, and must never enter `video_sound_mix.py` |
| `backup/<ts>/svg_output/` (default output path only; copy is best-effort after directory creation) | re-export from frozen SVG sources without rerunning the LLM | after successful conversion the exporter creates the backup directory and attempts the copy; explicit `-o` creates none, copy failure does not block export, prints a warning outside quiet mode, and leaves postflight `backup_path` empty, while directory-creation failure remains fatal |
Validation JSON files and `validation/workflow.log` are cold audit artifacts,
@@ -846,6 +847,11 @@ When native transition/object sounds exist, `video_sound_mix.py` remains a
second explicit boundary because PowerPoint may omit them from the encoded
audio. It calibrates the raw MP4, renders a reusable SFX stem, and publishes a
receipt that verifies the mixed output while leaving the canonical PPTX intact.
+An explicitly selected real-time slideshow capture is a separate manual
+boundary: desktop PowerPoint still renders and plays the canonical deck while
+an external recorder captures its picture and one system-audio path. It is not
+cross-platform or headless automation, and its already captured cues make the
+post-export mixer invalid for that file.
---
diff --git a/docs/zh/animations.md b/docs/zh/animations.md
index 31e3f0d3..4f24ac22 100644
--- a/docs/zh/animations.md
+++ b/docs/zh/animations.md
@@ -164,7 +164,8 @@ python3 skills/ppt-master/scripts/sound_sync.py list --query recommended
上述校验只能证明可编辑 PPTX 含有原生 cue,不能证明 PowerPoint 导出的 MP4
音轨含有它。直接交付带旁白且含音效 cue 的视频时,应按
-[音频旁白与视频导出](./audio-narration.md)执行导出后混音。
+[音频旁白与视频导出](./audio-narration.md)选择验收后的原生导出混音,或显式采用
+捕获系统音频的 PowerPoint 实时放映录制;两条路径不能叠加。
## 自定义具体对象
diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.md
index 03d4823a..ecbbee0b 100644
--- a/docs/zh/audio-narration.md
+++ b/docs/zh/audio-narration.md
@@ -14,7 +14,8 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg
- 选择旁白 cue 同步时,规范的 `animations.json` 与逐页 SRT 会派生 `narration_animations.json`,让无点击对象动画等待相关字幕 cue;与旁白无关的自定义动画则保留规范配置中的原始计时。两个动画 sidecar 都不存在时,旁白导出不会创建 sidecar,而是继承基础导出的已解析 motion。存在逐页 SRT 时,这些路径都可以生成与最终 PPTX 时间轴一致的 `<project_path>/audio/total.srt`;PowerPoint 导出视频后,`video_subtitles.py` 可把冻结的旁白文本与实际视频音轨对齐,生成交付用外挂字幕。
- 可选重新导出:在 `exports/` 生成新版 PPTX,每页对应的 `m4a` / `mp3` / `wav` 音频已嵌入到该页,且页面推进时间根据可配置的页前起始下限、音频长度和页尾停留自动设置——无人值守自动播放和视频导出都不用再手动调时间。旁白不会早于页面转场结束时启动。
- Windows 下可选原生视频导出:`powerpoint_video.py` 把最终带旁白 PPTX 交给 PowerPoint 2016+,并等待其原生 MP4 编码成功或失败。该 raw MP4 保留视觉动画与旁白路径,但 PowerPoint 不保证把原生转场音效或对象动画音效写入视频音轨。
-- 直接 MP4 交付存在已解析动画音效时,`video_sound_mix.py` 会生成独立的 float SFX WAV、最终混音 MP4 和 JSON 回执,证明 stem 已进入实际成片音轨,同时视频流保持不变。
+- 原生导出路径直接交付 MP4 且存在已解析动画音效时,`video_sound_mix.py` 会生成独立的 float SFX WAV、最终混音 MP4 和 JSON 回执,证明 stem 已进入实际成片音轨,同时视频流保持不变。
+- 也可以显式选择人工实时录制:用桌面版 Windows PowerPoint 全屏播放最终带旁白 deck,再由录屏器捕获放映画面和唯一一路应用 / 系统音频。它会录下 PowerPoint 实际播放的旁白与原生 cue,因此不能再运行 `video_sound_mix.py`。
- 演讲者备注原样保留。
## 它是怎么做到的
@@ -22,7 +23,7 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg
1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。
2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出候选并给每个写一句中文调性说明(如"稳重男声·适合财报")。语速/风格也会基于 notes 信息密度给出推荐值。
3. **配置一次确定**。Default Generate 和 Enhance Native 会一次确认 provider、音色、语速、是否嵌入 PPTX,以及是否继续导出视频。Quick 直接采用明确值,并自动补齐未指定的 provider、音色、语速和嵌入方式;只有明确要求直接交付视频时才开启视频导出。
-4. **执行**。Edge、ElevenLabs、MiniMax,以及支持时间戳的 CosyVoice 音色,会依据同一次合成返回的 provider 计时,把每页音频和 SRT 一起写入 `audio/`;Qwen 和显式 CosyVoice 纯音频模式只写音频。完整生成成功后会原子写入 `audio/manifest.json` 记录来源。对于选择旁白 cue 同步的 Generate PPTX,逐页 SRT 与规范自定义动画会让 AI 将当前 SVG 内容组映射到编号后的 SRT cue,并派生无点击的 `narration_animations.json`;与旁白无关的自定义动画保留规范计时,没有动画 sidecar 时则继承基础导出的已解析 motion。随后再导出带音频的 PPTX;存在逐页 SRT 时,才从该 PPTX 读回实际计时并合并。若用户选择自动视频导出且本机 Windows PowerPoint 兼容,则继续调用 PowerPoint 原生编码器。最终 narrated trace 与 PPTX 含音效 cue 时,再按逐页旁白校准 raw MP4,混入 PPTX 中实际嵌入的 cue 字节,限幅并验收,最后才对齐交付字幕。不支持长音频导入或自动拆分。
+4. **执行**。Edge、ElevenLabs、MiniMax,以及支持时间戳的 CosyVoice 音色,会依据同一次合成返回的 provider 计时,把每页音频和 SRT 一起写入 `audio/`;Qwen 和显式 CosyVoice 纯音频模式只写音频。完整生成成功后会原子写入 `audio/manifest.json` 记录来源。对于选择旁白 cue 同步的 Generate PPTX,逐页 SRT 与规范自定义动画会让 AI 将当前 SVG 内容组映射到编号后的 SRT cue,并派生无点击的 `narration_animations.json`;与旁白无关的自定义动画保留规范计时,没有动画 sidecar 时则继承基础导出的已解析 motion。随后再导出带音频的 PPTX;存在逐页 SRT 时,才从该 PPTX 读回实际计时并合并。自动视频交付继续调用 PowerPoint 原生编码器,存在 cue 时再完成验收后的混音;显式选择实时放映录制时,则捕获 PowerPoint 实际全屏画面与系统音频、跳过混音,并将交付字幕对齐到验收后的录屏。不支持长音频导入或自动拆分。
字幕保持为外部 SRT 文件:PPT Master 不把字幕嵌入 PPTX,也不烧录进 MP4。自动视频导出委托给本机 Windows PowerPoint,并不是另一套渲染器。
@@ -134,8 +135,8 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
--inherit-motion-from "<base_postflight_report>"
# Quick Generate 在所选命令后追加 --quick-generate --with-notes。
-# 直接 MP4 交付且存在已解析音效 cue 时,还需在所选导出命令中追加
-# --conversion-trace <final_narrated_trace>。
+# 原生导出混音分支存在已解析音效 cue 时,还需在所选导出命令中追加
+# --conversion-trace <final_narrated_trace>;实时放映录制不依赖该 trace 交付声音。
# 6. 存在逐页 SRT 时,按最终 PowerPoint 计时合并
python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \
@@ -146,8 +147,8 @@ python3 skills/ppt-master/scripts/powerpoint_video.py --check
python3 skills/ppt-master/scripts/powerpoint_video.py \
<final_narrated_pptx> -o exports/<raw_powerpoint_video>.mp4
-# 8. 最终 motion 存在音效 cue 时,生成独立 SFX stem 与验收后的混音成片。
-# 默认:转场音约 35%,对象音约 25%,最终限幅 -1 dBFS。
+# 8. 原生导出分支的最终 motion 存在音效 cue 时,生成独立 SFX stem 与
+# 验收后的混音成片。默认:转场音约 35%,对象音约 25%,最终限幅 -1 dBFS。
python3 skills/ppt-master/scripts/video_sound_mix.py <project_path> \
--pptx <final_narrated_pptx> \
--trace <final_narrated_trace> \
@@ -155,7 +156,7 @@ python3 skills/ppt-master/scripts/video_sound_mix.py <project_path> \
-o exports/<final_mixed_video>.mp4 --force
# 9. 存在逐页 SRT 时,把冻结的旁白文本与最终视频音轨对齐;
-# 第 8 步执行过就使用 mixed,否则使用 raw。
+# 第 8 步执行过就使用 mixed,选择录屏则使用验收后的 capture,否则使用 raw。
python3 skills/ppt-master/scripts/video_subtitles.py <project_path> \
--video "<final_delivery_video>" --language <language> --force
```
@@ -275,6 +276,11 @@ python3 -m pip install edge-tts
自动 MP4 导出不增加 Python 依赖,但要求 Windows PowerPoint 2016+ 与 Windows PowerShell;macOS 或没有兼容 PowerPoint 的机器保留带旁白 PPTX,改用手动导出。
+实时放映录制不增加 PPT Master 依赖,但需要桌面版 Windows PowerPoint 和能
+捕获放映画面及应用 / 系统音频的录屏器。[OBS Studio](https://obsproject.com/kb/quick-start-guide)
+和 [Windows Game Bar](https://support.microsoft.com/en-us/accessibility/windows/use-a-screen-reader-to-record-your-screen-with-xbox-game-bar)
+只是可选工具示例,不是项目依赖。
+
导出后混入动画音效需要系统 `PATH` 中可用的 `ffmpeg` / `ffprobe` 以及
`numpy`;最终视频字幕对齐另需 `stable-ts`:
@@ -292,6 +298,14 @@ python3 -m pip install numpy stable-ts
## 导出为视频
+只选择一条交付路径:
+
+| 路径 | 适用情况 | 声音结果 |
+|---|---|---|
+| 原生 `CreateVideo` | 需要自动、可重复的流程 | 原生包含旁白;存在已解析转场 / 对象 cue 时必须运行 `video_sound_mix.py`。 |
+| PowerPoint 实时放映录制 | 明确希望成片包含 PowerPoint 实际播放的全部声音 | 录屏已经包含旁白和原生 cue,不能再运行 `video_sound_mix.py`。 |
+| 手工执行“创建视频” | 自动化不可用,但可以接受 PowerPoint 编码器 | 声音边界与原生 `CreateVideo` 相同;这不是录屏。 |
+
带旁白的 PPTX 在 `exports/` 里就绪后,Windows PowerPoint 2016+ 可通过下面的接口自动导出:
```bash
@@ -308,7 +322,24 @@ narrated trace 含这些 cue 时,按上面的命令运行 `video_sound_mix.py`
与旁白混合,最终经过峰值限幅,并输出独立 SFX stem 与机器可读验收回执。字幕应
基于 mixed MP4 对齐,而不是 raw 中间产物。
-**PowerPoint 手动回退(Windows / Mac,Office 2016+)**:
+### 录制 PowerPoint 实时放映
+
+这是显式选择的实时采集路径。PowerPoint 仍是渲染器和音频播放器,录屏器只负责
+捕获其输出。
+
+1. 用桌面版 Windows PowerPoint 打开最终带旁白 PPTX,从第一页开始全屏放映。使用 deck 已有的自动翻页和无点击对象计时,不录编辑界面或演讲者视图。
+2. 只捕获与 deck 宽高比一致的全屏放映画面,关闭通知,并让鼠标指针离开画面。常规目标为 1920×1080、稳定 30fps。
+3. 只开启一路应用 / 系统音频捕获;除非明确需要现场讲话,否则关闭麦克风。不能同时捕获桌面音频和应用音频,否则会产生回声。48kHz 是推荐录制设置,不是硬要求。
+4. 第一页开始前提前录制,最终声音拖尾结束后再停止。保留原始录屏,然后只裁去首尾缓冲。
+5. 验收最终文件确实包含视频流和音频流,旁白清楚,所有已配置 cue 各出现一次,动画与转场完整,并且没有掉帧、通知或桌面 UI。
+6. 存在逐页 SRT 时,对最终裁切后的录屏运行 `video_subtitles.py`,把冻结旁白文本对齐到真实录制音轨。
+
+当前录屏验收依赖人工检查,PPT Master 不会声称它具有机器化 cue 回执。如果 cue
+盖住旁白或发生削波,应调整 PPTX / cue 素材后重新录制,或改用带确定性增益和限幅
+的原生导出加混音路径。Linux 可以准备完整的带旁白 PPTX、音频、计时和字幕,但
+这一步仍需要真实的桌面版 Windows PowerPoint 播放端。
+
+### 手工“创建视频”回退(Windows / Mac,Office 2016+)
1. 打开 `exports/` 里那份带旁白的 `.pptx`。
2. **文件 → 导出 → 创建视频**。
@@ -323,7 +354,7 @@ PowerPoint for Mac 可以手动导出 MP4/MOV,但微软明确说明其影片
**经验值**:
-- **不需要麦克风、不需要录制环节**——音频是合成的。重跑会复用同一份 notes 与参数,但云端模型仍可能出现轻微的非确定性差异。
-- **Windows 动画保真**:PowerPoint 的 Windows 视频导出会保留 PPT Master 的原生视觉页间转场和无点击对象动画;动画音效属于独立音频交付边界,由导出后混音处理。Mac 影片导出存在上面的限制。详见 [转场与动画](./animations.md)。
+- **生成旁白不需要麦克风**:原生导出也不需要录制环节;实时放映录制捕获应用 / 系统音频,并关闭麦克风。重跑会复用同一份 notes 与参数,但云端模型仍可能出现轻微的非确定性差异。
+- **Windows 动画保真**:PowerPoint 的 Windows 视频导出会保留 PPT Master 的原生视觉页间转场和无点击对象动画;动画音效采用验收后的导出后混音,或与其互斥的实时放映录制。Mac 影片导出存在上面的限制。详见 [转场与动画](./animations.md)。
- **单页改音频**:改对应 `notes/<page>.md`,再跑一遍 `notes_to_audio.py` + 嵌入步骤,再重新导出视频——单页迭代通常不到一分钟。
- **文件大小**:20 页全高清 deck 通常是 30–80 MB,取决于图片量。需要小文件分享时降到高清就行。
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index c17dedea..e84c870e 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -598,6 +598,7 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“
| `exports/<name>_<ts>_narrated.pptx`(经 `--recorded-narration` 或 `--narration-audio-dir` 生成) | 嵌入匹配到的旁白音频;完整录制模式可直接服务自动放映与 PowerPoint 视频导出 | `--recorded-narration` 要求每页匹配音频,并写入“时长 + padding”的自动推进;低层 `--narration-audio-dir` 允许部分或零覆盖,只有另加 `--use-narration-timings` 才写自动推进 |
| `exports/<narrated_stem>.mp4`(可选,经 `powerpoint_video.py`) | Windows PowerPoint 2016+ 下保留原生视觉动画与旁白的 raw 视频 | 委托 PowerPoint 原生编码器并等待完成;没有原生动画音效 cue 时它就是最终视频,但编码器不保证把这些 cue 写入音轨 |
| `exports/<raw_stem>_sfx.wav`、`<raw_stem>_mixed.mp4`、`<raw_stem>_sound_mix.json`(触发式,经 `video_sound_mix.py`) | 最终 motion 含转场 / 对象音效时的带音效 MP4 交付物 | 依据最终 narrated trace 与 raw 视频逐页校准确定时间,从 PPTX relationship 提取准确字节,复制视频流,并验收实际 mixed 音轨,而不是把 PPTX 配置校验当成 MP4 验收 |
+| `exports/<capture_name>.mp4`(显式由操作者提供的实时放映录屏) | PowerPoint 实时画面,以及经唯一一路应用 / 系统音频实际播放的旁白和原生 cue | 绕过 `CreateVideo` 但不绕过 PowerPoint;依赖人工画面 / 音频 / 全部 cue 验收,没有混音回执,并且不得再进入 `video_sound_mix.py` |
| `backup/<ts>/svg_output/`(仅默认输出路径;目录创建后复制为 best-effort) | 在不重跑 LLM 的前提下从冻结 SVG 源重建 pptx | 转换成功后先创建备份目录再尝试复制;显式 `-o` 不创建,复制失败不阻断导出,非 quiet 模式打印 warning,postflight 的 `backup_path` 为空,但目录创建失败仍会中断 |
校验 JSON 与 `validation/workflow.log` 都是冷审计产物,不是常规模型输入。只有用户明确要求复核运行过程时才打开日志。它可以还原项目级 Python 命令及有限的重要结果,而不是完整控制台输出;每条命令的尾部会记录保留与省略的输出行数。日志也允许选择性记录重要阶段交接或返工原因、用户批准的例外及人工恢复选择等非 Python 事项;这些人工记录不重复制品内容、常规页面进度或私有推理,也不能替代当前制品对阶段与就绪状态的判定。导出器在程序内部读取 SVG 质量报告,并在默认非 quiet 流程打印紧凑的 `[POSTFLIGHT]` 回执,包含状态、质量门结果、Slide 数量、warning 类别计数和产物路径。成功流程只消费该回执,不加载两份完整 JSON;只有失败排查或用户明确要求审计时才定向提取报告字段。
@@ -722,7 +723,7 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu
(`after-previous` 或 `with-previous`);该要求按每条解析后的动画行检查,也排除
`trigger_shape`。
-**为什么原生视频导出保持独立命令。** 音频合成和 PPTX 打包属于跨平台项目操作;PowerPoint 视频编码则是 Windows 桌面集成。`powerpoint_video.py` 接收最终带旁白 PPTX,调用 `CreateVideo` 并轮询 `CreateVideoStatus`,对调用方呈现同步结果,同时避免把 Office 自动化耦合进 TTS backend。存在原生转场 / 对象音效时,`video_sound_mix.py` 仍保持第二个显式边界,因为 PowerPoint 可能从编码音轨中省略它们;该工具校准 raw MP4、生成可复用 SFX stem,并在不改变规范 PPTX 的前提下发布 mixed 输出验收回执。
+**为什么原生视频导出保持独立命令。** 音频合成和 PPTX 打包属于跨平台项目操作;PowerPoint 视频编码则是 Windows 桌面集成。`powerpoint_video.py` 接收最终带旁白 PPTX,调用 `CreateVideo` 并轮询 `CreateVideoStatus`,对调用方呈现同步结果,同时避免把 Office 自动化耦合进 TTS backend。存在原生转场 / 对象音效时,`video_sound_mix.py` 仍保持第二个显式边界,因为 PowerPoint 可能从编码音轨中省略它们;该工具校准 raw MP4、生成可复用 SFX stem,并在不改变规范 PPTX 的前提下发布 mixed 输出验收回执。显式选择实时放映录制时则进入另一条人工边界:桌面版 PowerPoint 仍负责渲染和播放规范 deck,外部录屏器只捕获画面与唯一一路系统音频。这不是跨平台或无头自动化,而且录屏已经包含 cue,不能再交给导出后混音器。
---
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index cc8dc5e5..921d6648 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -20,7 +20,7 @@ before the page plan is frozen, not only when a deck is already exported.
| A static full-bleed page that should stop looking frozen | Consider slow `path_*` motion on a visually subordinate image or atmospheric layer; §4.1 gives one starting recipe | Post-processing; §4.1 |
| Carousel, counting numerals, parallax depth, click-to-reveal flip card | Four recurring recipes assembled from the mechanisms above | §4.2 — the carousel and odometer both need paired pages |
| Kiosk or unattended playback | `--auto-advance <seconds>`, optionally with `-t none` | Export; §3 |
-| A transition or object animation needs an audible cue | Optional `transition.sound` or object-animation `sound`; select it only after the visual motion solution is complete, then sync the chosen global-library ids into the project. Direct narrated MP4 delivery uses the separate verified mix in [`generate-audio`](../workflows/stages/generate-audio.md) | Post-motion; §2.2 |
+| A transition or object animation needs an audible cue | Optional `transition.sound` or object-animation `sound`; select it only after the visual motion solution is complete, then sync the chosen global-library ids into the project. For direct narrated MP4 delivery, [`generate-audio`](../workflows/stages/generate-audio.md) selects either the verified native-export mix or explicit real-time slideshow capture; never combine them | Post-motion; §2.2 |
| Nothing should move | `-t none`, and leave per-element animation at its default `none` | Export; §1 |
**Hard rule — Morph geometry is an authoring decision; pairing is a later
@@ -284,8 +284,10 @@ gesture after the corresponding visual behavior is already selected.
package read-back prove the editable PPTX contains the intended native cue;
they do not prove PowerPoint's video encoder placed it in the MP4 audio track.
For direct narrated MP4 delivery with resolved cues, follow `generate-audio`
-and mix from the final narrated trace plus final PPTX. Keep post-production
-gain and limiter settings out of `animations.json`.
+and choose exactly one branch: mix from the final narrated trace plus final
+PPTX after native encoding, or explicitly capture the live PowerPoint Slide
+Show with system audio. Never mix the capture again. Keep post-production gain
+and limiter settings out of `animations.json`.
---
@@ -594,8 +596,10 @@ structural package validation; they do not author or normalize animation
effects.
**Validation boundary**: these checks prove PPTX timing, relationships, and
-embedded sound parts. They are not final-video audio acceptance; a triggered
-`video_sound_mix.py` receipt owns that evidence.
+embedded sound parts. They are not final-video audio acceptance. The
+native-export branch requires a triggered `video_sound_mix.py` receipt; the
+slideshow-capture branch requires the human picture/audio/all-cue acceptance
+owned by `generate-audio` and never claims that receipt.
---
@@ -607,10 +611,12 @@ locks identity, order, effect, direction, and timing; video may refine only its
declared renderer parameters. Unsupported families fail visibly. See
[`video-motion-plan.md`](../scripts/docs/video-motion-plan.md).
-Direct narrated video sound uses the final resolved trace for cue order and
-offsets, the final PPTX relationships for the exact embedded audio bytes, and
-page-level narration correlation for the exported-video clock. It never reads
-sound timing from a raw sidecar or filename.
+On the native-export mix branch, direct narrated video sound uses the final
+resolved trace for cue order and offsets, the final PPTX relationships for the
+exact embedded audio bytes, and page-level narration correlation for the
+exported-video clock. It never reads sound timing from a raw sidecar or
+filename. The explicit slideshow-capture branch records PowerPoint's real-time
+playback instead and does not consume the trace for sound mixing.
---
@@ -622,8 +628,10 @@ sound timing from a raw sidecar or filename.
- PowerPoint OOXML is the compatibility target; other presentation apps may
reinterpret individual native behavior trees.
- PowerPoint's native MP4 encoder may omit transition and object-animation
- sounds even when the PPTX package is valid; direct sound-enabled MP4 delivery
- therefore uses the post-export mix owned by `generate-audio`.
+ sounds even when the PPTX package is valid. Direct sound-enabled MP4 delivery
+ therefore uses either the post-export mix or the explicit real-time
+ slideshow-capture contract owned by `generate-audio`; the branches never
+ stack.
- Direct-PPTX routes preserve unknown transition `AlternateContent`; timing
edits keep Choice and Fallback advance attributes synchronized.
diff --git a/skills/ppt-master/references/video-design.md b/skills/ppt-master/references/video-design.md
index 021f6308..1edd89df 100644
--- a/skills/ppt-master/references/video-design.md
+++ b/skills/ppt-master/references/video-design.md
@@ -197,9 +197,10 @@ and the object-sync claim.
**Sound effects**: exclude them from this pass and planning artifacts. After
final SVG/motion, animation post-processing owns on-demand selection and native
PPTX configuration; otherwise remain silent. For direct narrated MP4 delivery,
-`generate-audio` additionally owns the triggered post-export mix when the final
-resolved motion contains sound cues. Video gain and limiting never enter
-`animations.json`.
+`generate-audio` owns the selected sound-delivery branch: native PowerPoint
+encoding plus triggered post-export mix, or an explicitly requested real-time
+PowerPoint slideshow capture. Video gain and limiting never enter
+`animations.json`; capture uses the balance actually heard during Slide Show.
**Production sequence**: after the final SVG check, validate any pre-SVG
narration against the visible pages; ordinary draft-source runs instead use the
@@ -217,20 +218,27 @@ object-sync claim before the narrated PPTX and MP4.
**Canonical artifact**: the editable PPTX remains canonical. `generate-audio`
owns provider/voice/rate selection, page audio/SRT generation, semantic
narration timing, narrated PPTX export, optional native PowerPoint video export,
-and the triggered sound-effects mix for direct MP4 delivery.
-
-**Conditional MP4**: run `powerpoint_video.py --check` only when MP4 delivery is
-selected. If native Windows PowerPoint export is unavailable, keep the narrated
-PPTX as the successful upstream artifact; do not substitute screenshots, HTML,
-or a third-party renderer and call it equivalent.
-
-**Hard rule — native MP4 sound boundary**: PowerPoint's native encoder is the
-visual-animation and narration source, but it does not reliably include
-transition or object-animation sounds in the MP4 audio track. When the final
-narrated trace and PPTX contain sound cues, treat that native MP4 as a raw
-intermediate and run `video_sound_mix.py`; only its verified mixed MP4 is the
-sound-enabled video deliverable. Keep the native cue configuration in the
-canonical PPTX.
+the explicit slideshow-capture handoff, and the triggered sound-effects mix for
+direct MP4 delivery.
+
+**Conditional MP4**: run `powerpoint_video.py --check` only for the native-export
+branch. If native Windows PowerPoint export is unavailable, keep the narrated
+PPTX as the successful upstream artifact. An explicit slideshow-capture choice
+may hand that artifact to a user-operated Windows PowerPoint recorder; it is not
+complete until the capture is returned and accepted. Do not substitute
+screenshots, HTML, or a third-party renderer and call it equivalent.
+
+**Hard rule — choose one PowerPoint video sound boundary**:
+
+| Delivery branch | Sound contract |
+|---|---|
+| Native encoder | PowerPoint supplies visual animation and narration but may omit transition/object sounds. With resolved cues, treat its MP4 as raw and require the verified `video_sound_mix.py` output. |
+| Real-time slideshow capture | PowerPoint remains the renderer and audio player; a recorder captures the full-screen Slide Show and exactly one application/system-audio source. The accepted capture must contain narration and every configured cue once, and must not enter `video_sound_mix.py`. |
+
+The branches are mutually exclusive because mixing a capture would duplicate
+its cues. Keep the native cue configuration in the canonical PPTX. Slideshow
+capture is explicit and human-audited; it does not inherit the native mix
+receipt or become an automatic fallback.
**Current boundary**: importing and automatically splitting one long finished
recording is unsupported. Require page-level audio or an explicit page/time map;
diff --git a/skills/ppt-master/scripts/video_subtitles.py b/skills/ppt-master/scripts/video_subtitles.py
index 9fe6f05c..62e6b02d 100644
--- a/skills/ppt-master/scripts/video_subtitles.py
+++ b/skills/ppt-master/scripts/video_subtitles.py
@@ -2,10 +2,10 @@
"""
PPT Master - Final Video Subtitles
-Align the exact narration text frozen in page-local narration SRT files against the
-audio track of a finished PowerPoint-exported video. This produces a delivery
-SRT from the actual video timeline without rewriting speaker notes or relying
-on theoretical slide offsets.
+Align the exact narration text frozen in page-local narration SRT files against
+the audio track of a finished PowerPoint-exported or slideshow-captured video.
+This produces a delivery SRT from the actual video timeline without rewriting
+speaker notes or relying on theoretical slide offsets.
Usage:
python3 scripts/video_subtitles.py <project_path> --video <video> --language <language>
@@ -311,7 +311,10 @@ def build_parser() -> argparse.ArgumentParser:
parser.add_argument(
"--video",
required=True,
- help="Finished PowerPoint-exported video; relative paths are project-relative",
+ help=(
+ "Finished PowerPoint-exported or slideshow-captured video; "
+ "relative paths are project-relative"
+ ),
)
parser.add_argument(
"--language",
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index fc2b7318..2d7e7f14 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -789,10 +789,13 @@ activating object choreography; the exporter never reads
`templates/sounds/` directly.
When downstream delivery is a narrated MP4 and the resolved final motion has
-sound cues, `generate-audio` owns a final narrated export with
-`--conversion-trace`, native PowerPoint raw-video export, and the verified
-post-export sound mix. Do not enable conversion trace on every base export only
-for this possible downstream branch.
+sound cues, `generate-audio` owns the final sound-delivery choice. Its default
+automated branch uses a final narrated export with `--conversion-trace`, native
+PowerPoint raw-video export, and the verified post-export sound mix. An
+explicit real-time slideshow capture instead records PowerPoint playback with
+system audio and skips both conversion-trace-only work and sound mixing. Do not
+enable conversion trace on every base export only for a possible downstream
+branch.
**Success criterion**: The command exits successfully and produces:
diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.md
index bc8c4908..77bc6d27 100644
--- a/skills/ppt-master/workflows/profiles/quick-generate.md
+++ b/skills/ppt-master/workflows/profiles/quick-generate.md
@@ -564,8 +564,9 @@ deck-wide-only motion through the selected exporter flags instead.
After visual motion is final, sync a selected cue per
[`animations.md`](../../references/animations.md) §2.2; otherwise create no
`sounds/`. Sidecars never use `templates/sounds/`. This configures the native
-PPTX only; direct narrated MP4 delivery with resolved cues completes the
-verified post-export mix in `generate-audio`.
+PPTX only; `generate-audio` completes direct narrated MP4 delivery with either
+the verified native-export mix or an explicitly selected real-time PowerPoint
+slideshow capture. Those sound branches are mutually exclusive.
For Quick recorded/self-running/video delivery, complete the mandatory Custom
Animations stage and validate `animations.json` before the base export unless
@@ -594,7 +595,8 @@ selected by the agent or required by the Quick video rule above. Do not run
`finalize_svg.py`. After the validated base export, run
[`generate-audio`](../stages/generate-audio.md) when Narration Audio is enabled;
it owns page audio/SRT, narrated PPTX, the optional raw native MP4, and the
-final mixed MP4 when resolved animation sound cues trigger that branch.
+final mixed or captured MP4. When a selected manual capture has not yet been
+returned, it owns the capture-ready narrated PPTX handoff instead.
The exporter requires a passing `final` report whose SVG fingerprint matches
the current `svg_output/`; missing, blocking, non-final, or stale reports stop
@@ -618,5 +620,5 @@ or lock.
- [x] Enabled notes were validated/generated and split; enabled custom motion ran through its owning stage
- [x] One native PPTX exists under `exports/` or the explicit output path
- [x] No Strategist, confirmation, root project Design Spec, or lock artifact was created
-- [ ] **Next**: Report the base PPTX and any enabled narrated PPTX/raw or mixed MP4 outputs
+- [ ] **Next**: Report the base PPTX and any enabled narrated PPTX, raw/mixed/captured MP4, or capture-ready PPTX handoff
```
diff --git a/skills/ppt-master/workflows/stages/customize-animations.md b/skills/ppt-master/workflows/stages/customize-animations.md
index 12af05a4..db9f476b 100644
--- a/skills/ppt-master/workflows/stages/customize-animations.md
+++ b/skills/ppt-master/workflows/stages/customize-animations.md
@@ -471,11 +471,13 @@ python3 skills/ppt-master/scripts/video_motion_plan.py \
```
For narrated output, use the final `--recorded-narration` trace. When resolved
-sound cues exist and direct MP4 delivery is selected, that same final trace and
-the final narrated PPTX feed `video_sound_mix.py`; never infer cue timing from
-the raw sidecar or filenames. The video plan locks identity, effect, direction,
-order, bounds, and timing; it may refine renderer parameters but cannot replace
-the source effect. See
+sound cues exist and the native-export mix branch is selected, that same final
+trace and the final narrated PPTX feed `video_sound_mix.py`; never infer cue
+timing from the raw sidecar or filenames. An explicit slideshow capture already
+records PowerPoint's native cue playback and does not use the trace for sound
+mixing. The video plan locks identity, effect, direction, order, bounds, and
+timing; it may refine renderer parameters but cannot replace the source effect.
+See
[`video-motion-plan.md`](../../scripts/docs/video-motion-plan.md).
---
diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.md
index 7a844d95..75554136 100644
--- a/skills/ppt-master/workflows/stages/generate-audio.md
+++ b/skills/ppt-master/workflows/stages/generate-audio.md
@@ -1,5 +1,5 @@
---
-description: Shared post-processing stage for narration audio, PPTX embedding, native video export, and triggered sound mixing.
+description: Shared post-processing stage for narration audio, PPTX embedding, PowerPoint video delivery, and triggered sound mixing.
---
# Generate Audio Stage
@@ -35,6 +35,8 @@ this stage.
- Optional automatic video export requires Windows PowerPoint 2016+ and runs
through `powerpoint_video.py`; the command waits for PowerPoint's native
encoder to finish before returning.
+- Optional slideshow capture is an explicit manual Windows PowerPoint handoff;
+ it is never an automatic fallback or project dependency.
- macOS PowerPoint may export MP4/MOV manually, but it has no equivalent
`CreateVideo` automation contract and its movie export does not preserve
animation effects. Do not replace the missing API with UI scripting.
@@ -118,13 +120,18 @@ rules below. Keep video off unless the caller selected direct video; then embed
the narrated PPTX and continue to native video only when
`powerpoint_video.py --check` succeeds. If final resolved motion contains sound
cues, continue automatically through the post-export mix without another
-question. Require a timestamp-capable provider only when narration-cue sync or
-subtitle delivery needs page-local SRT; audio-only narration can still calibrate
-the sound mix from its complete per-page tracks.
+question. An explicit slideshow-capture request instead stops at the
+capture-ready narrated PPTX until the user supplies the recorded MP4; it never
+silently switches to native export. Require a timestamp-capable provider only
+when narration-cue sync or subtitle delivery needs page-local SRT; on the
+native-export branch, audio-only narration can still calibrate the sound mix
+from its complete per-page tracks.
**Default / Enhance Native — one-shot interaction (mandatory)**:
For Default or Enhance Native, send one message that resolves all five configuration decisions and recommends each value. Before offering automatic video export, run `python3 skills/ppt-master/scripts/powerpoint_video.py --check`; do not present an unavailable local capability as executable. Do NOT split into multiple rounds.
+An explicit slideshow-capture choice does not run this availability check; it
+uses the manual Windows playback handoff below.
**Cloned-voice fast path**: if the user mentioned a cloned voice / 克隆音色 / 复刻音色 / "my own voice" along with a `voice_id`, skip the voice-recommendation list — set the named provider (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) and pin that `voice_id`. Quick applies its exception above; Default and Enhance Native confirm only rate + embed + video.
@@ -146,7 +153,7 @@ For Default or Enhance Native, send one message that resolves all five configura
>
> **生成完是否重新导出嵌入音频的 PPTX**:⭐ 推荐 **是**(一次到位,自动按音频时长设页面停留)。
>
-> **带音频 PPTX 完成后是否继续导出视频**:⭐ 推荐 **是**(仅在本机 Windows PowerPoint 2016+ 可用时;将等待原生视频导出完成)。
+> **带音频 PPTX 完成后是否继续导出视频**:⭐ 推荐 **原生编码**(本机 Windows PowerPoint 2016+ 可用时)。需要录下实际放映声音时可选 **实时放映录制**。
>
> 直接回"好"用全部推荐值,或告诉我想改的部分(如"音色 2,语速 -5%"或"用 MiniMax 的 voice_id xxx")。
@@ -155,7 +162,7 @@ For Default or Enhance Native, send one message that resolves all five configura
- 音色:从 Step 2 候选里挑最贴合 deck 调性的那一个。
- 语速:edge 默认 `+0%`;notes 字数密集(页均 >4 句长句)建议 `-5%`;notes 简短紧凑建议 `+5%`;超出此范围需说明理由。Cloud providers 默认用 provider defaults,除非用户明确要调速或改风格。
- 嵌入:默认推荐"是";除非用户已有定制 PPTX 不希望覆盖。
-- 视频:`powerpoint_video.py --check` 成功时默认推荐"是";不可用时说明只能交付带音频 PPTX,不自动改用第三方渲染器。
+- 视频:`powerpoint_video.py --check` 成功时默认推荐"原生编码";只有用户明确选择时才使用"实时放映录制"。自动化不可用时交付带音频 PPTX;不得静默改用录屏或第三方渲染器。
---
@@ -207,8 +214,9 @@ python3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \
# 2B. Re-export with audio embedded
# Use the base export's [REPORT] path to preserve source-bound deck motion.
# Quick Generate adds --quick-generate --with-notes to every re-export below.
-# For direct MP4 delivery when final motion has sound cues, also pass
-# --conversion-trace <final_narrated_trace> on the selected export command.
+# For the native-export mix branch when final motion has sound cues, also
+# pass --conversion-trace <final_narrated_trace>. Explicit slideshow capture
+# does not require that trace for sound delivery.
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
--recorded-narration audio \
--narration-start-floor 0.8 --narration-padding 0.5 \
@@ -251,11 +259,22 @@ python3 skills/ppt-master/scripts/video_sound_mix.py <project_path> \
--report-output <sound_mix_report.json> --force
# 2F. Only when page-local SRT exists, align the frozen narration text against
-# the final delivery video: mixed when 2E ran, otherwise the raw video.
+# the final delivery video: mixed when 2E ran, captured when the explicit
+# slideshow-capture handoff returned an MP4, otherwise the raw video.
python3 skills/ppt-master/scripts/video_subtitles.py <project_path> \
--video <final_delivery_video.mp4> --language <language> --force
```
+**Explicit slideshow capture**: desktop Windows PowerPoint plays the final
+narrated PPTX full-screen from the beginning with automatic, click-free timing;
+capture only the deck frame and one application/system-audio source, with mic,
+UI, pointer, and notifications absent. Trim short head/tail handles. Human-check
+streams, narration, every cue once, complete motion, and no dropped frames. The
+capture has no machine cue receipt and must never enter `video_sound_mix.py`.
+If the host cannot capture, report only the capture-ready PPTX handoff. Align
+page SRT against an accepted capture and append one compact `workflow_log.py`
+note.
+
**Default — bounded Edge concurrency (may override)**: Generate up to three
slide-level audio/SRT pairs concurrently. Use `--concurrency <N>` to tune the
Edge path or `--concurrency 1` for serial troubleshooting. Cloud providers
@@ -351,46 +370,52 @@ MP4 succeeds, fails, or times out. The interface is synchronous to its caller
even though PowerPoint performs encoding asynchronously. It preserves the
native visual-animation and narration path rather than re-rendering the deck,
but does not reliably write transition or object-animation sounds into the MP4
-audio track.
+audio track. This is the default automated video path; an explicitly selected
+slideshow capture bypasses `CreateVideo` but still uses desktop PowerPoint as
+the real-time renderer and audio player.
If native video export fails, keep the narrated PPTX as a successful upstream
artifact and report the video failure separately. Do not regenerate audio or
the PPTX unless their own validation failed.
-When the final narrated trace and PPTX contain sound cues, treat the PowerPoint
-MP4 as a raw intermediate. `video_sound_mix.py` cross-checks that trace against
-the final PPTX read-back, extracts the exact embedded sound relationships,
-calibrates every page against the raw video's narration, renders a float SFX
-stem, and mixes it with narration at unity gain. Transition cues default to
-about 35%, object cues to about 25%; `amix` normalization and ducking remain off,
-and a -1 dBFS peak limiter follows the mix. The receipt must prove a non-silent
-stem, preserved video-stream hash, changed and present final audio, duration
-parity, non-clipping true peak, and correlation between the added final-audio
-component and the stem. A valid `animations.json` or OOXML package alone is not
-MP4 audio acceptance.
+On the native-export path, when the final narrated trace and PPTX contain sound
+cues, treat the PowerPoint MP4 as a raw intermediate. `video_sound_mix.py`
+cross-checks that trace against the final PPTX read-back, extracts the exact
+embedded sound relationships, calibrates every page against the raw video's
+narration, renders a float SFX stem, and mixes it with narration at unity gain.
+Transition cues default to about 35%, object cues to about 25%; `amix`
+normalization and ducking remain off, and a -1 dBFS peak limiter follows the
+mix. The receipt must prove a non-silent stem, preserved video-stream hash,
+changed and present final audio, duration parity, non-clipping true peak, and
+correlation between the added final-audio component and the stem. A valid
+`animations.json` or OOXML package alone is not MP4 audio acceptance.
After the final delivery MP4 exists, `video_subtitles.py` takes the exact
narration text frozen in the page SRT set and force-aligns it against that
finished video's actual audio track with `stable-ts`. Use the mixed MP4 when
-sound mixing ran; otherwise use the raw PowerPoint MP4. Long delivery cues may
-be split for display at this final stage. This writes a same-stem external SRT
-without changing the MP4, notes, page SRT, or animation files.
+sound mixing ran, the accepted capture when slideshow recording ran, otherwise
+the raw PowerPoint MP4. Long delivery cues may be split for display at this
+final stage. This writes a same-stem external SRT without changing the MP4,
+notes, page SRT, or animation files.
-This stage keeps subtitles as external SRT files. It does not burn subtitles into the video. Automatic MP4 export is an optional Windows PowerPoint integration, not an independent renderer; when PowerPoint automation is unavailable, stop after the narrated PPTX instead of claiming a downgraded video.
+This stage keeps subtitles as external SRT files and never burns them in.
+Automatic export is an optional Windows PowerPoint integration. When it is
+unavailable, stop after the narrated PPTX unless explicit capture is selected;
+that handoff remains incomplete until a real capture is accepted.
**Caller integration**:
| Caller | After audio generation |
|---|---|
-| Generate PPTX | When narration-cue sync is selected, combine page-local SRT with `animations.json` and derive `narration_animations.json`; narration-independent custom motion passes `--animation-config animations.json`; with no sidecar, inherit the base report's resolved motion, while explicit all-motion-off uses `--no-animations`. Export with `--recorded-narration audio`; Quick also passes `--quick-generate --with-notes`. For direct MP4 with resolved sound cues, add the final narrated conversion trace, export a raw PowerPoint MP4, run `video_sound_mix.py`, then align delivery subtitles against the mixed MP4. With no cues, the raw MP4 is final. |
-| Enhance Native PPTX | Return to [`native-enhance-pptx`](../native-enhance-pptx.md) Step 9; its `apply` command owns audio relationships, timings, transitions, and the enhanced export. If video was selected, pass that final PPTX to `powerpoint_video.py`. |
+| Generate PPTX | Derive narration-cued motion when selected; otherwise pass canonical motion, inherit base motion, or use explicit all-motion-off. Export with `--recorded-narration audio`; Quick also passes `--quick-generate --with-notes`. Native video uses conversion trace plus raw export and cue mix as required. Explicit capture returns the narrated PPTX for the handoff above, skips trace-only sound work and mixing, then aligns subtitles against the accepted capture. |
+| Enhance Native PPTX | Return to [`native-enhance-pptx`](../native-enhance-pptx.md) Step 9. Native video passes its final PPTX to `powerpoint_video.py`; explicit capture uses the same handoff above and skips mixing. |
For Qwen or explicit CosyVoice audio-only mode, embed/export the audio normally
but skip `narration_timing.json`, `narration_sync.py animations`, SRT merge, and
final-video subtitle alignment. Pass canonical narration-independent custom
-motion explicitly when present. A direct-MP4 sound mix may still run because
-page audio, not SRT, supplies its correlation template. Never present missing
-subtitle artifacts or object sync as generated.
+motion explicitly when present. On the native-export branch, a direct-MP4 sound
+mix may still run because page audio, not SRT, supplies its correlation
+template. Never present missing subtitle artifacts or object sync as generated.
For Generate PPTX, `--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. Narration changes the slide-advance layer only: the resolved page-transition effect remains unchanged, `-t none` remains visually transition-free, and narration advance disables click while using page-start lead-in plus audio duration plus page-tail padding. The re-export is saved as `exports/<project_name>_<timestamp>_narrated.pptx`, telling it apart from silent exports.
@@ -407,13 +432,16 @@ Output one summary block listing:
- Narration provider/model plus the `<project_path>/audio/manifest.json` provenance path.
- For narrated object animation, whether current SVG semantics were reused or which missing/stale pages were reread, plus semantic mapping coverage and fallback count.
- For Generate PPTX, report derived narration animation coverage/path when cue sync ran, the canonical config path for narration-independent custom motion, or inherited/all-motion-off state.
-- When video export was selected, the raw PowerPoint MP4 path/status. When
- resolved cues triggered sound mixing, also report the final mixed MP4, SFX
- stem, cue count, and `video_sound_mix.py` receipt; otherwise identify the raw
- MP4 as final.
+- When native video export was selected, the raw PowerPoint MP4 path/status.
+ When resolved cues triggered sound mixing, also report the final mixed MP4,
+ SFX stem, cue count, and `video_sound_mix.py` receipt; otherwise identify the
+ raw MP4 as final.
+- For slideshow capture, report the capture-ready PPTX handoff or accepted MP4
+ plus system-audio and human picture/narration/all-cue status; never report a
+ mix receipt.
- When page-local SRT was merged, the PPTX-timeline `audio/total.srt` path.
- When final-video subtitle alignment ran, the aligned delivery SRT path and
- whether its source was the mixed or raw final video;
+ whether its source was the mixed, captured, or raw final video;
otherwise do not claim a video-aligned subtitle.
- The provider, voice, and rate/settings actually used.
- The caller-owned integration result: narrated SVG export path, enhanced native PPTX path, or “audio only”.