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(audio): colocate narration subtitles and track source
hugohe31a6d4f8c8c32
diff --git a/docs/audio-narration.md b/docs/audio-narration.mdindex 9920f1b2..25fc26f5 100644--- a/docs/audio-narration.md+++ b/docs/audio-narration.md@@ -9,8 +9,9 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](## What you get- One audio file per slide under `<project_path>/audio/`, named to match the SVG (`01_cover.mp3`, `02_market_landscape.mp3`, …).-- With edge or MiniMax subtitles, one matching subtitle file per slide under `<project_path>/notes/subtitles/` (`01_cover.srt`, `02_market_landscape.srt`, …). Each file uses a page-local timeline with a `00:00:00,000` origin. Both providers' word timings are regrouped into the same compact cue format.-- When canonical `animations.json` exists, 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. Both paths can produce a deck-wide `<project_path>/notes/subtitles/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.+- With edge or MiniMax 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. Both providers' word 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, 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. 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.- Optional re-export: a new PPTX in `exports/` with each `m4a` / `mp3` / `wav` file embedded into the matching slide and slide auto-advance timings set to the audio length, so kiosk/auto-play and video export work without manual timing.- 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,7 +21,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. **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.** With edge, the script writes each page's MP3 and SRT from the same stream to `audio/` and `notes/subtitles/`. MiniMax requests service timestamps together with the MP3 and converts the returned JSON to the same page-local SRT format; ElevenLabs, Qwen, and CosyVoice write audio only. For Generate PPTX with 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 merges the local SRT files 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. Long-audio import and automatic long-audio splitting are not supported.+4. **Generation runs.** With edge, the script writes each page's MP3 and SRT from the same stream into `audio/`. MiniMax requests service timestamps together with the MP3 and converts the returned JSON to the same page-local SRT format; ElevenLabs, Qwen, and CosyVoice write audio only. A complete run atomically writes `audio/manifest.json` for provenance. For Generate PPTX with 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 merges the local SRT files 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. 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.@@ -140,10 +141,12 @@ Edge generates up to three slide-level audio/SRT pairs concurrently by default.Use `--concurrency <N>` to tune it or `--concurrency 1` for serialtroubleshooting. Cloud providers remain serial.-The edge command creates `audio/<stem>.mp3` and `notes/subtitles/<stem>.srt` from the same streaming request. Sentence-ending punctuation closes a cue. A cue over 20 visible characters first splits at commas, semicolons, or colons, then at the nearest word boundary only if it is still too long. Use `--subtitle-max-chars` to change the limit. Adjacent timing overlap up to 100 ms is tolerated by moving the later cue start to the previous cue end; larger overlap fails. Each SRT uses a page-local timebase with a zero origin and preserves edge's `WordBoundary` timing, including any leading silence before the first cue.+The edge command creates `audio/<stem>.mp3` and `audio/<stem>.srt` from the same streaming request. Sentence-ending punctuation closes a cue. A cue over 20 visible characters first splits at commas, semicolons, or colons, then at the nearest word boundary only if it is still too long. Use `--subtitle-max-chars` to change the limit. Adjacent timing overlap up to 100 ms is tolerated by moving the later cue start to the previous cue end; larger overlap fails. Each SRT uses a page-local timebase with a zero origin and preserves edge's `WordBoundary` timing, including any leading silence before the first cue.MiniMax requests word-level subtitles on the same non-streaming T2A request, downloads the returned JSON timing file, and applies the same punctuation-first, length-bounded regrouping as Edge. The validated MP3/SRT pair is then published together. Use `--subtitle-max-chars` to tune both providers; their compact cues are the semantic animation-mapping units. ElevenLabs, Qwen, and CosyVoice create audio only.+`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, 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. 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 slide-advance and transition 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.diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex 8b960328..6252860f 100644--- a/docs/zh/audio-narration.md+++ b/docs/zh/audio-narration.md@@ -9,8 +9,9 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg## 你会得到什么- 每页一个音频文件,存放于 `<project_path>/audio/`,文件名与 SVG 对齐(`01_cover.mp3`、`02_market_landscape.mp3` …)。-- 使用 Edge 或 MiniMax 字幕时,每页还有一个同名字幕文件,存放于 `<project_path>/notes/subtitles/`(`01_cover.srt`、`02_market_landscape.srt` …)。每个文件使用以 `00:00:00,000` 为原点的页内时间轴;两个 provider 的词级时间戳都会重组为同一套紧凑 cue。-- 存在规范的 `animations.json` 时,SVG 到 SRT 的计时计划会派生 `narration_animations.json`,让无点击对象动画等待相关字幕 cue。两个动画 sidecar 都不存在时,旁白导出不会创建 sidecar,而是保留默认 `fade` 页间切换和无逐元素动画。两条路径都可以生成与最终 PPTX 时间轴一致的 `<project_path>/notes/subtitles/total.srt`;PowerPoint 导出视频后,还可用同一命令根据视频音轨校准每页起点,得到帧级对齐的外挂字幕。+- 使用 Edge 或 MiniMax 字幕时,每页还有一个同名字幕文件,与音频一起存放于 `<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` 时,SVG 到 SRT 的计时计划会派生 `narration_animations.json`,让无点击对象动画等待相关字幕 cue。两个动画 sidecar 都不存在时,旁白导出不会创建 sidecar,而是保留默认 `fade` 页间切换和无逐元素动画。两条路径都可以生成与最终 PPTX 时间轴一致的 `<project_path>/audio/total.srt`;PowerPoint 导出视频后,还可用同一命令根据视频音轨校准每页起点,得到帧级对齐的外挂字幕。- 可选重新导出:在 `exports/` 生成新版 PPTX,每页对应的 `m4a` / `mp3` / `wav` 音频已嵌入到该页,且页面切换时间按音频长度自动设置——无人值守自动播放和视频导出都不用再手动调时间。- Windows 下可选原生视频导出:`powerpoint_video.py` 把最终带旁白 PPTX 交给 PowerPoint 2016+,并等待其原生 MP4 编码成功或失败。- 演讲者备注原样保留。@@ -20,7 +21,7 @@ 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 时,脚本从同一次流中把每页 MP3 和 SRT 分别写到 `audio/` 与 `notes/subtitles/`。MiniMax 会在生成 MP3 的同一请求中获取服务端时间戳,并把返回的 JSON 转成相同的逐页 SRT;ElevenLabs、Qwen 与 CosyVoice 仍只写音频。对于存在规范自定义动画的 Generate PPTX,AI 将当前 SVG 内容组映射到编号后的 SRT cue,并派生无点击的 `narration_animations.json`;没有动画 sidecar 时则跳过派生,保留 `fade` / 无逐元素动画。随后再导出带音频的 PPTX,并从该 PPTX 读回实际计时、合并逐页 SRT。若用户选择自动视频导出且本机 Windows PowerPoint 兼容,则继续调用 PowerPoint 原生编码器,等 MP4 完成后再校准交付字幕。不支持长音频导入或自动拆分。+4. **执行**。使用 Edge 时,脚本从同一次流中把每页 MP3 和 SRT 一起写入 `audio/`。MiniMax 会在生成 MP3 的同一请求中获取服务端时间戳,并把返回的 JSON 转成相同的逐页 SRT;ElevenLabs、Qwen 与 CosyVoice 仍只写音频。完整生成成功后会原子写入 `audio/manifest.json` 记录来源。对于存在规范自定义动画的 Generate PPTX,AI 将当前 SVG 内容组映射到编号后的 SRT cue,并派生无点击的 `narration_animations.json`;没有动画 sidecar 时则跳过派生,保留 `fade` / 无逐元素动画。随后再导出带音频的 PPTX,并从该 PPTX 读回实际计时、合并逐页 SRT。若用户选择自动视频导出且本机 Windows PowerPoint 兼容,则继续调用 PowerPoint 原生编码器,等 MP4 完成后再校准交付字幕。不支持长音频导入或自动拆分。字幕保持为外部 SRT 文件:PPT Master 不把字幕嵌入 PPTX,也不烧录进 MP4。自动视频导出委托给本机 Windows PowerPoint,并不是另一套渲染器。@@ -134,10 +135,12 @@ edge 模式下 `--voice` 是必填项,可用 `--list-voices --locale <locale>`Edge 默认同时生成最多 3 页音频/SRT。可用 `--concurrency <N>` 调整;排查连接问题时可设为 `--concurrency 1`。云端 provider 仍保持串行。-Edge 命令会从同一次流式请求中生成 `audio/<stem>.mp3` 与 `notes/subtitles/<stem>.srt`。句末标点必定结束一条字幕;单条超过默认 20 个可见字符时,优先在逗号、分号或冒号处拆分,仍然过长才在最近的词边界拆分。可用 `--subtitle-max-chars` 调整上限。相邻字幕最多允许 100 毫秒的计时重叠:后一句起点会移到前一句终点;超过该范围则报错。每页 SRT 使用从零计时的页内时间基准,并保留 Edge `WordBoundary` 的实际时间(包括首条字幕前的静音)。+Edge 命令会从同一次流式请求中生成 `audio/<stem>.mp3` 与 `audio/<stem>.srt`。句末标点必定结束一条字幕;单条超过默认 20 个可见字符时,优先在逗号、分号或冒号处拆分,仍然过长才在最近的词边界拆分。可用 `--subtitle-max-chars` 调整上限。相邻字幕最多允许 100 毫秒的计时重叠:后一句起点会移到前一句终点;超过该范围则报错。每页 SRT 使用从零计时的页内时间基准,并保留 Edge `WordBoundary` 的实际时间(包括首条字幕前的静音)。MiniMax 会在同一次非流式 T2A 请求中获取词级字幕,下载返回的 JSON 时间戳,再复用 Edge 的标点优先、长度受控重组逻辑。校验通过后成对发布 MP3 与 SRT;`--subtitle-max-chars` 同时控制两个 provider,整理后的紧凑 cue 用于语义动画映射。ElevenLabs、Qwen 与 CosyVoice 仍只生成音频。+`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`。包含 `effects[]` 的分组仍只映射一条 cue:第一条有效动画行锚定该 cue,后续动画行保留相对延迟。没有动画 sidecar 时跳过该派生步骤。`narration_sync.py subtitles` 从最终 PPTX 读取真实页面关系顺序、毫秒级页面推进与转场时间,因此 `total.srt` 使用原生 PPTX 时间轴。相对 `--pptx` 路径按 `<project_path>` 解析。PowerPoint 的视频编码器可能把每个页面 / 媒体段落量化到输出帧时钟;即使 PPTX 计时值正确,这些很小的分页误差仍可能逐页累积。把最终 `.mp4` / `.wmv` / `.mov` 通过 `--video` 传入后,脚本会用归一化音频相关性在视频音轨中定位每页原始旁白。它只改页级偏移,provider 返回的字幕文本和页内时间保持不变;这是视频导出后的字幕校准步骤,不会改写视频。diff --git a/skills/ppt-master/scripts/narration_sync.py b/skills/ppt-master/scripts/narration_sync.pyindex 9313b556..a5c53fbd 100644--- a/skills/ppt-master/scripts/narration_sync.py+++ b/skills/ppt-master/scripts/narration_sync.py@@ -1714,7 +1714,7 @@ def build_parser() -> argparse.ArgumentParser:fingerprint.add_argument("--subtitle-dir",default=None,- help="Page-local SRT directory; default: <project>/notes/subtitles",+ help="Page-local SRT directory; default: <project>/audio",)animations = subparsers.add_parser(@@ -1735,7 +1735,7 @@ def build_parser() -> argparse.ArgumentParser:animations.add_argument("--subtitle-dir",default=None,- help="Page-local SRT directory; default: <project>/notes/subtitles",+ help="Page-local SRT directory; default: <project>/audio",)animations.add_argument("--audio-dir",@@ -1779,7 +1779,7 @@ def build_parser() -> argparse.ArgumentParser:subtitles.add_argument("--subtitle-dir",default=None,- help="Page-local SRT directory; default: <project>/notes/subtitles",+ help="Page-local SRT directory; default: <project>/audio",)subtitles.add_argument("--video",@@ -1801,7 +1801,7 @@ def build_parser() -> argparse.ArgumentParser:"-o","--output",default=None,- help="Merged SRT output; default: <project>/notes/subtitles/total.srt",+ help="Merged SRT output; default: <project>/audio/total.srt",)subtitles.add_argument("--force",@@ -1823,7 +1823,7 @@ def main(argv: list[str] | None = None) -> int:subtitle_dir = _project_path(project_path,args.subtitle_dir,- Path("notes/subtitles"),+ Path("audio"),)slide_names = _page_subtitle_names(subtitle_dir)for slide_name in slide_names:@@ -1845,7 +1845,7 @@ def main(argv: list[str] | None = None) -> int:subtitle_dir = _project_path(project_path,args.subtitle_dir,- Path("notes/subtitles"),+ Path("audio"),)audio_dir = _project_path(project_path,@@ -1881,7 +1881,7 @@ def main(argv: list[str] | None = None) -> int:subtitle_dir = _project_path(project_path,args.subtitle_dir,- Path("notes/subtitles"),+ Path("audio"),)audio_dir = _project_path(project_path,@@ -1896,7 +1896,7 @@ def main(argv: list[str] | None = None) -> int:output_path = _project_path(project_path,args.output,- Path("notes/subtitles/total.srt"),+ Path("audio/total.srt"),)result = _merge_subtitles_result(project_path,diff --git a/skills/ppt-master/scripts/notes_to_audio.py b/skills/ppt-master/scripts/notes_to_audio.pyindex de769881..3d730b66 100644--- a/skills/ppt-master/scripts/notes_to_audio.py+++ b/skills/ppt-master/scripts/notes_to_audio.py@@ -27,11 +27,13 @@ from __future__ import annotationsimport argparseimport asyncio+import hashlibimport jsonimport osimport reimport sysfrom dataclasses import dataclass+from datetime import datetime, timezonefrom pathlib import Pathfrom console_encoding import configure_utf8_stdio@@ -44,6 +46,7 @@ from tts_backends import (backend_minimax,backend_qwen,)+from tts_backends.backend_common import temporary_pathconfigure_utf8_stdio()@@ -221,6 +224,105 @@ def _remove_stale_audio_variants(output_path: Path) -> None:candidate.unlink()+def _sha256_text(value: str) -> str:+ return hashlib.sha256(value.encode("utf-8")).hexdigest()+++def _provider_manifest_details(+ args: argparse.Namespace,+ backend: AudioBackend,+) -> tuple[str, dict[str, object]]:+ if backend.provider == "edge":+ return "edge-tts", {+ "rate": args.rate,+ }+ if backend.provider == "elevenlabs":+ return args.elevenlabs_model, {+ "stability": args.elevenlabs_stability,+ "similarity_boost": args.elevenlabs_similarity_boost,+ "style": args.elevenlabs_style,+ "speaker_boost": args.elevenlabs_speaker_boost,+ }+ if backend.provider == "minimax":+ return args.minimax_model, {+ "speed": args.minimax_speed,+ "volume": args.minimax_volume,+ "pitch": args.minimax_pitch,+ "language_boost": args.minimax_language_boost,+ }+ if backend.provider == "qwen":+ return args.qwen_model, {+ "language_type": args.qwen_language_type,+ "optimize_instructions": args.qwen_optimize_instructions,+ "custom_instructions": True if args.qwen_instructions else None,+ }+ return args.cosyvoice_model, {+ "volume": args.cosyvoice_volume,+ "rate": args.cosyvoice_rate,+ "pitch": args.cosyvoice_pitch,+ "language_hint": args.cosyvoice_language_hint,+ "custom_instruction": True if args.cosyvoice_instruction else None,+ }+++def _narration_manifest(+ args: argparse.Namespace,+ backend: AudioBackend,+ *,+ writes_subtitles: bool,+) -> dict[str, object]:+ model, raw_settings = _provider_manifest_details(args, backend)+ settings = {+ key: value+ for key, value in raw_settings.items()+ if value is not None+ }+ voice_ref = backend.voice_id+ if backend.provider != "edge":+ voice_ref = f"sha256:{_sha256_text(voice_ref)}"++ manifest: dict[str, object] = {+ "schema": "ppt-master.narration.v1",+ "generated_at": datetime.now(timezone.utc).isoformat(+ timespec="seconds"+ ).replace("+00:00", "Z"),+ "provider": backend.provider,+ "model": model,+ "voice_ref": voice_ref,+ "audio_format": backend.extension.lstrip("."),+ }+ if settings:+ manifest["settings"] = settings+ if writes_subtitles:+ manifest["subtitles"] = {+ "format": "srt",+ "timing": "word",+ "max_visible_chars": args.subtitle_max_chars,+ }+ return manifest+++def _publish_manifest(path: Path, manifest: dict[str, object]) -> None:+ descriptor, staged_path = temporary_path(path, ".tmp")+ try:+ with os.fdopen(+ descriptor,+ "w",+ encoding="utf-8",+ newline="\n",+ ) as stream:+ descriptor = -1+ json.dump(manifest, stream, ensure_ascii=False, indent=2)+ stream.write("\n")+ stream.flush()+ os.fsync(stream.fileno())+ os.replace(staged_path, path)+ finally:+ if descriptor >= 0:+ os.close(descriptor)+ staged_path.unlink(missing_ok=True)++async def _generate_edge_jobs(jobs: list[AudioJob],subtitle_dir: Path,@@ -487,7 +589,7 @@ def main() -> int:project = args.project_pathnotes_dir = project / "notes"output_dir = args.output or (project / "audio")- subtitle_dir = notes_dir / "subtitles"+ subtitle_dir = output_dirwrites_subtitles = backend.provider in {"edge", "minimax"}try:@@ -504,8 +606,13 @@ def main() -> int:return 2output_dir.mkdir(parents=True, exist_ok=True)- if writes_subtitles:- subtitle_dir.mkdir(parents=True, exist_ok=True)+ manifest_path = output_dir / "manifest.json"+ try:+ manifest_path.unlink(missing_ok=True)+ (output_dir / "total.srt").unlink(missing_ok=True)+ except OSError as exc:+ print(f"error: failed to clear stale narration metadata: {exc}", file=sys.stderr)+ return 1generated = 0if backend.provider == "edge":@@ -620,6 +727,8 @@ def main() -> int:base_url=args.cosyvoice_base_url,)_remove_stale_audio_variants(output_path)+ if not writes_subtitles:+ output_path.with_suffix(".srt").unlink(missing_ok=True)except Exception as exc:print(f"error: failed to generate {output_path}: {exc}", file=sys.stderr)return 1@@ -628,13 +737,27 @@ def main() -> int:if subtitle_path is not None:print(f" {subtitle_path}")+ try:+ _publish_manifest(+ manifest_path,+ _narration_manifest(+ args,+ backend,+ writes_subtitles=writes_subtitles,+ ),+ )+ except (OSError, RuntimeError) as exc:+ print(f"error: failed to publish narration manifest: {exc}", file=sys.stderr)+ return 1+if writes_subtitles:print(f"[Done] Generated {generated}/{len(note_roster)} audio/SRT pair(s): "- f"{output_dir} + {subtitle_dir}"+ f"{output_dir}")else:print(f"[Done] Generated {generated}/{len(note_roster)} audio file(s): {output_dir}")+ print(f"[REPORT] Narration manifest: {manifest_path}")return 0diff --git a/skills/ppt-master/scripts/video_subtitles.py b/skills/ppt-master/scripts/video_subtitles.pyindex 1335f75d..9fe6f05c 100644--- a/skills/ppt-master/scripts/video_subtitles.py+++ b/skills/ppt-master/scripts/video_subtitles.py@@ -2,7 +2,7 @@"""PPT Master - Final Video Subtitles-Align the exact narration text frozen in page-local Edge SRT files against the+Align the exact narration text frozen in page-local narration SRT files against theaudio track of a finished PowerPoint-exported video. This produces a deliverySRT from the actual video timeline without rewriting speaker notes or relyingon theoretical slide offsets.@@ -189,7 +189,7 @@ def _page_subtitle_paths(subtitle_dir: Path) -> list[Path]:]if not paths:raise FileNotFoundError(- f"No page-local Edge SRT files found under {subtitle_dir}"+ f"No page-local narration SRT files found under {subtitle_dir}")return paths@@ -321,7 +321,7 @@ def build_parser() -> argparse.ArgumentParser:parser.add_argument("--subtitle-dir",default=None,- help="Page-local Edge SRT directory; default: <project>/notes/subtitles",+ help="Page-local narration SRT directory; default: <project>/audio",)parser.add_argument("-o",@@ -367,7 +367,7 @@ def main(argv: list[str] | None = None) -> int:subtitle_dir = (Path(args.subtitle_dir)if args.subtitle_dir- else Path("notes/subtitles")+ else Path("audio"))if not subtitle_dir.is_absolute():subtitle_dir = project_path / subtitle_dirdiff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.mdindex 313ad9bc..61921f18 100644--- a/skills/ppt-master/workflows/stages/generate-audio.md+++ b/skills/ppt-master/workflows/stages/generate-audio.md@@ -26,7 +26,8 @@ this stage.- Per-page narration files exist at `notes/*.md`. In Generate PPTX, split `notes/total.md` during Step 7.1. In Enhance Native PPTX, the notes module writes numeric files such as `001.md`.- Default mode: `edge-tts` is installed (`python3 -m pip install edge-tts`).-- The stage is page-level only: with edge or MiniMax, one notes file becomes `audio/<stem>.mp3` plus `notes/subtitles/<stem>.srt`; with another cloud provider, it becomes one audio file. Do not use a single long audio track or attempt automatic long-audio splitting.+- The stage is page-level only: with edge or MiniMax, one notes file becomes `audio/<stem>.mp3` plus `audio/<stem>.srt`; with another cloud provider, it becomes one audio file. Do not use a single long audio track or attempt automatic long-audio splitting.+- A fully successful run writes a compact `audio/manifest.json` with only provider/model, audio/subtitle format, relevant voice settings, and a SHA-256 fingerprint instead of the raw cloud voice ID. It has no per-slide inventory, artifact hashes, or API keys and is not a normal generation input. The flat `audio/` directory is the single active narration set; do not create provider subdirectories unless the user explicitly asks to preserve multiple variants.- PPT narration assets must be PowerPoint-reliable audio: `m4a` (AAC), `mp3`, or `wav`. The built-in TTS path defaults to `mp3`; provider formats such as `pcm`, `opus`, or `flac` must be transcoded before embedding.- PowerPoint recorded narration export requires `ffprobe` so slide timings can be written from actual audio duration.- Optional automatic video export requires Windows PowerPoint 2016+ and runs@@ -225,6 +226,8 @@ The edge command writes each MP3 and its internal page SRT from the same `edge-tThe MiniMax command requests word-level subtitles on the same non-streaming `/v1/t2a_v2` call, downloads the returned JSON timing file, and applies the same punctuation-first, `--subtitle-max-chars`-bounded regrouping as Edge. It publishes the validated MP3/SRT as a rollback-safe pair; the compact cues are the units used for semantic animation mapping. ElevenLabs, Qwen, and CosyVoice commands write audio only.+Before 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.> 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.@@ -276,7 +279,7 @@ python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path>}```-`narration_sync.py subtitles` may still write `<project_path>/notes/subtitles/total.srt` as a PPTX-timeline diagnostic. It is not the delivery subtitle for a finished video.+`narration_sync.py subtitles` may still write `<project_path>/audio/total.srt` as a PPTX-timeline diagnostic. It is not the delivery subtitle for a finished video.When video export was selected, `powerpoint_video.py` opens the final narrated PPTX through local Windows PowerPoint, requests its native video encoder with recorded timings and narrations enabled, and polls `CreateVideoStatus` until the MP4 succeeds, fails, or times out. The interface is synchronous to its caller even though PowerPoint performs encoding asynchronously. It preserves PowerPoint's own animation and media behavior rather than re-rendering the deck.@@ -306,7 +309,8 @@ For Generate PPTX, `--recorded-narration audio` prepares PowerPoint's recorded tOutput one summary block listing:- Number of audio files generated and their location (`<project_path>/audio/*`).-- For edge or MiniMax subtitles, number of matching page-local SRT files and their location (`<project_path>/notes/subtitles/*`).+- For edge or MiniMax subtitles, number of matching page-local SRT files and their location (`<project_path>/audio/*`).+- 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.- When video export was selected, the final MP4 path and native PowerPoint export status.