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
fix(video): preserve Quick narration motion choices
hugohe37106f0a38f05
diff --git a/docs/audio-narration.md b/docs/audio-narration.mdindex 1a6ea4f9..5a158a1f 100644--- a/docs/audio-narration.md+++ b/docs/audio-narration.md@@ -11,7 +11,7 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](- One audio file per slide under `<project_path>/audio/`, named to match the SVG (`01_cover.mp3`, `02_market_landscape.mp3`, …).- With provider-timed subtitles, one matching subtitle file per slide in the same `<project_path>/audio/` directory (`01_cover.srt`, `02_market_landscape.srt`, …). Each file uses a page-local timeline with a `00:00:00,000` origin. Provider word/character timings are regrouped into the same compact cue format.- One compact `<project_path>/audio/manifest.json` after a complete successful run. It records only provider/model, audio/subtitle format, relevant voice settings, and a SHA-256 fingerprint instead of a raw cloud voice ID. It contains no per-slide inventory, artifact hashes, or API keys and is not loaded during normal generation.-- When canonical `animations.json` exists and page-local SRT is available, an SVG-to-SRT timing plan derives `narration_animations.json` whose click-free object animations wait for the relevant subtitle cue. When neither animation sidecar exists, narrated export creates no sidecar and keeps the default `fade` page transition with no per-element builds. With page-local SRT, both paths can produce a deck-wide `<project_path>/audio/total.srt` aligned to the final PPTX timeline; after PowerPoint exports a video, the same command can calibrate page starts against its audio track for frame-accurate sidecar subtitles.+- 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.- The original speaker notes are preserved.@@ -20,8 +20,8 @@ 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. **One question, one answer.** You are asked once — provider, voice, rate, "embed audio back into PPTX", and "continue to video" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.-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 page-local SRT and canonical custom animation, the AI maps current SVG content groups to numbered SRT cues and derives click-free `narration_animations.json`; without animation sidecars, it skips that derivation and retains `fade` / no per-element builds. 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 and waits for the MP4 before aligning the delivery SRT when available. Long-audio import and automatic long-audio splitting are not supported.+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 and waits for the MP4 before aligning the delivery SRT when available. 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.@@ -102,22 +102,39 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \--voice-id <cosyvoice-voice> \--cosyvoice-model cosyvoice-v3-flash-# 3-4. Only when page-local SRT and canonical animations.json exist, print the SRT-set-# fingerprint, then author+# 3-4. Only when narration-cue sync is selected and page-local SRT plus canonical+# animations.json exist, print the SRT-set fingerprint, then author# <project_path>/narration_timing.json by comparing each current# SVG content group with the numbered cues in that page's SRT. A missing# cue means the group has no spoken counterpart and uses normal sequencing.-# When neither animation sidecar exists, skip directly to step 5.+# For narration-independent custom motion or no sidecar, skip to step 5.python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path># 4. Derive click-free narration_animations.json from canonical animations.jsonpython3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \--narration-start-floor 0.8 --narration-padding 0.5 --force-# 5. Re-export PPTX with audio embedded+# 5A. Cue-synchronized custom motion: use the derived sidecarpython3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \-o <final_narrated_pptx> --recorded-narration audio \- --narration-start-floor 0.8 --narration-padding 0.5+ --narration-start-floor 0.8 --narration-padding 0.5 \+ --animation-config narration_animations.json \+ --inherit-motion-from "<base_postflight_report>"++# 5B. Narration-independent custom motion: use canonical timing+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \+ -o <final_narrated_pptx> --recorded-narration audio \+ --narration-start-floor 0.8 --narration-padding 0.5 \+ --animation-config animations.json \+ --inherit-motion-from "<base_postflight_report>"++# 5C. No animation sidecar: inherit resolved base motion, including -a auto+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \+ -o <final_narrated_pptx> --recorded-narration audio \+ --narration-start-floor 0.8 --narration-padding 0.5 \+ --inherit-motion-from "<base_postflight_report>"++# Quick Generate appends --quick-generate --with-notes to the selected command.# 6. When page-local SRT exists, merge it using the final PowerPoint timingspython3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \@@ -128,11 +145,10 @@ python3 skills/ppt-master/scripts/powerpoint_video.py --checkpython3 skills/ppt-master/scripts/powerpoint_video.py \<final_narrated_pptx> -o exports/<final_video>.mp4-# 8. When page-local SRT exists, calibrate page starts against the exported-# audio track and write a same-stem sidecar SRT-python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \- --pptx <final_narrated_pptx> --video <powerpoint_exported_video> \- -o exports/<powerpoint_exported_video_stem>.srt --force+# 8. When page-local SRT exists, align the frozen narration text against the+# exported video's audio track and write a same-stem delivery SRT+python3 skills/ppt-master/scripts/video_subtitles.py <project_path> \+ --video "<powerpoint_exported_video>" --language <language> --force```Before sending any TTS request, `notes_to_audio.py` verifies that every@@ -171,9 +187,9 @@ Alibaba Cloud's current [TTS model guide](https://www.alibabacloud.com/help/en/m`audio/` is the single active narration set. The manifest records its source, so provider subdirectories are not created by default. Before regeneration, the script removes stale `manifest.json` and `total.srt`; audio-only providers also remove same-stem stale page SRT files. Use a separate explicit output directory only when you intentionally need to preserve an alternate provider run.-When canonical custom animation exists, `narration_timing.json` remains deliberately separate from read-only `animations.json`. It records the ordered SRT-set SHA-256, optional narration start floor, narration padding, ordered SVG group IDs, and optional 1-based cue numbers. `narration_sync.py animations` rejects a stale fingerprint, validates the group IDs against the current SVGs, and writes the derived `narration_animations.json` with only supported PowerPoint fields. Cue-bound animation starts use the same page-start floor as the embedded audio; uncued title or decorative animation keeps its canonical relative timing. A group with `effects[]` still maps to one cue: its first active row is anchored to that cue, while later rows retain their relative delay. With no animation sidecars, skip that derivation. `narration_sync.py subtitles` reads the final PPTX's actual presentation order plus millisecond transition, narration-delay, and slide-advance values, so `total.srt` follows the native PPTX timeline. A relative `--pptx` path is resolved under `<project_path>`.+When narration-cue synchronization is selected with canonical custom animation, `narration_timing.json` remains deliberately separate from read-only `animations.json`. It records the ordered SRT-set SHA-256, optional narration start floor, narration padding, ordered SVG group IDs, and optional 1-based cue numbers. `narration_sync.py animations` rejects a stale fingerprint, validates the group IDs against the current SVGs, and writes the derived `narration_animations.json` with only supported PowerPoint fields. Cue-bound animation starts use the same page-start floor as the embedded audio; uncued title or decorative animation keeps its canonical relative timing. A group with `effects[]` still maps to one cue: its first active row is anchored to that cue, while later rows retain their relative delay. Narration-independent custom motion passes canonical `animations.json` directly; with no sidecar, inherit the base report's resolved motion. `narration_sync.py subtitles` reads the final PPTX's actual presentation order plus millisecond transition, narration-delay, and slide-advance values, so `total.srt` follows the native PPTX timeline. A relative `--pptx` path is resolved under `<project_path>`.-PowerPoint's video encoder can quantize each slide/media segment to its output frame clock. Those small per-page differences may accumulate even when the PPTX timing values are correct. Passing the finished `.mp4` / `.wmv` / `.mov` with `--video` uses normalized audio correlation to locate each original page narration in the exported audio track. It changes only the page-level offsets: the provider's cue text and page-local timing remain untouched. This is a post-export subtitle calibration step and does not rewrite the video.+PowerPoint's video encoder can quantize each slide/media segment to its output frame clock. Those small per-page differences may accumulate even when the PPTX timing values are correct. `video_subtitles.py` uses `stable-ts` to force-align the exact frozen narration text against the finished `.mp4` / `.wmv` / `.mov` audio track. It may split long delivery cues for display, writes a same-stem SRT, and does not rewrite the video, notes, or page-local subtitles.Use the default text-flow mode for the final narrated SVG export. It keeps authored line breaks in one editable, no-wrap text frame; narration does not require per-line text frames.@@ -254,6 +270,12 @@ Cloud TTS providers do not require extra Python packages; they use HTTPS directlAutomatic 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.+Final-video subtitle alignment additionally requires `ffmpeg` on `PATH` and `stable-ts`:++```bash+python3 -m pip install stable-ts+```+## Tips- **Pacing**: On the Generate PPTX route, speaker notes scale with the independent information groups in the final SVG; 2–5 sentences is a typical rhythm, not a cap. Start with `+0%`; for a dense, deliberately detailed script, try `-5%`.@@ -277,7 +299,7 @@ The command uses recorded timings and narrations, defaults to 1080p/30 fps, and2. **File → Export → Create a Video**.3. Pick a quality and "Use Recorded Timings and Narrations".4. Save as `.mp4` (`.wmv` is also available on Windows).-5. Run the optional subtitle calibration command above and place its same-stem SRT beside the video.+5. Run the optional `video_subtitles.py` alignment command above; it writes the same-stem SRT beside the video.PowerPoint for Mac can export MP4/MOV manually, but Microsoft documents thatanimation effects do not play in its movie export. Use the Windows automationdiff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex 59d480c2..3c37ec47 100644--- a/docs/zh/audio-narration.md+++ b/docs/zh/audio-narration.md@@ -11,7 +11,7 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg- 每页一个音频文件,存放于 `<project_path>/audio/`,文件名与 SVG 对齐(`01_cover.mp3`、`02_market_landscape.mp3` …)。- 使用 provider 原生计时字幕时,每页还有一个同名字幕文件,与音频一起存放于 `<project_path>/audio/`(`01_cover.srt`、`02_market_landscape.srt` …)。每个文件使用以 `00:00:00,000` 为原点的页内时间轴;provider 的词级或字符级时间戳都会重组为同一套紧凑 cue。- 完整生成成功后写出精简的 `<project_path>/audio/manifest.json`,只记录 provider、模型、音频/字幕格式、相关音色参数,以及代替云端 voice ID 原文的 SHA-256 指纹;不包含逐页清单、产物哈希或 API Key,正常生成过程也不会读取它。-- 存在规范的 `animations.json` 且已有逐页 SRT 时,SVG 到 SRT 的计时计划会派生 `narration_animations.json`,让无点击对象动画等待相关字幕 cue。两个动画 sidecar 都不存在时,旁白导出不会创建 sidecar,而是保留默认 `fade` 页间切换和无逐元素动画。存在逐页 SRT 时,两条路径都可以生成与最终 PPTX 时间轴一致的 `<project_path>/audio/total.srt`;PowerPoint 导出视频后,还可用同一命令根据视频音轨校准每页起点,得到帧级对齐的外挂字幕。+- 选择旁白 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 编码成功或失败。- 演讲者备注原样保留。@@ -20,8 +20,8 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出候选并给每个写一句中文调性说明(如"稳重男声·适合财报")。语速/风格也会基于 notes 信息密度给出推荐值。-3. **一次问完,一次回答**。AI 在一条消息里同时确认 provider、音色、语速、是否嵌入 PPTX,以及是否继续导出视频;每项都标推荐值。回"好"接受全部默认,或者只说要改的部分(如"音色 2,语速 -5%")。-4. **执行**。Edge、ElevenLabs、MiniMax,以及支持时间戳的 CosyVoice 音色,会依据同一次合成返回的 provider 计时,把每页音频和 SRT 一起写入 `audio/`;Qwen 和显式 CosyVoice 纯音频模式只写音频。完整生成成功后会原子写入 `audio/manifest.json` 记录来源。对于已有逐页 SRT 且存在规范自定义动画的 Generate PPTX,AI 将当前 SVG 内容组映射到编号后的 SRT cue,并派生无点击的 `narration_animations.json`;没有动画 sidecar 时则跳过派生,保留 `fade` / 无逐元素动画。随后再导出带音频的 PPTX;存在逐页 SRT 时,才从该 PPTX 读回实际计时并合并。若用户选择自动视频导出且本机 Windows PowerPoint 兼容,则继续调用 PowerPoint 原生编码器,等 MP4 完成后再校准可用的交付字幕。不支持长音频导入或自动拆分。+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 原生编码器,等 MP4 完成后再校准可用的交付字幕。不支持长音频导入或自动拆分。字幕保持为外部 SRT 文件:PPT Master 不把字幕嵌入 PPTX,也不烧录进 MP4。自动视频导出委托给本机 Windows PowerPoint,并不是另一套渲染器。@@ -101,20 +101,38 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \--voice-id <cosyvoice-voice> \--cosyvoice-model cosyvoice-v3-flash-# 3-4. 仅当逐页 SRT 与规范 animations.json 都存在时,输出整套 SRT 的指纹,+# 3-4. 仅当选择旁白 cue 同步,且逐页 SRT 与规范 animations.json 都存在时,+# 输出整套 SRT 的指纹,# 再对照每页当前 SVG 内容组与 SRT cue,编写# <project_path>/narration_timing.json;没有对应口播的组不写 cue,-# 后续按正常动画顺序出现。两个动画 sidecar 都不存在时直接跳到第 5 步。+# 后续按正常动画顺序出现。旁白无关的自定义动画或无 sidecar 时直接跳到第 5 步。python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path># 4. 从规范 animations.json 派生无点击的 narration_animations.jsonpython3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \--narration-start-floor 0.8 --narration-padding 0.5 --force-# 5. 重新导出 PPTX 嵌入音频+# 5A. 与旁白 cue 同步的自定义动画:使用派生 sidecarpython3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \-o <final_narrated_pptx> --recorded-narration audio \- --narration-start-floor 0.8 --narration-padding 0.5+ --narration-start-floor 0.8 --narration-padding 0.5 \+ --animation-config narration_animations.json \+ --inherit-motion-from "<base_postflight_report>"++# 5B. 与旁白无关的自定义动画:使用规范计时+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \+ -o <final_narrated_pptx> --recorded-narration audio \+ --narration-start-floor 0.8 --narration-padding 0.5 \+ --animation-config animations.json \+ --inherit-motion-from "<base_postflight_report>"++# 5C. 没有动画 sidecar:继承基础导出的 motion,包括 -a auto+python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \+ -o <final_narrated_pptx> --recorded-narration audio \+ --narration-start-floor 0.8 --narration-padding 0.5 \+ --inherit-motion-from "<base_postflight_report>"++# Quick Generate 在所选命令后追加 --quick-generate --with-notes。# 6. 存在逐页 SRT 时,按最终 PowerPoint 计时合并python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \@@ -125,10 +143,10 @@ python3 skills/ppt-master/scripts/powerpoint_video.py --checkpython3 skills/ppt-master/scripts/powerpoint_video.py \<final_narrated_pptx> -o exports/<final_video>.mp4-# 8. 存在逐页 SRT 时,根据导出音轨校准每页起点,生成与视频同名的外挂 SRT-python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \- --pptx <final_narrated_pptx> --video <powerpoint_exported_video> \- -o exports/<powerpoint_exported_video_stem>.srt --force+# 8. 存在逐页 SRT 时,把冻结的旁白文本与导出视频音轨对齐,+# 生成与视频同名的交付 SRT+python3 skills/ppt-master/scripts/video_subtitles.py <project_path> \+ --video "<powerpoint_exported_video>" --language <language> --force```发送任何 TTS 请求前,`notes_to_audio.py` 会确认每个 Generate SVG 页面或@@ -165,9 +183,9 @@ CLI 会在发送请求前拒绝超出范围的 ElevenLabs stability/similarity/s`audio/` 是唯一的当前旁白集,来源由 manifest 记录,因此默认不创建 provider 子目录。重新生成前,脚本会移除过期的 `manifest.json` 与 `total.srt`;仅生成音频的 provider 还会移除同名旧逐页 SRT。只有明确需要保留另一套 provider 结果时,才使用单独的显式输出目录。-存在规范自定义动画时,`narration_timing.json` 与只读的 `animations.json` 刻意分离:前者记录整套有序 SRT 的 SHA-256、可选的旁白起始下限、页尾 padding、有序 SVG 组 ID 和可选的 1-based cue 编号。`narration_sync.py animations` 会拒绝过期的 SRT 指纹,用当前 SVG 校验组 ID,并把 PowerPoint 支持的字段写入派生的 `narration_animations.json`。与 cue 绑定的动画使用和嵌入音频相同的页前起始下限;未绑定 cue 的标题或装饰动画保留规范相对时间。包含 `effects[]` 的分组仍只映射一条 cue:第一条有效动画行锚定该 cue,后续动画行保留相对延迟。没有动画 sidecar 时跳过该派生步骤。`narration_sync.py subtitles` 从最终 PPTX 读取真实页面关系顺序、毫秒级转场、旁白延迟与页面推进时间,因此 `total.srt` 使用原生 PPTX 时间轴。相对 `--pptx` 路径按 `<project_path>` 解析。+选择旁白 cue 同步且存在规范自定义动画时,`narration_timing.json` 与只读的 `animations.json` 刻意分离:前者记录整套有序 SRT 的 SHA-256、可选的旁白起始下限、页尾 padding、有序 SVG 组 ID 和可选的 1-based cue 编号。`narration_sync.py animations` 会拒绝过期的 SRT 指纹,用当前 SVG 校验组 ID,并把 PowerPoint 支持的字段写入派生的 `narration_animations.json`。与 cue 绑定的动画使用和嵌入音频相同的页前起始下限;未绑定 cue 的标题或装饰动画保留规范相对时间。包含 `effects[]` 的分组仍只映射一条 cue:第一条有效动画行锚定该 cue,后续动画行保留相对延迟。与旁白无关的自定义动画直接使用规范 `animations.json`;没有 sidecar 时继承基础报告的已解析 motion。`narration_sync.py subtitles` 从最终 PPTX 读取真实页面关系顺序、毫秒级转场、旁白延迟与页面推进时间,因此 `total.srt` 使用原生 PPTX 时间轴。相对 `--pptx` 路径按 `<project_path>` 解析。-PowerPoint 的视频编码器可能把每个页面 / 媒体段落量化到输出帧时钟;即使 PPTX 计时值正确,这些很小的分页误差仍可能逐页累积。把最终 `.mp4` / `.wmv` / `.mov` 通过 `--video` 传入后,脚本会用归一化音频相关性在视频音轨中定位每页原始旁白。它只改页级偏移,provider 返回的字幕文本和页内时间保持不变;这是视频导出后的字幕校准步骤,不会改写视频。+PowerPoint 的视频编码器可能把每个页面 / 媒体段落量化到输出帧时钟;即使 PPTX 计时值正确,这些很小的分页误差仍可能逐页累积。`video_subtitles.py` 使用 `stable-ts`,把冻结的旁白原文与最终 `.mp4` / `.wmv` / `.mov` 音轨强制对齐;交付时可为显示效果拆分过长 cue,并生成与视频同名的 SRT,不会改写视频、备注或逐页字幕。最终带旁白的 SVG 导出使用默认文本流模式即可:在一个禁用自动换行的可编辑文本框中保留作者断行;旁白不要求每一行拆成独立文本框。@@ -246,6 +264,12 @@ python3 -m pip install edge-tts自动 MP4 导出不增加 Python 依赖,但要求 Windows PowerPoint 2016+ 与 Windows PowerShell;macOS 或没有兼容 PowerPoint 的机器保留带旁白 PPTX,改用手动导出。+最终视频字幕对齐还需要系统 `PATH` 中可用的 `ffmpeg`,以及 `stable-ts`:++```bash+python3 -m pip install stable-ts+```+## 经验值- **语速**:在 Generate PPTX 路线上,PPT Master 会根据最终 SVG 中的独立信息组调整讲稿长度;每页 2–5 句只是常见节奏,并非上限。可先使用 `+0%`,较密且刻意保留细节的讲稿可尝试 `-5%`。@@ -271,7 +295,7 @@ python3 skills/ppt-master/scripts/powerpoint_video.py \2. **文件 → 导出 → 创建视频**。3. 选清晰度以及"使用录制的计时和旁白"。4. **创建视频** → 保存为 `.mp4`(Windows 也支持 `.wmv`)。-5. 若要让外挂字幕最贴合最终视频,再执行上面的 `narration_sync.py subtitles --video ...`,把生成的同名 SRT 与视频放在一起。+5. 若要让外挂字幕最贴合最终视频,再执行上面的 `video_subtitles.py` 对齐命令;它会把同名 SRT 写在视频旁边。PowerPoint for Mac 可以手动导出 MP4/MOV,但微软明确说明其影片导出不会播放动画效果。需要动画保真时,应使用 Windows 自动导出路径。diff --git a/skills/ppt-master/references/video-design.md b/skills/ppt-master/references/video-design.mdindex 57a58af7..33b8a144 100644--- a/skills/ppt-master/references/video-design.md+++ b/skills/ppt-master/references/video-design.md@@ -120,13 +120,14 @@ A pre-SVG `notes/total.md` is an enabled production artifact, not a forbiddenplanning checkpoint; Quick still creates no root Design Spec, lock,confirmation payload, or storyboard.-**Hard rule — Quick direct video input**: when Quick must deliver a narrated+**Mandatory — Quick direct video input**: when Quick must deliver a narratedvideo or MP4 rather than only a deck for later recording, enable Speaker Notes,-Custom Animations, Narration Audio, and video export. Before P01, write the-complete per-scene narration to `notes/total.md` even when the agent authored-it. Treat it as page-design input; validate/finalize agent-authored wording after-the SVG roster and before audio. A supplied final/literal script remains-verbatim and requires visual repair instead.+Narration Audio, and video export; write the complete per-scene narration to+`notes/total.md` before P01 and use it as page-design input. After the SVG+roster, only agent-authored wording may be finalized; final/literal input remains+verbatim. Before audio, choose static/page-transition-only,+narration-independent deck-wide exporter motion, or page/object-specific Custom+Animations; for the last, decide whether narration governs any group timing.**Production outcomes**:@@ -135,12 +136,13 @@ verbatim and requires visual repair instead.| Spoken delivery or a supplied final script | Enable Speaker Notes || User asks the workflow to synthesize narration | Enable Narration Audio; Speaker Notes is its dependency || Progressive reveal, continuing geometry, or timed emphasis materially aids explanation | Enable/load the appropriate animation capability |-| Quick directly delivers a narrated video or MP4 | Enable Speaker Notes, Custom Animations, Narration Audio, and video export; require timestamped page-local SRT |+| Quick directly delivers a narrated video or MP4 | Enable Speaker Notes, Narration Audio, and video export; resolve motion before audio, requiring timestamped page-local SRT only for narration-cue sync or subtitle delivery || Video is manually narrated or static playback is sufficient | Keep Narration Audio and/or object animation off as applicable |**Capability boundary**: a deck intended for later video use does not forceobject animation or generated audio. Direct Quick narrated-video delivery uses-the mandatory row above. Explicit user instructions remain authoritative.+the mandatory row above but may intentionally remain static or+page-transition-only. Explicit user instructions remain authoritative.---@@ -170,14 +172,15 @@ named communication job. There is no motion-coverage quota, and `effect: none`remains valid. Auto-running narration uses `after-previous` / `with-previous`,never `on-click`.-**Hard rule — Quick direct video synchronization**: load `animations.md` before-SVG authoring and create/validate canonical `animations.json` from real semantic-groups. After notes validation, export the base PPTX/report, use a-timestamp-capable provider to generate page audio/SRT, map each timed group in-`narration_timing.json`, derive `narration_animations.json`, re-export the-narrated PPTX, then export MP4. Author object identity, effect, and order before-audio; only narration-derived triggers/delays wait for SRT timing. An audio-only-provider cannot satisfy this branch.+**Mandatory when narration governs object motion**: before SVG authoring, load+`animations.md` and preserve real semantic groups; before audio, create and+validate canonical `animations.json`. After the base PPTX/report and timestamped+page audio/SRT, map timed groups in `narration_timing.json`, derive+`narration_animations.json`, and export the narrated PPTX/MP4. Only derived+triggers/delays wait for SRT; object identity, effect, and order do not. `-a+auto` or inherited fixed stagger is not semantic synchronization. For+static/page-transition-only or narration-independent deck-wide motion, omit+these sidecars and the object-sync claim.**Sound effects**: add them only on explicit request and only from prepared,project-local assets. Do not introduce sound search, trimming, or normalization@@ -185,9 +188,12 @@ as an implicit video step.**Production sequence**: after the final SVG check, validate any pre-SVGnarration against the visible pages; ordinary draft-source runs instead use the-final-SVG-grounded notes generation. Split notes, run triggered custom animation,-and export the canonical editable PPTX. Direct Quick video continues through-timestamped audio/SRT, narration synchronization, narrated PPTX, and MP4.+final-SVG-grounded notes generation. Split notes, execute the resolved motion+path, and export the editable PPTX. Direct Quick video continues+through audio and, when required, timestamped SRT. Custom Animations use the+narrated-sidecar flow when narration governs group timing;+narration-independent custom motion exports its canonical timing without an+object-sync claim before the narrated PPTX and MP4.---diff --git a/skills/ppt-master/workflows/profiles/quick-generate.md b/skills/ppt-master/workflows/profiles/quick-generate.mdindex 6b60b628..160268cb 100644--- a/skills/ppt-master/workflows/profiles/quick-generate.md+++ b/skills/ppt-master/workflows/profiles/quick-generate.md@@ -69,6 +69,14 @@ defaults when no row supplies a concrete communication job. When severalsignals apply, perform every required action and use the earliest required loadpoint; a before-authoring signal always overrides a before-export-only timing.+**Direct-video application**: when [`video-design.md`](../../references/video-design.md)+is active for Quick direct delivery, use this gate as the required pre-audio+motion choice, not an animation quota. The page/object-specific row activates+Custom Animations; when narration should govern those semantic reveals, it also+activates narration-cue synchronization. The deck-wide row remains independent+of narration and must not be reported as synchronized; static or+page-transition-only motion remains valid.+---## 2. Source and Resource Preparation@@ -247,7 +255,7 @@ checkpoint, or persist a page/resource plan.Before writing P01, resolve in active context:- the exact slide roster and one compact core message for every page, used to choose its composition and hierarchy;-- the effective Speaker Notes, Custom Animations, and Narration Audio outcomes; generated narration requires notes, while video purpose alone forces neither audio nor object animation;+- the effective Speaker Notes, Custom Animations, and Narration Audio outcomes; generated narration requires notes. A deck intended only for later recording forces neither audio nor object animation. Quick direct video follows [`video-design.md`](../../references/video-design.md): enable notes/narration/video delivery, decide motion before audio, and enable Custom Animations only for narration-cued or other page/object-specific motion;- the canvas, visual direction, wording, intended viewing distance, and effective reading mode: choose `presentation` for distance-first projected or recorded viewing, `balanced` for mixed viewing, or `text` for close content-heavy reading. Take the initial body anchor and sanity band from [`canvas-formats.md`](../../references/canvas-formats.md) § "Typography Scale Start" for the resolved canvas—PPT remains reading-mode-driven, while registered/custom non-PPT canvases use their canvas-derived start—then resolve one concrete typography plan using installed font families, with stable size anchors for title, body, annotation, and every other recurring role the roster uses. When content does not fit, preserve its core message and apply only fitting actions the source/profile invariants permit—restructure, shorten, or split; if none is permitted, surface the unresolved fit instead of shrinking a recurring role. Explicit user, template, fidelity-profile, or resolved-style requirements may call for a deliberate exception;- the semantic color roles actually needed by the roster, each with a concrete active-context color anchor, including background/surface, primary/secondary text, dominant/accent, and status roles as applicable. Honor explicit user, installed template/brand, fidelity-profile source-identity, and resolved-style color semantics before deriving only the missing roles that the active profile permits; decide which roles dominate, support, or remain rare, and preserve sufficient contrast for meaning-bearing text. Pair newly authored color-coded states, categories, or relationships with a label, symbol, line, or geometry cue; when fidelity forbids adding one, preserve the source encoding;- an ordinary body-content frame and a density judgment for every page, adapted to the canvas and any user / template / style geometry; use `anchor`, `dense`, `breathing`, or an equivalent active-context distinction instead of one uniform fill level;@@ -531,8 +539,9 @@ Fix every blocking error and rerun the same command. Then export:When Speaker Notes is enabled, load[`executor-notes.md`](../../references/executor-notes.md) after the passing final-check. Validate an already frozen final script without rewriting it; otherwise-generate `notes/total.md` from the final SVG roster. Then run:+check. Validate an already frozen final script or direct-video pre-SVG narration+without regenerating it; otherwise generate `notes/total.md` from the final SVG+roster. Then run:```bashpython3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>@@ -542,11 +551,20 @@ Run [`customize-animations`](../stages/customize-animations.md) after that notespass when the active-context outcome or an existing sidecar triggers it. Resolvedeck-wide-only motion through the selected exporter flags instead.+For Quick direct video, preserve the motion choice made under+[`video-design.md`](../../references/video-design.md). A static,+page-transition-only, or narration-independent deck-wide choice may export+without `animations.json` and does not claim object-level audio sync. Any+page/object-specific choice completes the custom stage before base export;+`generate-audio` derives cue timing only for narration-governed groups and+otherwise exports canonical timing without an object-sync claim.+Choose exactly one notes mode for the base export:```bash# Speaker Notes enabled-python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> --quick-generate+python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> \+ --quick-generate --with-notes# Speaker Notes disabledpython3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> \diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.mdindex c82a2b49..11e8d043 100644--- a/skills/ppt-master/workflows/stages/generate-audio.md+++ b/skills/ppt-master/workflows/stages/generate-audio.md@@ -107,11 +107,20 @@ For each candidate, write a **one-line Chinese description** covering: 性别 ·----## Step 3: One-shot user interaction (mandatory)+## Step 3: Resolve generation settings-Send a single message to the user that resolves all five configuration decisions at once and provides a recommended value for each. 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.+**Quick exception**: do not pause. Apply explicit user values, then resolve+unspecified provider, voice, rate, and embed choices from the recommended-value+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. Require a timestamp-capable provider+only when narration-cue sync or subtitle delivery needs page-local SRT.-**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 provider to whichever the user named (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`), pin the `voice_id` they gave you, and only confirm rate + embed + video.+**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.++**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.**Message template** (Chinese; translate to user's chat language if different). “Embed” means caller-specific integration: SVG re-export for Generate PPTX, or native OOXML application for Enhance Native PPTX.@@ -181,8 +190,8 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \--provider cosyvoice --voice-id <chosen-voice> \--cosyvoice-model cosyvoice-v3-flash-# 2A. Only when page-local SRT exists and animations.json is active, author or-# refresh narration_timing.json+# 2A. Only when narration-cue sync is selected and page SRT + animations.json+# exist, author or refresh narration_timing.json# by matching SVG group semantics to SRT topics, then derive the narrated# sidecar. Reuse current SVG semantics when complete; otherwise read only# the missing or stale svg_output pages.@@ -191,6 +200,7 @@ 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.python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \--recorded-narration audio \--narration-start-floor 0.8 --narration-padding 0.5 \@@ -239,11 +249,17 @@ Provider-timed paths share punctuation-first, `--subtitle-max-chars`-bounded regBefore generation starts, `notes_to_audio.py` removes stale `audio/manifest.json` and `audio/total.srt`; an incomplete run therefore cannot claim the previous set's provenance or merged timeline. A successful audio-only provider run also removes same-stem stale SRT files. The new manifest is published atomically only after the complete page roster succeeds.-**Mandatory when `animations.json` is consumed — semantic animation context**: Before writing or refreshing `<project_path>/narration_timing.json`, determine whether the active context already contains the current top-level SVG group IDs and visible group-content semantics for every affected page. Reuse that context without rereading SVG when it is complete and still matches the current `svg_output/`. If any page is missing, stale, or represented only by group IDs/order without content meaning, read only that page's SVG as a read-only source and extract the missing group semantics. Always combine those semantics with the page SRT topics/timestamps and `animations.json`; group order alone is not a semantic narration mapping.+**Mandatory when narration-cue sync is selected — semantic animation context**: Before writing or refreshing `<project_path>/narration_timing.json`, determine whether the active context already contains the current top-level SVG group IDs and visible group-content semantics for every affected page. Reuse that context without rereading SVG when it is complete and still matches the current `svg_output/`. If any page is missing, stale, or represented only by group IDs/order without content meaning, read only that page's SVG as a read-only source and extract the missing group semantics. Always combine those semantics with the page SRT topics/timestamps and `animations.json`; group order alone is not a semantic narration mapping.-> Active `animations.json` requires `narration_timing.json`; explicit `--no-animations` bypasses both. Without a sidecar, `narration_sync.py animations` maps groups **positionally** (group N → cue N) and warns when later objects may reveal during an earlier topic. Treat that warning as required repair: author the semantic plan and re-derive.+> Narration-cue sync with `animations.json` requires `narration_timing.json`.+> Narration-independent custom motion instead passes `--animation-config animations.json`+> and makes no object-sync claim. Explicit `--no-animations`+> bypasses both. Without a timing sidecar, `narration_sync.py animations` maps+> groups **positionally** (group N → cue N) and warns when later objects may+> reveal during an earlier topic. Treat that warning as required repair: author+> the semantic plan and re-derive.-**Narration animation ownership**: When `animations.json` is consumed, it remains read-only. The audio stage deep-copies it to `narration_animations.json`, preserves transitions, effects, durations, order, and explicit `effect: none`, then changes only the derived trigger/delay values needed for click-free narration playback. The authored `narration_timing.json` maps each animated content group—not each effect row—to the SRT cue that speaks about that content. For `effects[]`, the cue anchors the group's first active row; later rows keep global order and their relative delay. The command may still read an affected SVG page to resolve structural group order when a sparse sidecar cannot identify every effective group; this structural fallback does not replace the semantic-context step and never edits SVG, notes, or `animations.json`. Unmatched groups keep their canonical relative delay.+**Narration animation ownership**: When narration-cue sync is selected, `animations.json` remains read-only. The audio stage deep-copies it to `narration_animations.json`, preserves transitions, effects, durations, order, and explicit `effect: none`, then changes only the derived trigger/delay values needed for click-free narration playback. The authored `narration_timing.json` maps each animated content group—not each effect row—to the SRT cue that speaks about that content. For `effects[]`, the cue anchors the group's first active row; later rows keep global order and their relative delay. The command may still read an affected SVG page to resolve structural group order when a sparse sidecar cannot identify every effective group; this structural fallback does not replace the semantic-context step and never edits SVG, notes, or `animations.json`. Unmatched groups keep their canonical relative delay.**Title timing handoff when canonical animation exists**: preserve the title reveal decision already made by the custom-animation pass. Assign a title group to an SRT cue only when the user's request or the active motion plan explicitly chose `narration-cued`; otherwise leave its `cue` omitted in `narration_timing.json` so it keeps the canonical relative delay from `animations.json`. Do not infer `narration-cued` merely because speaker notes mention the title.@@ -251,8 +267,9 @@ Before generation starts, `notes_to_audio.py` removes stale `audio/manifest.json| Sidecar state | Behavior ||---|---|-| `narration_animations.json` exists | Use it by default |-| Only canonical `animations.json` exists | Block until narration synchronization creates the derived sidecar |+| `narration_animations.json` exists and narration-cue sync is selected | Use it |+| Only canonical `animations.json` exists and narration-cue sync is selected | Block until narration synchronization creates the derived sidecar |+| Canonical `animations.json` exists and motion is narration-independent, whether or not a derived sidecar also exists | Pass `--animation-config animations.json`; do not claim object sync || Both are absent | Create no sidecar; inherit the base report's deck motion |Generate passes the base report through `--inherit-motion-from`: inherited@@ -319,10 +336,10 @@ This stage keeps subtitles as external SRT files. It does not burn subtitles int| Caller | After audio generation ||---|---|-| Generate PPTX | With page-local SRT from Edge, ElevenLabs, MiniMax, or timestamp-capable CosyVoice and an existing `animations.json`, derive `narration_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`, optionally continue through `powerpoint_video.py`, then generate the delivery SRT from the finished video. |+| 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`. Optionally continue through `powerpoint_video.py`, then generate the delivery SRT from the finished video. || 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`. |-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. Never present those missing subtitle artifacts as generated.+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. Never present those 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.@@ -338,9 +355,11 @@ Output one summary block listing:- For provider-timed subtitles, number of matching page-local SRT files and their location (`<project_path>/audio/*`); for Qwen or explicit CosyVoice audio-only mode, report that no page-local SRT was generated.- 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 with page-local SRT and canonical custom animation, derived narration animation group count and `narration_animations.json` path; otherwise report inherited base motion or explicit all-motion-off.+- 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 final MP4 path and native PowerPoint export status.-- When a finished video exists, the final aligned sidecar SRT path.+- When page-local SRT was merged, the PPTX-timeline `audio/total.srt` path.+- When final-video subtitle alignment ran, the aligned delivery SRT path;+ 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”.- For Generate PPTX when embedding was skipped, one-line hint: `python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --recorded-narration audio`.