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(narration): synchronize subtitles with PowerPoint animations

hugohe3fbb191a4e4ec
diff --git a/docs/audio-narration.md b/docs/audio-narration.md
index 590872e5..3773086a 100644
--- a/docs/audio-narration.md
+++ b/docs/audio-narration.md
@@ -4,11 +4,13 @@
---
-PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](https://github.com/rany2/edge-tts) (Microsoft Edge's online neural voices) by default, or via ElevenLabs, MiniMax, Qwen TTS, and CosyVoice when you need higher-quality cloud narration or a cloned voice. It can then embed the audio back into the PPTX and let PowerPoint export the deck as an MP4 video — with synced narration and slide transitions, no extra tools.
+PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](https://github.com/rany2/edge-tts) (Microsoft Edge's online neural voices) by default, or via ElevenLabs, MiniMax, Qwen TTS, and CosyVoice when you need higher-quality cloud narration or a cloned voice. The edge path also writes a page-local SRT from the same TTS stream. It can then embed the audio back into the PPTX for PowerPoint's native video export.
## 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, 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 and edge's word-boundary timing.
+- With an SVG-to-SRT timing plan, a rebuilt `animations.json` whose click-free entrance animations wait for the relevant subtitle cue, plus a deck-wide `<project_path>/notes/subtitles/total.srt` aligned to the final PowerPoint timeline.
- Optional re-export: a new PPTX in `exports/` with each `m4a` / `mp3` / `wav` file embedded into the matching slide and slide auto-advance timings set to the audio length, so kiosk/auto-play and video export work without manual timing.
- The original speaker notes are preserved.
@@ -17,7 +19,9 @@ 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 — voice, rate, and "embed audio back into PPTX (yes/no)" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.
-4. **Generation runs.** The script writes page-level audio to `audio/`, then (if you kept embedding) re-exports the deck with audio attached. Long-audio import and automatic long-audio splitting are not supported.
+4. **Generation runs.** With edge, the script writes each page's MP3 and SRT from the same stream to `audio/` and `notes/subtitles/`; cloud providers currently write audio only. For Generate PPTX, the AI maps current SVG content groups to numbered SRT cues, rebuilds click-free animations, and re-exports the deck with audio attached. It then merges the local SRT files using timing values read from that final PPTX. 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 export MP4 directly. Use PowerPoint's native video export with the generated `total.srt`.
The shared stage is documented in [`workflows/stages/generate-audio.md`](../skills/ppt-master/workflows/stages/generate-audio.md).
@@ -56,7 +60,7 @@ If you want to skip the AI flow and call the script directly:
# 1. Make sure speaker notes are split (post-processing Step 7.1):
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
-# 2A. Generate MP3s with edge-tts (default, no API key)
+# 2A. Generate MP3/SRT pairs with edge-tts (default, no API key)
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice zh-CN-YunjianNeural --rate +0%
@@ -90,13 +94,50 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice-id <cosyvoice-voice> \
--cosyvoice-model cosyvoice-v3-flash
-# 3. (Optional) Re-export PPTX with audio embedded
+# 3. 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.
+python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path>
+
+# 4. Rebuild click-free object animation timing from the formal SRT
+python3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \
+ --narration-padding 0.5 --force
+
+# 5. Re-export PPTX with audio embedded
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
- --recorded-narration audio
+ -o <final_narrated_pptx> --no-merge --recorded-narration audio \
+ --narration-padding 0.5
+
+# 6. Merge page-local SRT using the final PowerPoint timings
+python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \
+ --pptx <final_narrated_pptx> --force
```
For edge, `--voice` is required. Use `--list-voices --locale <locale>` to see what's available.
+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. 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 cloud-provider commands currently create audio only.
+
+`narration_timing.json` is deliberately separate from `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 replaces the animation sidecar with only supported PowerPoint fields. `narration_sync.py subtitles` reads the final PPTX's actual presentation order plus millisecond slide-advance and transition values, so `total.srt` follows the same timeline PowerPoint uses when creating a video. A relative `--pptx` path is resolved under `<project_path>`.
+
+Use `--no-merge` for the final narrated SVG export. Keeping each SVG line in its own text frame preserves the authored coordinates; paragraph merging lets PowerPoint recalculate multiline text geometry and can introduce visible offsets.
+
+```json
+{
+ "version": 1,
+ "srt_sha256": "<sha256 of the ordered page-local SRT set>",
+ "narration_padding": 0.5,
+ "slides": {
+ "01_title": {
+ "groups": [
+ { "id": "page-title", "cue": 1 },
+ { "id": "supporting-visual" }
+ ]
+ }
+ }
+}
+```
+
For ElevenLabs, `--voice-id` is required. List voices from your ElevenLabs account with:
```bash
diff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.md
index 1cac3a8f..357d35ca 100644
--- a/docs/zh/audio-narration.md
+++ b/docs/zh/audio-narration.md
@@ -4,11 +4,13 @@
---
-PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edge-tts`](https://github.com/rany2/edge-tts) —— 微软 Edge 的在线神经网络语音;也可配置 ElevenLabs、MiniMax、Qwen TTS、CosyVoice 使用高质量或复刻音色),再把音频嵌入回 PPTX,由 PowerPoint 自带的"导出视频"一键产出带旁白和转场的 MP4,全程无需第三方工具。
+PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edge-tts`](https://github.com/rany2/edge-tts) —— 微软 Edge 的在线神经网络语音;也可配置 ElevenLabs、MiniMax、Qwen TTS、CosyVoice 使用高质量或复刻音色)。Edge 路径还会从同一次 TTS 流中写出该页的 SRT;音频可继续嵌入 PPTX,供 PowerPoint 使用原生视频导出。
## 你会得到什么
- 每页一个音频文件,存放于 `<project_path>/audio/`,文件名与 SVG 对齐(`01_cover.mp3`、`02_market_landscape.mp3` …)。
+- 使用 Edge 时,每页还有一个同名字幕文件,存放于 `<project_path>/notes/subtitles/`(`01_cover.srt`、`02_market_landscape.srt` …)。每个文件使用以 `00:00:00,000` 为原点的页内时间轴,时间来自 Edge 的词边界。
+- 提供 SVG 到 SRT 的计时计划后,还会重建 `animations.json`:无点击入场动画会等待相关字幕 cue;同时生成与最终 PowerPoint 时间轴一致的 `<project_path>/notes/subtitles/total.srt`。
- 可选重新导出:在 `exports/` 生成新版 PPTX,每页对应的 `m4a` / `mp3` / `wav` 音频已嵌入到该页,且页面切换时间按音频长度自动设置——无人值守自动播放和视频导出都不用再手动调时间。
- 演讲者备注原样保留。
@@ -17,7 +19,9 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg
1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。
2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出候选并给每个写一句中文调性说明(如"稳重男声·适合财报")。语速/风格也会基于 notes 信息密度给出推荐值。
3. **一次问完,一次回答**。AI 在一条消息里同时问三件事——生成模式、音色、是否把音频嵌入回 PPTX——每项都标了推荐值。回"好"接受全部默认,或者只说要改的部分(如"音色 2,语速 -5%")。
-4. **执行**。脚本写出逐页音频到 `audio/`,再(如果你保留嵌入)重新导出带音频的 PPTX。不支持长音频导入或自动拆分。
+4. **执行**。使用 Edge 时,脚本从同一次流中把每页 MP3 和 SRT 分别写到 `audio/` 与 `notes/subtitles/`;云端 provider 目前仍只写音频。对于 Generate PPTX,AI 将当前 SVG 内容组映射到编号后的 SRT cue,重建无点击动画,再导出带音频的 PPTX;最后从该 PPTX 读回实际计时并合并逐页 SRT。不支持长音频导入或自动拆分。
+
+字幕保持为外部 SRT 文件:PPT Master 不把字幕嵌入 PPTX,也不直接导出 MP4。请使用 PowerPoint 原生视频导出,并配套使用生成的 `total.srt`。
共享阶段见 [`workflows/stages/generate-audio.md`](../../skills/ppt-master/workflows/stages/generate-audio.md)。
@@ -56,7 +60,7 @@ python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale ja-JP
# 1. 确保备注已切分(后处理 Step 7.1)
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
-# 2A. 用 edge-tts 生成 MP3(默认,无需 API Key)
+# 2A. 用 edge-tts 生成 MP3/SRT 对(默认,无需 API Key)
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice zh-CN-YunjianNeural --rate +0%
@@ -90,13 +94,49 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--voice-id <cosyvoice-voice> \
--cosyvoice-model cosyvoice-v3-flash
-# 3.(可选)重新导出 PPTX 嵌入音频
+# 3. 输出整套 SRT 的指纹,再对照每页当前 SVG 内容组与 SRT cue,编写
+# <project_path>/narration_timing.json;没有对应口播的组不写 cue,
+# 后续按正常动画顺序出现。
+python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path>
+
+# 4. 根据正式 SRT 重建无点击对象动画计时
+python3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \
+ --narration-padding 0.5 --force
+
+# 5. 重新导出 PPTX 嵌入音频
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
- --recorded-narration audio
+ -o <final_narrated_pptx> --no-merge --recorded-narration audio \
+ --narration-padding 0.5
+
+# 6. 按最终 PowerPoint 计时合并逐页 SRT
+python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \
+ --pptx <final_narrated_pptx> --force
```
edge 模式下 `--voice` 是必填项,可用 `--list-voices --locale <locale>` 查看音色。
+Edge 命令会从同一次流式请求中生成 `audio/<stem>.mp3` 与 `notes/subtitles/<stem>.srt`。句末标点必定结束一条字幕;单条超过默认 20 个可见字符时,优先在逗号、分号或冒号处拆分,仍然过长才在最近的词边界拆分。可用 `--subtitle-max-chars` 调整上限。每页 SRT 使用从零计时的页内时间基准,并保留 Edge `WordBoundary` 的实际时间(包括首条字幕前的静音);云端 provider 命令目前只生成音频。
+
+`narration_timing.json` 与 `animations.json` 刻意分离:前者记录整套有序 SRT 的 SHA-256、旁白 padding、有序 SVG 组 ID 和可选的 1-based cue 编号。`narration_sync.py animations` 会拒绝过期的 SRT 指纹,用当前 SVG 校验组 ID,并用 PowerPoint 支持的字段完整替换动画 sidecar。`narration_sync.py subtitles` 从最终 PPTX 读取真实页面关系顺序、毫秒级页面推进与转场时间,因此 `total.srt` 与 PowerPoint“创建视频”使用同一条时间轴。相对 `--pptx` 路径按 `<project_path>` 解析。
+
+最终带旁白的 SVG 导出固定使用 `--no-merge`。让每条 SVG 文本行保持独立文本框,可以保留作者坐标;合并段落会让 PowerPoint 重新计算多行文本几何,可能造成肉眼可见的偏移。
+
+```json
+{
+ "version": 1,
+ "srt_sha256": "<sha256 of the ordered page-local SRT set>",
+ "narration_padding": 0.5,
+ "slides": {
+ "01_title": {
+ "groups": [
+ { "id": "page-title", "cue": 1 },
+ { "id": "supporting-visual" }
+ ]
+ }
+ }
+}
+```
+
ElevenLabs 模式下 `--voice-id` 是必填项,可从账户中列出音色:
```bash
diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.md
index a3663957..d5923fec 100644
--- a/skills/ppt-master/scripts/README.md
+++ b/skills/ppt-master/scripts/README.md
@@ -46,7 +46,7 @@ python3 scripts/update_repo.py
|------|-----------------|---------------|
| Conversion | `source_to_md.py`, `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py`, `pptx_intake.py`, `pptx_to_svg.py` | [docs/conversion.md](./docs/conversion.md) |
| Project management | `project_manager.py`, `page_context.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py` | [docs/project.md](./docs/project.md) |
-| SVG pipeline | `preset_shape_svg.py`, `svg_authoring_view.py`, `compact_svg_coordinates.py`, `mirror_template_materialize.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `extract_svg_pictures.py`, `animation_config.py`, `notes_to_audio.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native preset authoring](../references/native-shape-authoring.md) |
+| SVG pipeline | `preset_shape_svg.py`, `svg_authoring_view.py`, `compact_svg_coordinates.py`, `mirror_template_materialize.py`, `finalize_svg.py`, `svg_to_pptx.py`, `template_preview_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `extract_svg_pictures.py`, `animation_config.py`, `notes_to_audio.py`, `narration_sync.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md); [native preset authoring](../references/native-shape-authoring.md) |
| PPTX transitions | `pptx_transitions.py` | [docs/pptx-transitions.md](./docs/pptx-transitions.md) |
| PPTX animations | `pptx_animations.py`, `animation_config.py` | [docs/pptx-animations.md](./docs/pptx-animations.md) |
| Spec maintenance | `update_spec.py`, `chart_recall.py` | [docs/update_spec.md](./docs/update_spec.md); [docs/chart-recall.md](./docs/chart-recall.md) |
diff --git a/skills/ppt-master/scripts/narration_sync.py b/skills/ppt-master/scripts/narration_sync.py
new file mode 100644
index 00000000..3e852d6b
--- /dev/null
+++ b/skills/ppt-master/scripts/narration_sync.py
@@ -0,0 +1,959 @@
+#!/usr/bin/env python3
+"""
+PPT Master - Narration Sync Tool
+
+Rebuild click-free object timing from page-local SRT cues, then merge those
+subtitles against timing values read from the final narrated PPTX.
+See workflows/stages/generate-audio.md for the owning stage.
+
+Usage:
+ python3 scripts/narration_sync.py fingerprint <project_path>
+ python3 scripts/narration_sync.py animations <project_path> --force
+ python3 scripts/narration_sync.py subtitles <project_path> --pptx <pptx> --force
+
+Examples:
+ python3 scripts/narration_sync.py fingerprint projects/demo
+ python3 scripts/narration_sync.py animations projects/demo --force
+ python3 scripts/narration_sync.py subtitles projects/demo --pptx exports/demo.pptx --force
+
+Dependencies:
+ ffprobe for animation-window validation; otherwise standard library and
+ PPT Master's local SVG/PPTX helpers.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import os
+import posixpath
+import re
+import sys
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+from xml.etree import ElementTree as ET
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+ sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from console_encoding import configure_utf8_stdio # noqa: E402
+from pptx_transitions import read_slide_transition_xml # noqa: E402
+from svg_to_pptx.animation_config import scan_project_targets # noqa: E402
+from svg_to_pptx.pptx_package.narration import ( # noqa: E402
+ NARRATION_EXTENSIONS,
+ probe_audio_duration,
+)
+
+configure_utf8_stdio()
+
+
+_PML_NS = "http://schemas.openxmlformats.org/presentationml/2006/main"
+_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+_DOC_REL_NS = (
+ "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
+)
+_TIMING_RE = re.compile(
+ r"^(?P<start>\d+:\d{2}:\d{2},\d{3})\s+-->\s+"
+ r"(?P<end>\d+:\d{2}:\d{2},\d{3})(?:\s+.*)?$"
+)
+_RHYTHM_RE = re.compile(r"^-\s*P(?P<page>\d+)\s*:\s*(?P<rhythm>[a-z-]+)\s*$")
+_RHYTHM_PROFILES = {
+ "dense": {
+ "transition_duration": 0.3,
+ "animation_duration": 0.35,
+ "stagger": 0.18,
+ },
+ "anchor": {
+ "transition_duration": 0.5,
+ "animation_duration": 0.5,
+ "stagger": 0.3,
+ },
+ "breathing": {
+ "transition_duration": 0.5,
+ "animation_duration": 0.6,
+ "stagger": 0.3,
+ },
+}
+_DEFAULT_PROFILE = {
+ "transition_duration": 0.4,
+ "animation_duration": 0.4,
+ "stagger": 0.25,
+}
+
+
+@dataclass(frozen=True)
+class SubtitleCue:
+ """One parsed SRT cue on a millisecond timeline."""
+
+ start_ms: int
+ end_ms: int
+ text: str
+
+
+@dataclass(frozen=True)
+class TimingPlanEntry:
+ """One ordered SVG animation target and its optional SRT cue anchor."""
+
+ group_id: str
+ cue_number: int | None
+
+
+def _timestamp_to_ms(value: str) -> int:
+ hours_text, minutes_text, remainder = value.split(":")
+ seconds_text, milliseconds_text = remainder.split(",")
+ hours = int(hours_text)
+ minutes = int(minutes_text)
+ seconds = int(seconds_text)
+ milliseconds = int(milliseconds_text)
+ if minutes >= 60 or seconds >= 60:
+ raise ValueError(f"Invalid SRT timestamp: {value}")
+ return (((hours * 60) + minutes) * 60 + seconds) * 1000 + milliseconds
+
+
+def _ms_to_timestamp(value: int) -> str:
+ if value < 0:
+ raise ValueError(f"SRT timestamp cannot be negative: {value}")
+ hours, remainder = divmod(value, 3_600_000)
+ minutes, remainder = divmod(remainder, 60_000)
+ seconds, milliseconds = divmod(remainder, 1000)
+ return f"{hours:02d}:{minutes:02d}:{seconds:02d},{milliseconds:03d}"
+
+
+def _parse_srt(path: Path) -> list[SubtitleCue]:
+ text = path.read_text(encoding="utf-8-sig")
+ blocks = re.split(r"\r?\n\s*\r?\n", text.strip())
+ cues: list[SubtitleCue] = []
+ previous_end = -1
+
+ for block_number, block in enumerate(blocks, 1):
+ lines = block.splitlines()
+ if len(lines) < 3:
+ raise ValueError(f"{path}: malformed SRT block {block_number}")
+ try:
+ cue_number = int(lines[0].strip())
+ except ValueError as exc:
+ raise ValueError(
+ f"{path}: invalid cue number in block {block_number}"
+ ) from exc
+ if cue_number != block_number:
+ raise ValueError(
+ f"{path}: cue numbers must be consecutive from 1; "
+ f"block {block_number} is numbered {cue_number}"
+ )
+ timing_match = _TIMING_RE.match(lines[1].strip())
+ if timing_match is None:
+ raise ValueError(
+ f"{path}: invalid cue timing in block {block_number}"
+ )
+ start_ms = _timestamp_to_ms(timing_match.group("start"))
+ end_ms = _timestamp_to_ms(timing_match.group("end"))
+ cue_text = "\n".join(lines[2:]).strip()
+ if not cue_text:
+ raise ValueError(f"{path}: empty cue text in block {block_number}")
+ if end_ms <= start_ms:
+ raise ValueError(
+ f"{path}: cue {block_number} must end after it starts"
+ )
+ if start_ms < previous_end:
+ raise ValueError(
+ f"{path}: cue {block_number} overlaps the preceding cue"
+ )
+ cues.append(SubtitleCue(start_ms, end_ms, cue_text))
+ previous_end = end_ms
+
+ if not cues:
+ raise ValueError(f"No subtitle cues found: {path}")
+ return cues
+
+
+def _format_srt(cues: list[SubtitleCue]) -> str:
+ blocks = []
+ for index, cue in enumerate(cues, 1):
+ blocks.append(
+ f"{index}\n"
+ f"{_ms_to_timestamp(cue.start_ms)} --> "
+ f"{_ms_to_timestamp(cue.end_ms)}\n"
+ f"{cue.text}"
+ )
+ return "\n\n".join(blocks) + "\n"
+
+
+def _atomic_write_text(path: Path, text: str) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ descriptor, temporary_name = tempfile.mkstemp(
+ prefix=f".{path.name}.",
+ suffix=".tmp",
+ dir=str(path.parent),
+ )
+ temporary_path = Path(temporary_name)
+ try:
+ stream = os.fdopen(descriptor, "w", encoding="utf-8", newline="\n")
+ descriptor = -1
+ with stream:
+ stream.write(text)
+ stream.flush()
+ os.fsync(stream.fileno())
+ os.replace(temporary_path, path)
+ finally:
+ if descriptor >= 0:
+ os.close(descriptor)
+ temporary_path.unlink(missing_ok=True)
+
+
+def _project_path(project_path: Path, value: str | None, default: Path) -> Path:
+ path = Path(value) if value else default
+ return path if path.is_absolute() else project_path / path
+
+
+def _project_input_path(project_path: Path, value: str) -> Path:
+ path = Path(value)
+ if path.is_absolute():
+ return path
+ return project_path / path
+
+
+def _require_replaceable(path: Path, force: bool) -> None:
+ if path.exists() and not force:
+ raise FileExistsError(f"Output already exists: {path}; pass --force to replace it")
+
+
+def _reject_output_alias(
+ output_path: Path,
+ input_paths: list[Path],
+ *,
+ label: str,
+) -> None:
+ output_resolved = output_path.resolve()
+ for input_path in input_paths:
+ if output_resolved == input_path.resolve():
+ raise ValueError(
+ f"{label} output must not overwrite an input file: {output_path}"
+ )
+
+
+def _subtitle_fingerprint(slide_names: list[str], subtitle_dir: Path) -> str:
+ digest = hashlib.sha256()
+ for slide_name in slide_names:
+ path = subtitle_dir / f"{slide_name}.srt"
+ digest.update(slide_name.encode("utf-8"))
+ digest.update(b"\0")
+ digest.update(path.read_bytes())
+ digest.update(b"\0")
+ return digest.hexdigest()
+
+
+def _load_timing_plan(
+ path: Path,
+) -> tuple[str, float, dict[str, list[TimingPlanEntry]]]:
+ raw = json.loads(path.read_text(encoding="utf-8"))
+ if not isinstance(raw, dict):
+ raise ValueError(f"Narration timing plan must be a JSON object: {path}")
+ unknown_top = set(raw) - {
+ "version",
+ "srt_sha256",
+ "narration_padding",
+ "slides",
+ }
+ if unknown_top:
+ raise ValueError(
+ f"Narration timing plan has unknown top-level field(s): "
+ f"{', '.join(sorted(unknown_top))}"
+ )
+ if raw.get("version") != 1:
+ raise ValueError(
+ f"Unsupported narration timing plan version: {raw.get('version')!r}"
+ )
+ srt_sha256 = raw.get("srt_sha256")
+ if (
+ not isinstance(srt_sha256, str)
+ or re.fullmatch(r"[0-9a-f]{64}", srt_sha256) is None
+ ):
+ raise ValueError(
+ 'Narration timing plan field "srt_sha256" must be a lowercase '
+ "SHA-256 digest of the ordered page-local SRT files"
+ )
+ narration_padding = raw.get("narration_padding")
+ if (
+ isinstance(narration_padding, bool)
+ or not isinstance(narration_padding, (int, float))
+ or not math.isfinite(float(narration_padding))
+ or narration_padding < 0
+ ):
+ raise ValueError(
+ 'Narration timing plan field "narration_padding" must be a '
+ "finite non-negative number"
+ )
+ slides = raw.get("slides")
+ if not isinstance(slides, dict):
+ raise ValueError('Narration timing plan field "slides" must be an object')
+
+ result: dict[str, list[TimingPlanEntry]] = {}
+ for slide_name, slide_raw in slides.items():
+ if not isinstance(slide_name, str) or not slide_name:
+ raise ValueError("Narration timing plan slide names must be non-empty strings")
+ if not isinstance(slide_raw, dict) or set(slide_raw) != {"groups"}:
+ raise ValueError(
+ f'Narration timing plan slide "{slide_name}" must contain only "groups"'
+ )
+ groups = slide_raw["groups"]
+ if not isinstance(groups, list) or not groups:
+ raise ValueError(
+ f'Narration timing plan slide "{slide_name}" groups must be a non-empty list'
+ )
+
+ entries: list[TimingPlanEntry] = []
+ seen_groups: set[str] = set()
+ for position, entry_raw in enumerate(groups, 1):
+ if not isinstance(entry_raw, dict):
+ raise ValueError(
+ f'Narration timing plan "{slide_name}" group #{position} '
+ "must be an object"
+ )
+ unknown_fields = set(entry_raw) - {"id", "cue"}
+ if unknown_fields:
+ raise ValueError(
+ f'Narration timing plan "{slide_name}" group #{position} '
+ f"has unknown field(s): {', '.join(sorted(unknown_fields))}"
+ )
+ group_id = entry_raw.get("id")
+ if not isinstance(group_id, str) or not group_id.strip():
+ raise ValueError(
+ f'Narration timing plan "{slide_name}" group #{position} '
+ 'field "id" must be a non-empty string'
+ )
+ if group_id in seen_groups:
+ raise ValueError(
+ f'Narration timing plan "{slide_name}" repeats group "{group_id}"'
+ )
+ cue_number = entry_raw.get("cue")
+ if cue_number is not None and (
+ isinstance(cue_number, bool)
+ or not isinstance(cue_number, int)
+ or cue_number <= 0
+ ):
+ raise ValueError(
+ f'Narration timing plan "{slide_name}/{group_id}" cue '
+ "must be a positive integer or null"
+ )
+ entries.append(TimingPlanEntry(group_id, cue_number))
+ seen_groups.add(group_id)
+ result[slide_name] = entries
+ return srt_sha256, float(narration_padding), result
+
+
+def _load_page_rhythms(path: Path) -> dict[int, str]:
+ if not path.exists():
+ return {}
+ rhythms: dict[int, str] = {}
+ in_section = False
+ for line in path.read_text(encoding="utf-8").splitlines():
+ if line.startswith("## "):
+ in_section = line.strip() == "## page_rhythm"
+ continue
+ if not in_section:
+ continue
+ match = _RHYTHM_RE.match(line.strip())
+ if match is None:
+ continue
+ rhythms[int(match.group("page"))] = match.group("rhythm")
+ return rhythms
+
+
+def _profile_for_slide(
+ slide_index: int,
+ slide_count: int,
+ rhythms: dict[int, str],
+) -> dict[str, float]:
+ profile = dict(_RHYTHM_PROFILES.get(rhythms.get(slide_index), _DEFAULT_PROFILE))
+ if slide_index == 1:
+ profile["transition_duration"] = 0.6
+ profile["animation_duration"] = max(profile["animation_duration"], 0.55)
+ profile["stagger"] = max(profile["stagger"], 0.3)
+ if slide_index == slide_count:
+ profile["transition_duration"] = 0.6
+ profile["animation_duration"] = max(profile["animation_duration"], 0.65)
+ profile["stagger"] = max(profile["stagger"], 0.35)
+ return profile
+
+
+def _find_audio(audio_dir: Path, slide_name: str) -> Path:
+ matches = [
+ path
+ for path in audio_dir.iterdir()
+ if path.is_file()
+ and path.stem == slide_name
+ and path.suffix.lower() in NARRATION_EXTENSIONS
+ ]
+ if not matches:
+ raise FileNotFoundError(f"Missing narration audio for slide: {slide_name}")
+ if len(matches) > 1:
+ rendered = ", ".join(str(path) for path in matches)
+ raise ValueError(f"Multiple narration audio files match {slide_name}: {rendered}")
+ return matches[0]
+
+
+def _seconds_from_ms(value: int) -> float:
+ return round(value / 1000, 3)
+
+
+def rebuild_animations(
+ project_path: Path,
+ *,
+ plan_path: Path,
+ subtitle_dir: Path,
+ audio_dir: Path,
+ output_path: Path,
+ narration_padding: float,
+ force: bool,
+) -> tuple[int, int, int, int]:
+ """Replace ``animations.json`` from the current SVG/SRT timing plan."""
+ if not math.isfinite(narration_padding) or narration_padding < 0:
+ raise ValueError("Narration padding must be finite and non-negative")
+ _reject_output_alias(
+ output_path,
+ [plan_path],
+ label="Animation config",
+ )
+
+ targets_by_slide, anonymous_groups = scan_project_targets(project_path)
+ if anonymous_groups:
+ details = "\n".join(f"- {item}" for item in anonymous_groups)
+ raise ValueError(
+ "Every top-level animation group must have an id before narration sync:\n"
+ f"{details}"
+ )
+ slide_names = list(targets_by_slide)
+ if not slide_names:
+ raise ValueError(f"No SVG slides found under: {project_path / 'svg_output'}")
+
+ for slide_name, targets in targets_by_slide.items():
+ group_ids = [target.group_id for target in targets]
+ duplicate_ids = sorted(
+ group_id
+ for group_id in set(group_ids)
+ if group_ids.count(group_id) > 1
+ )
+ if duplicate_ids:
+ raise ValueError(
+ f'SVG slide "{slide_name}" has duplicate top-level group id(s): '
+ f"{', '.join(duplicate_ids)}"
+ )
+
+ (
+ expected_srt_sha256,
+ planned_narration_padding,
+ timing_plan,
+ ) = _load_timing_plan(plan_path)
+ if not math.isclose(
+ narration_padding,
+ planned_narration_padding,
+ rel_tol=0,
+ abs_tol=1e-9,
+ ):
+ raise ValueError(
+ "Narration padding differs from the timing plan: "
+ f"plan={planned_narration_padding}, command={narration_padding}"
+ )
+ subtitle_paths = [
+ subtitle_dir / f"{slide_name}.srt"
+ for slide_name in slide_names
+ ]
+ _reject_output_alias(
+ output_path,
+ subtitle_paths,
+ label="Animation config",
+ )
+ current_srt_sha256 = _subtitle_fingerprint(slide_names, subtitle_dir)
+ if current_srt_sha256 != expected_srt_sha256:
+ raise ValueError(
+ "Narration timing plan was authored for a different SRT set: "
+ f"plan={expected_srt_sha256}, current={current_srt_sha256}; "
+ "rebuild the cue mapping before regenerating animations"
+ )
+
+ expected_slides = set(slide_names)
+ planned_slides = set(timing_plan)
+ if expected_slides != planned_slides:
+ missing = sorted(expected_slides - planned_slides)
+ extra = sorted(planned_slides - expected_slides)
+ details = []
+ if missing:
+ details.append(f"missing slide(s): {', '.join(missing)}")
+ if extra:
+ details.append(f"unknown slide(s): {', '.join(extra)}")
+ raise ValueError("Narration timing plan does not match current SVGs: " + "; ".join(details))
+
+ rhythms = _load_page_rhythms(project_path / "spec_lock.md")
+ slides_config: dict[str, Any] = {}
+ anchored_count = 0
+ fallback_count = 0
+ drift_warnings: list[str] = []
+ audio_paths: list[Path] = []
+
+ for slide_index, slide_name in enumerate(slide_names, 1):
+ cues = _parse_srt(subtitle_dir / f"{slide_name}.srt")
+ audio_path = _find_audio(audio_dir, slide_name)
+ audio_paths.append(audio_path)
+ audio_duration = probe_audio_duration(audio_path)
+ if audio_duration is None:
+ raise RuntimeError(
+ f"Unable to read narration duration with ffprobe: {audio_path}"
+ )
+
+ all_targets = {target.group_id: target for target in targets_by_slide[slide_name]}
+ required_groups = {
+ target.group_id
+ for target in targets_by_slide[slide_name]
+ if not target.chrome
+ }
+ entries = timing_plan[slide_name]
+ planned_groups = {entry.group_id for entry in entries}
+ missing_groups = sorted(required_groups - planned_groups)
+ if missing_groups:
+ raise ValueError(
+ f'Narration timing plan slide "{slide_name}" omits content group(s): '
+ f"{', '.join(missing_groups)}"
+ )
+
+ for entry in entries:
+ target = all_targets.get(entry.group_id)
+ if target is None:
+ raise ValueError(
+ f'Narration timing plan references missing group: '
+ f"{slide_name}/{entry.group_id}"
+ )
+ if target.structurally_static:
+ raise ValueError(
+ f"Narration timing plan cannot animate structural group: "
+ f"{slide_name}/{entry.group_id}"
+ )
+ if entry.cue_number is not None and entry.cue_number > len(cues):
+ raise ValueError(
+ f'Narration timing plan "{slide_name}/{entry.group_id}" '
+ f"references cue {entry.cue_number}, but the SRT has {len(cues)} cues"
+ )
+
+ profile = _profile_for_slide(slide_index, len(slide_names), rhythms)
+ animation_duration_ms = int(profile["animation_duration"] * 1000)
+ stagger_ms = int(profile["stagger"] * 1000)
+ previous_end_ms = 0
+ groups_config: dict[str, Any] = {}
+
+ for order, entry in enumerate(entries, 1):
+ next_entry = entries[order] if order < len(entries) else None
+ effective_duration_ms = animation_duration_ms
+ if (
+ entry.cue_number is not None
+ and next_entry is not None
+ and next_entry.cue_number == entry.cue_number
+ ):
+ effective_duration_ms = min(animation_duration_ms, 250)
+
+ if entry.cue_number is None:
+ fallback_count += 1
+ if order == 1:
+ desired_start_ms = cues[0].start_ms
+ actual_start_ms = max(desired_start_ms, previous_end_ms)
+ delay_ms = actual_start_ms - previous_end_ms
+ else:
+ delay_ms = stagger_ms
+ actual_start_ms = previous_end_ms + delay_ms
+ else:
+ anchored_count += 1
+ desired_start_ms = cues[entry.cue_number - 1].start_ms
+ actual_start_ms = max(desired_start_ms, previous_end_ms)
+ delay_ms = actual_start_ms - previous_end_ms
+ drift_ms = actual_start_ms - desired_start_ms
+ if drift_ms > 500:
+ drift_warnings.append(
+ f"{slide_name}/{entry.group_id}: cue {entry.cue_number} "
+ f"starts at {_seconds_from_ms(desired_start_ms):.3f}s, "
+ f"animation starts at {_seconds_from_ms(actual_start_ms):.3f}s "
+ f"(after-previous drift {_seconds_from_ms(drift_ms):.3f}s)"
+ )
+
+ group_config = {
+ "order": order,
+ "delay": _seconds_from_ms(delay_ms),
+ }
+ if effective_duration_ms != animation_duration_ms:
+ group_config["duration"] = _seconds_from_ms(effective_duration_ms)
+ groups_config[entry.group_id] = group_config
+ previous_end_ms = actual_start_ms + effective_duration_ms
+
+ advance_ms = int((audio_duration + narration_padding) * 1000)
+ if previous_end_ms > advance_ms:
+ raise ValueError(
+ f'Animations on slide "{slide_name}" end at '
+ f"{_seconds_from_ms(previous_end_ms):.3f}s, after the recorded "
+ f"slide advance at {_seconds_from_ms(advance_ms):.3f}s"
+ )
+
+ slides_config[slide_name] = {
+ "transition": {
+ "effect": "fade",
+ "duration": profile["transition_duration"],
+ },
+ "animation": {
+ "effect": "auto",
+ "duration": profile["animation_duration"],
+ "stagger": profile["stagger"],
+ "trigger": "after-previous",
+ },
+ "groups": groups_config,
+ }
+
+ _reject_output_alias(
+ output_path,
+ audio_paths,
+ label="Animation config",
+ )
+ _require_replaceable(output_path, force)
+ config = {
+ "version": 1,
+ "defaults": {
+ "transition": {"effect": "fade", "duration": 0.4},
+ "animation": {
+ "effect": "auto",
+ "duration": 0.4,
+ "stagger": 0.25,
+ "trigger": "after-previous",
+ },
+ },
+ "slides": slides_config,
+ }
+ _atomic_write_text(
+ output_path,
+ json.dumps(config, ensure_ascii=False, indent=2) + "\n",
+ )
+
+ for warning in drift_warnings:
+ print(f"Warning: {warning}", file=sys.stderr)
+ return len(slide_names), anchored_count + fallback_count, anchored_count, fallback_count
+
+
+def _presentation_slide_members(package: zipfile.ZipFile) -> list[str]:
+ try:
+ presentation_root = ET.fromstring(package.read("ppt/presentation.xml"))
+ relationships_root = ET.fromstring(
+ package.read("ppt/_rels/presentation.xml.rels")
+ )
+ except KeyError as exc:
+ raise ValueError(
+ f"Narrated PPTX is missing presentation ordering data: {exc}"
+ ) from exc
+
+ relationship_targets: dict[str, str] = {}
+ for relationship in relationships_root.iter(f"{{{_REL_NS}}}Relationship"):
+ relationship_id = relationship.get("Id")
+ target = relationship.get("Target")
+ if (
+ relationship_id
+ and target
+ and relationship.get("TargetMode", "Internal") != "External"
+ ):
+ relationship_targets[relationship_id] = target.replace("\\", "/")
+
+ slide_list = presentation_root.find(f"{{{_PML_NS}}}sldIdLst")
+ if slide_list is None:
+ raise ValueError("Narrated PPTX presentation has no slide order")
+
+ members: list[str] = []
+ for slide_id in slide_list.findall(f"{{{_PML_NS}}}sldId"):
+ relationship_id = slide_id.get(f"{{{_DOC_REL_NS}}}id")
+ target = relationship_targets.get(relationship_id or "")
+ if target is None:
+ raise ValueError(
+ "Narrated PPTX slide order references a missing relationship: "
+ f"{relationship_id!r}"
+ )
+ if target.startswith("/"):
+ member = posixpath.normpath(target.lstrip("/"))
+ else:
+ member = posixpath.normpath(posixpath.join("ppt", target))
+ if member not in package.namelist():
+ raise ValueError(
+ f"Narrated PPTX slide relationship target is missing: {member}"
+ )
+ members.append(member)
+ return members
+
+
+def _read_powerpoint_timings(pptx_path: Path, slide_count: int) -> list[tuple[int, int]]:
+ timings: list[tuple[int, int]] = []
+ with zipfile.ZipFile(pptx_path) as package:
+ slide_members = _presentation_slide_members(package)
+ if len(slide_members) != slide_count:
+ raise ValueError(
+ f"Narrated PPTX has {len(slide_members)} slides, "
+ f"but the project has {slide_count}"
+ )
+ for slide_index, member in enumerate(slide_members, 1):
+ summary = read_slide_transition_xml(package.read(member))
+ if summary.logical_count != 1:
+ raise ValueError(
+ f"Narrated PPTX slide {slide_index} has "
+ f"{summary.logical_count} logical transition carriers"
+ )
+ advance_ms = summary.advance_after_ms
+ if advance_ms is None:
+ raise ValueError(
+ f"Narrated PPTX slide {slide_index} has no recorded advance time"
+ )
+ transition_ms = summary.duration_ms or 0
+ if advance_ms <= 0 or transition_ms < 0:
+ raise ValueError(
+ f"Narrated PPTX slide {slide_index} has invalid timing values"
+ )
+ timings.append((transition_ms, advance_ms))
+ return timings
+
+
+def merge_subtitles(
+ project_path: Path,
+ *,
+ pptx_path: Path,
+ subtitle_dir: Path,
+ output_path: Path,
+ force: bool,
+) -> tuple[int, int, int]:
+ """Merge local SRT files using timing values read from the final PPTX."""
+ targets_by_slide, _anonymous_groups = scan_project_targets(project_path)
+ slide_names = list(targets_by_slide)
+ if not slide_names:
+ raise ValueError(f"No SVG slides found under: {project_path / 'svg_output'}")
+
+ local_subtitle_paths = [
+ subtitle_dir / f"{slide_name}.srt"
+ for slide_name in slide_names
+ ]
+ _reject_output_alias(
+ output_path,
+ [pptx_path, *local_subtitle_paths],
+ label="Merged subtitle",
+ )
+ _require_replaceable(output_path, force)
+ timings = _read_powerpoint_timings(pptx_path, len(slide_names))
+ merged_cues: list[SubtitleCue] = []
+ timeline_ms = 0
+
+ for slide_name, (transition_ms, advance_ms) in zip(slide_names, timings):
+ local_cues = _parse_srt(subtitle_dir / f"{slide_name}.srt")
+ if local_cues[-1].end_ms > advance_ms:
+ raise ValueError(
+ f"{slide_name}.srt ends at "
+ f"{_seconds_from_ms(local_cues[-1].end_ms):.3f}s, after the "
+ f"PowerPoint slide advance at {_seconds_from_ms(advance_ms):.3f}s"
+ )
+ audio_start_ms = timeline_ms + transition_ms
+ merged_cues.extend(
+ SubtitleCue(
+ cue.start_ms + audio_start_ms,
+ cue.end_ms + audio_start_ms,
+ cue.text,
+ )
+ for cue in local_cues
+ )
+ timeline_ms = audio_start_ms + advance_ms
+
+ _atomic_write_text(output_path, _format_srt(merged_cues))
+ return len(slide_names), len(merged_cues), timeline_ms
+
+
+def build_parser() -> argparse.ArgumentParser:
+ parser = argparse.ArgumentParser(
+ description=(
+ "Rebuild narrated object animation timings and merge page-local "
+ "SRT files on PowerPoint's final timeline."
+ ),
+ formatter_class=argparse.RawDescriptionHelpFormatter,
+ )
+ subparsers = parser.add_subparsers(dest="command", required=True)
+
+ fingerprint = subparsers.add_parser(
+ "fingerprint",
+ help="print the SHA-256 used to bind a timing plan to page-local SRT files",
+ )
+ fingerprint.add_argument("project_path", help="Project directory")
+ fingerprint.add_argument(
+ "--subtitle-dir",
+ default=None,
+ help="Page-local SRT directory; default: <project>/notes/subtitles",
+ )
+
+ animations = subparsers.add_parser(
+ "animations",
+ help="replace animations.json from narration_timing.json and page-local SRT",
+ )
+ animations.add_argument("project_path", help="Project directory")
+ animations.add_argument(
+ "--plan",
+ default=None,
+ help="Timing plan; default: <project>/narration_timing.json",
+ )
+ animations.add_argument(
+ "--subtitle-dir",
+ default=None,
+ help="Page-local SRT directory; default: <project>/notes/subtitles",
+ )
+ animations.add_argument(
+ "--audio-dir",
+ default=None,
+ help="Narration audio directory; default: <project>/audio",
+ )
+ animations.add_argument(
+ "-o",
+ "--output",
+ default=None,
+ help="Animation config output; default: <project>/animations.json",
+ )
+ animations.add_argument(
+ "--narration-padding",
+ type=float,
+ default=0.5,
+ help="Seconds added after each narration before slide advance (default: 0.5)",
+ )
+ animations.add_argument(
+ "--force",
+ action="store_true",
+ help="Replace an existing animations.json",
+ )
+
+ subtitles = subparsers.add_parser(
+ "subtitles",
+ help="merge page-local SRT using timings read from a narrated PPTX",
+ )
+ subtitles.add_argument("project_path", help="Project directory")
+ subtitles.add_argument(
+ "--pptx",
+ required=True,
+ help=(
+ "Final narrated PPTX whose recorded timing values define the "
+ "timeline; relative paths are resolved under the project"
+ ),
+ )
+ subtitles.add_argument(
+ "--subtitle-dir",
+ default=None,
+ help="Page-local SRT directory; default: <project>/notes/subtitles",
+ )
+ subtitles.add_argument(
+ "-o",
+ "--output",
+ default=None,
+ help="Merged SRT output; default: <project>/notes/subtitles/total.srt",
+ )
+ subtitles.add_argument(
+ "--force",
+ action="store_true",
+ help="Replace an existing merged SRT",
+ )
+ return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = build_parser()
+ args = parser.parse_args(argv)
+ project_path = Path(args.project_path).resolve()
+ if not project_path.is_dir():
+ parser.error(f"Project path does not exist: {project_path}")
+
+ try:
+ if args.command == "fingerprint":
+ subtitle_dir = _project_path(
+ project_path,
+ args.subtitle_dir,
+ Path("notes/subtitles"),
+ )
+ targets_by_slide, _anonymous_groups = scan_project_targets(project_path)
+ slide_names = list(targets_by_slide)
+ if not slide_names:
+ raise ValueError(
+ f"No SVG slides found under: {project_path / 'svg_output'}"
+ )
+ for slide_name in slide_names:
+ _parse_srt(subtitle_dir / f"{slide_name}.srt")
+ print(_subtitle_fingerprint(slide_names, subtitle_dir))
+ return 0
+
+ if args.command == "animations":
+ plan_path = _project_path(
+ project_path,
+ args.plan,
+ Path("narration_timing.json"),
+ )
+ subtitle_dir = _project_path(
+ project_path,
+ args.subtitle_dir,
+ Path("notes/subtitles"),
+ )
+ audio_dir = _project_path(
+ project_path,
+ args.audio_dir,
+ Path("audio"),
+ )
+ output_path = _project_path(
+ project_path,
+ args.output,
+ Path("animations.json"),
+ )
+ slide_count, group_count, anchored_count, fallback_count = rebuild_animations(
+ project_path,
+ plan_path=plan_path,
+ subtitle_dir=subtitle_dir,
+ audio_dir=audio_dir,
+ output_path=output_path,
+ narration_padding=args.narration_padding,
+ force=args.force,
+ )
+ print(f"Animation config rebuilt: {output_path}")
+ print(
+ f"Slides: {slide_count}; groups: {group_count}; "
+ f"SRT-anchored: {anchored_count}; sequential fallback: {fallback_count}"
+ )
+ return 0
+
+ pptx_path = _project_input_path(project_path, args.pptx).resolve()
+ subtitle_dir = _project_path(
+ project_path,
+ args.subtitle_dir,
+ Path("notes/subtitles"),
+ )
+ output_path = _project_path(
+ project_path,
+ args.output,
+ Path("notes/subtitles/total.srt"),
+ )
+ slide_count, cue_count, timeline_ms = merge_subtitles(
+ project_path,
+ pptx_path=pptx_path,
+ subtitle_dir=subtitle_dir,
+ output_path=output_path,
+ force=args.force,
+ )
+ print(f"Merged subtitle written: {output_path}")
+ print(
+ f"Slides: {slide_count}; cues: {cue_count}; "
+ f"PowerPoint timeline: {_seconds_from_ms(timeline_ms):.3f}s"
+ )
+ return 0
+ except (
+ ET.ParseError,
+ OSError,
+ OverflowError,
+ ValueError,
+ RuntimeError,
+ zipfile.BadZipFile,
+ ) as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/skills/ppt-master/scripts/notes_to_audio.py b/skills/ppt-master/scripts/notes_to_audio.py
index 7009e5a1..f0bc1aa5 100644
--- a/skills/ppt-master/scripts/notes_to_audio.py
+++ b/skills/ppt-master/scripts/notes_to_audio.py
@@ -2,7 +2,8 @@
"""Generate per-slide narration audio from PPT Master notes.
This script uses provider backends for the same per-slide output contract on
-macOS, Linux, and Windows. `edge-tts` remains the default no-key backend.
+macOS, Linux, and Windows. `edge-tts` remains the default no-key backend and
+also writes one compact, word-timed SRT file per slide from the same TTS stream.
Usage:
python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> --voice zh-CN-XiaoxiaoNeural
@@ -107,6 +108,12 @@ def main() -> int:
default="+0%",
help='edge-tts speaking rate, e.g. "+0%%", "-10%%", "+15%%" (default: +0%%). Ignored by cloud providers.',
)
+ parser.add_argument(
+ "--subtitle-max-chars",
+ type=int,
+ default=backend_edge.DEFAULT_SUBTITLE_MAX_CHARS,
+ help="maximum visible characters per Edge subtitle cue (default: 20)",
+ )
parser.add_argument(
"--elevenlabs-api-key-env",
default="ELEVENLABS_API_KEY",
@@ -245,6 +252,10 @@ def main() -> int:
parser.error(f"--voice-id is required for --provider {args.provider}")
raise AssertionError("unreachable")
+ if args.subtitle_max_chars < 1:
+ parser.error("--subtitle-max-chars must be at least 1")
+ raise AssertionError("unreachable")
+
if args.provider == "elevenlabs":
if not voice_id:
parser.error("--voice-id is required for --provider elevenlabs")
@@ -291,6 +302,9 @@ def main() -> int:
notes_dir = project / "notes"
output_dir = args.output or (project / "audio")
output_dir.mkdir(parents=True, exist_ok=True)
+ subtitle_dir = notes_dir / "subtitles"
+ if backend.provider == "edge":
+ subtitle_dir.mkdir(parents=True, exist_ok=True)
note_files = [
path for path in sorted(notes_dir.glob("*.md"))
@@ -367,14 +381,32 @@ def main() -> int:
base_url=args.cosyvoice_base_url,
)
else:
- asyncio.run(backend_edge.generate(text, output_path, voice=args.voice, rate=args.rate))
+ subtitle_path = subtitle_dir / f"{note_path.stem}.srt"
+ asyncio.run(
+ backend_edge.generate(
+ text,
+ output_path,
+ voice=args.voice,
+ rate=args.rate,
+ subtitle_path=subtitle_path,
+ subtitle_max_chars=args.subtitle_max_chars,
+ )
+ )
except Exception as exc:
print(f"error: failed to generate {output_path}: {exc}", file=sys.stderr)
return 1
generated += 1
print(f"[OK] {output_path}")
+ if backend.provider == "edge":
+ print(f" {subtitle_path}")
- print(f"[Done] Generated {generated}/{len(note_files)} audio file(s): {output_dir}")
+ if backend.provider == "edge":
+ print(
+ f"[Done] Generated {generated}/{len(note_files)} audio/SRT pair(s): "
+ f"{output_dir} + {subtitle_dir}"
+ )
+ else:
+ print(f"[Done] Generated {generated}/{len(note_files)} audio file(s): {output_dir}")
return 0
diff --git a/skills/ppt-master/scripts/tts_backends/backend_edge.py b/skills/ppt-master/scripts/tts_backends/backend_edge.py
index 8f8445e4..bc0a2ae7 100644
--- a/skills/ppt-master/scripts/tts_backends/backend_edge.py
+++ b/skills/ppt-master/scripts/tts_backends/backend_edge.py
@@ -2,10 +2,34 @@
from __future__ import annotations
+import os
import re
+import tempfile
+from dataclasses import dataclass
from pathlib import Path
+DEFAULT_SUBTITLE_MAX_CHARS = 20
+_SENTENCE_END = frozenset("。!?!?")
+_CLAUSE_END = frozenset(",,;;::")
+_CLOSING_PUNCTUATION = frozenset('”’」』)》)"\'')
+
+
+@dataclass(frozen=True)
+class _MappedWord:
+ start: int
+ end: int
+ source_start: int
+ source_end: int
+
+
+@dataclass(frozen=True)
+class _SubtitleCue:
+ start: int
+ end: int
+ text: str
+
+
COMMON_VOICES = [
("zh-CN", "zh-CN-XiaoxiaoNeural", "女声,普通话,清晰自然,默认推荐"),
("zh-CN", "zh-CN-XiaoyiNeural", "女声,普通话,明亮"),
@@ -43,7 +67,27 @@ def normalize_rate(rate: str) -> str:
return value
-async def generate(text: str, output_path: Path, *, voice: str, rate: str) -> None:
+async def generate(
+ text: str,
+ output_path: Path,
+ *,
+ voice: str,
+ rate: str,
+ subtitle_path: Path | None = None,
+ subtitle_max_chars: int = DEFAULT_SUBTITLE_MAX_CHARS,
+) -> None:
+ """Generate narration audio and, when requested, its compact SRT."""
+ if subtitle_path is not None:
+ await _generate_with_subtitles(
+ text,
+ output_path,
+ subtitle_path,
+ voice=voice,
+ rate=rate,
+ max_chars=subtitle_max_chars,
+ )
+ return
+
try:
import edge_tts
except ImportError as exc:
@@ -56,6 +100,399 @@ async def generate(text: str, output_path: Path, *, voice: str, rate: str) -> No
await communicate.save(str(output_path))
+def _temporary_path(target: Path, suffix: str) -> tuple[int, Path]:
+ target.parent.mkdir(parents=True, exist_ok=True)
+ descriptor, raw_path = tempfile.mkstemp(
+ prefix=f".{target.name}.",
+ suffix=suffix,
+ dir=target.parent,
+ )
+ return descriptor, Path(raw_path)
+
+
+def _publish_pair(
+ staged_audio: Path,
+ output_path: Path,
+ staged_subtitle: Path,
+ subtitle_path: Path,
+) -> None:
+ targets = (output_path, subtitle_path)
+ if output_path.resolve() == subtitle_path.resolve():
+ raise ValueError("audio and subtitle outputs must use different paths")
+
+ backups: dict[Path, Path] = {}
+ published: set[Path] = set()
+ try:
+ for target in targets:
+ if not target.exists():
+ continue
+ descriptor, backup = _temporary_path(target, ".bak")
+ os.close(descriptor)
+ backup.unlink()
+ os.replace(target, backup)
+ backups[target] = backup
+
+ for staged, target in (
+ (staged_audio, output_path),
+ (staged_subtitle, subtitle_path),
+ ):
+ os.replace(staged, target)
+ published.add(target)
+ except Exception:
+ for target in published:
+ target.unlink(missing_ok=True)
+ for target, backup in backups.items():
+ if backup.exists():
+ os.replace(backup, target)
+ raise
+ finally:
+ staged_audio.unlink(missing_ok=True)
+ staged_subtitle.unlink(missing_ok=True)
+ for backup in backups.values():
+ backup.unlink(missing_ok=True)
+
+
+def _text_key(text: str) -> str:
+ return "".join(character.casefold() for character in text if character.isalnum())
+
+
+def _source_key_positions(text: str) -> tuple[str, list[int]]:
+ key: list[str] = []
+ positions: list[int] = []
+ for index, character in enumerate(text):
+ if not character.isalnum():
+ continue
+ normalized = character.casefold()
+ key.extend(normalized)
+ positions.extend([index] * len(normalized))
+ return "".join(key), positions
+
+
+def _map_word_boundaries(text: str, boundaries: list[dict]) -> list[_MappedWord]:
+ source_key, source_positions = _source_key_positions(text)
+ boundary_keys = [_text_key(boundary["text"]) for boundary in boundaries]
+ boundary_key = "".join(boundary_keys)
+ if not source_key or source_key != boundary_key:
+ raise RuntimeError(
+ "Edge TTS word boundaries could not be aligned with the narration text; "
+ "subtitle timing was not generated"
+ )
+
+ mapped: list[_MappedWord] = []
+ key_offset = 0
+ for boundary, word_key in zip(boundaries, boundary_keys):
+ if not word_key:
+ continue
+ key_end = key_offset + len(word_key)
+ mapped.append(
+ _MappedWord(
+ start=boundary["offset"],
+ end=boundary["offset"] + boundary["duration"],
+ source_start=source_positions[key_offset],
+ source_end=source_positions[key_end - 1] + 1,
+ )
+ )
+ key_offset = key_end
+ return mapped
+
+
+def _trim_span(text: str, start: int, end: int) -> tuple[int, int]:
+ while start < end and text[start].isspace():
+ start += 1
+ while end > start and text[end - 1].isspace():
+ end -= 1
+ return start, end
+
+
+def _display_length(text: str, start: int, end: int) -> int:
+ return sum(not character.isspace() for character in text[start:end])
+
+
+def _is_sentence_end(text: str, index: int) -> bool:
+ character = text[index]
+ if character in _SENTENCE_END:
+ return True
+ if character != ".":
+ return False
+ previous = text[index - 1] if index else ""
+ following = text[index + 1] if index + 1 < len(text) else ""
+ return not (previous.isdigit() and following.isdigit())
+
+
+def _sentence_spans(text: str) -> list[tuple[int, int]]:
+ spans: list[tuple[int, int]] = []
+ start = 0
+ index = 0
+ while index < len(text):
+ if not _is_sentence_end(text, index):
+ index += 1
+ continue
+ end = index + 1
+ while end < len(text) and text[end] in _CLOSING_PUNCTUATION:
+ end += 1
+ span = _trim_span(text, start, end)
+ if span[0] < span[1]:
+ spans.append(span)
+ start = end
+ index = end
+ span = _trim_span(text, start, len(text))
+ if span[0] < span[1]:
+ spans.append(span)
+ return spans
+
+
+def _hard_split_span(
+ text: str,
+ span: tuple[int, int],
+ words: list[_MappedWord],
+ max_chars: int,
+) -> list[tuple[int, int]]:
+ start, end = span
+ parts: list[tuple[int, int]] = []
+ while _display_length(text, start, end) > max_chars:
+ remaining_length = _display_length(text, start, end)
+ remaining_parts = (remaining_length + max_chars - 1) // max_chars
+ target_length = (remaining_length + remaining_parts - 1) // remaining_parts
+ candidates = [
+ (word.source_end, _display_length(text, start, word.source_end))
+ for word in words
+ if start < word.source_end < end
+ and _display_length(text, start, word.source_end) <= max_chars
+ ]
+ if candidates:
+ split_at, _ = min(
+ candidates,
+ key=lambda candidate: (
+ abs(candidate[1] - target_length),
+ -candidate[1],
+ ),
+ )
+ else:
+ split_at = next(
+ (
+ word.source_end
+ for word in words
+ if start < word.source_end < end
+ ),
+ end,
+ )
+ if split_at >= end:
+ break
+ part = _trim_span(text, start, split_at)
+ if part[0] < part[1]:
+ parts.append(part)
+ start = split_at
+ part = _trim_span(text, start, end)
+ if part[0] < part[1]:
+ parts.append(part)
+ return parts
+
+
+def _split_sentence_span(
+ text: str,
+ sentence: tuple[int, int],
+ words: list[_MappedWord],
+ max_chars: int,
+) -> list[tuple[int, int]]:
+ if _display_length(text, *sentence) <= max_chars:
+ return [sentence]
+
+ start, end = sentence
+ clauses: list[tuple[int, int]] = []
+ clause_start = start
+ for index in range(start, end):
+ if text[index] not in _CLAUSE_END:
+ continue
+ clause = _trim_span(text, clause_start, index + 1)
+ if clause[0] < clause[1]:
+ clauses.append(clause)
+ clause_start = index + 1
+ clause = _trim_span(text, clause_start, end)
+ if clause[0] < clause[1]:
+ clauses.append(clause)
+
+ atoms = [
+ part
+ for clause in clauses
+ for part in _hard_split_span(text, clause, words, max_chars)
+ ]
+ merged: list[tuple[int, int]] = []
+ for atom in atoms:
+ if not merged:
+ merged.append(atom)
+ continue
+ candidate = (merged[-1][0], atom[1])
+ if _display_length(text, *candidate) <= max_chars:
+ merged[-1] = candidate
+ else:
+ merged.append(atom)
+ return merged
+
+
+def _subtitle_cues(
+ text: str,
+ boundaries: list[dict],
+ max_chars: int,
+) -> list[_SubtitleCue]:
+ if max_chars < 1:
+ raise ValueError("subtitle_max_chars must be at least 1")
+ words = _map_word_boundaries(text, boundaries)
+ spans = [
+ span
+ for sentence in _sentence_spans(text)
+ for span in _split_sentence_span(text, sentence, words, max_chars)
+ ]
+
+ pending: list[tuple[int, int, str]] = []
+ assigned_word_indexes: list[int] = []
+ for start, end in spans:
+ matching = [
+ (index, word)
+ for index, word in enumerate(words)
+ if word.source_start >= start and word.source_end <= end
+ ]
+ if not matching:
+ continue
+ cue_text = re.sub(r"\s+", " ", text[start:end]).strip()
+ assigned_word_indexes.extend(index for index, _ in matching)
+ pending.append((matching[0][1].start, matching[-1][1].end, cue_text))
+
+ if assigned_word_indexes != list(range(len(words))):
+ raise RuntimeError(
+ "Edge TTS word boundaries crossed subtitle split points; "
+ "subtitle timing was not generated"
+ )
+ if not pending:
+ raise RuntimeError("Edge TTS produced no timed subtitle cues")
+
+ cues: list[_SubtitleCue] = []
+ for index, (start, word_end, cue_text) in enumerate(pending):
+ next_start = pending[index + 1][0] if index + 1 < len(pending) else None
+ end = next_start if next_start is not None and next_start > word_end else word_end
+ cues.append(_SubtitleCue(start=start, end=end, text=cue_text))
+
+ source_text = re.sub(r"\s+", "", text)
+ subtitle_text = re.sub(r"\s+", "", "".join(cue.text for cue in cues))
+ if subtitle_text != source_text:
+ raise RuntimeError(
+ "Generated subtitle text does not match the narration text; "
+ "audio and subtitles were not published"
+ )
+ if any(_display_length(cue.text, 0, len(cue.text)) > max_chars for cue in cues):
+ raise RuntimeError(
+ "A single Edge TTS word boundary exceeds the subtitle character limit; "
+ "audio and subtitles were not published"
+ )
+ if any(cue.end <= cue.start for cue in cues):
+ raise RuntimeError(
+ "Edge TTS returned an invalid subtitle timing interval; "
+ "audio and subtitles were not published"
+ )
+ return cues
+
+
+def _srt_timestamp(ticks: int) -> str:
+ total_milliseconds = round(ticks / 10_000)
+ hours, remainder = divmod(total_milliseconds, 3_600_000)
+ minutes, remainder = divmod(remainder, 60_000)
+ seconds, milliseconds = divmod(remainder, 1_000)
+ return f"{hours:02d}:{minutes:02d}:{seconds:02d},{milliseconds:03d}"
+
+
+def _format_srt(cues: list[_SubtitleCue]) -> str:
+ blocks = [
+ (
+ f"{index}\n"
+ f"{_srt_timestamp(cue.start)} --> {_srt_timestamp(cue.end)}\n"
+ f"{cue.text}"
+ )
+ for index, cue in enumerate(cues, 1)
+ ]
+ return "\n\n".join(blocks) + "\n"
+
+
+async def _generate_with_subtitles(
+ text: str,
+ output_path: Path,
+ subtitle_path: Path,
+ *,
+ voice: str,
+ rate: str,
+ max_chars: int,
+) -> None:
+ """Generate one MP3 and compact SRT from the same Edge word-timing stream."""
+ try:
+ import edge_tts
+ except ImportError as exc:
+ raise RuntimeError(
+ "Missing dependency `edge-tts`. Install it with: "
+ "python3 -m pip install edge-tts"
+ ) from exc
+
+ communicate = edge_tts.Communicate(
+ text,
+ voice=voice,
+ rate=normalize_rate(rate),
+ boundary="WordBoundary",
+ )
+ audio_descriptor = -1
+ subtitle_descriptor = -1
+ staged_audio: Path | None = None
+ staged_subtitle: Path | None = None
+ boundaries: list[dict] = []
+ received_audio = False
+ try:
+ audio_descriptor, staged_audio = _temporary_path(output_path, ".tmp")
+ subtitle_descriptor, staged_subtitle = _temporary_path(subtitle_path, ".tmp")
+
+ audio_stream = os.fdopen(audio_descriptor, "wb")
+ audio_descriptor = -1
+ with audio_stream:
+ async for chunk in communicate.stream():
+ if chunk["type"] == "audio":
+ audio_stream.write(chunk["data"])
+ received_audio = True
+ elif chunk["type"] == "WordBoundary":
+ boundaries.append(chunk)
+ audio_stream.flush()
+ os.fsync(audio_stream.fileno())
+
+ if not received_audio:
+ raise RuntimeError("Edge TTS returned no audio data")
+ if not boundaries:
+ raise RuntimeError("Edge TTS returned no word-boundary timing")
+ subtitle_text = _format_srt(_subtitle_cues(text, boundaries, max_chars))
+
+ subtitle_stream = os.fdopen(
+ subtitle_descriptor,
+ "w",
+ encoding="utf-8",
+ newline="\n",
+ )
+ subtitle_descriptor = -1
+ with subtitle_stream:
+ subtitle_stream.write(subtitle_text)
+ subtitle_stream.flush()
+ os.fsync(subtitle_stream.fileno())
+ assert staged_audio is not None
+ assert staged_subtitle is not None
+ _publish_pair(
+ staged_audio,
+ output_path,
+ staged_subtitle,
+ subtitle_path,
+ )
+ finally:
+ if audio_descriptor >= 0:
+ os.close(audio_descriptor)
+ if subtitle_descriptor >= 0:
+ os.close(subtitle_descriptor)
+ if staged_audio is not None:
+ staged_audio.unlink(missing_ok=True)
+ if staged_subtitle is not None:
+ staged_subtitle.unlink(missing_ok=True)
+
+
def print_common_voices() -> None:
print("Common edge-tts voices:")
print("Locale Voice Notes")
diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.md
index f625a171..59357388 100644
--- a/skills/ppt-master/workflows/stages/generate-audio.md
+++ b/skills/ppt-master/workflows/stages/generate-audio.md
@@ -4,7 +4,7 @@ description: Shared post-processing stage for per-slide narration audio and opti
# Generate Audio Stage
-> Shared narration stage. Run from the Generate PPTX route after notes/export readiness, or from the Enhance Native PPTX narration module after its notes step. Produces one audio file per slide via `edge-tts` by default, or a cloud TTS provider (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) when the user chooses high-quality narration or a cloned voice. The caller owns final PPTX integration.
+> Shared narration stage. Run from the Generate PPTX route after notes/export readiness, or from the Enhance Native PPTX narration module after its notes step. By default, `edge-tts` produces one audio/SRT pair per slide from the same streaming request. Cloud TTS providers (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`) currently produce audio only. The caller owns final PPTX integration.
This stage is **context-independent**: it reads `notes/*.md` and queries the selected TTS voice catalog, so either owning route may invoke it in a fresh session. It does not choose the top-level route and does not patch slide design.
@@ -12,7 +12,7 @@ This stage is **context-independent**: it reads `notes/*.md` and queries the sel
- 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: one notes file 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, one notes file becomes `audio/<stem>.mp3` plus `notes/subtitles/<stem>.srt`; with a cloud provider, it becomes one audio file. Do not use a single long audio track or attempt automatic long-audio splitting.
- PPT narration assets must be PowerPoint-reliable audio: `m4a` (AAC), `mp3`, or `wav`. The built-in TTS path defaults to `mp3`; provider formats such as `pcm`, `opus`, or `flac` must be transcoded before embedding.
- PowerPoint recorded narration export requires `ffprobe` so slide timings can be written from actual audio duration.
- High-quality cloud mode: provider API key is set before use:
@@ -142,22 +142,62 @@ python3 skills/ppt-master/scripts/notes_to_audio.py <project_path> \
--provider cosyvoice --voice-id <chosen-voice> \
--cosyvoice-model cosyvoice-v3-flash
-# 2A. Generate PPTX caller only: re-export with audio embedded
+# 2A. Generate PPTX caller with Edge SRT: rebuild click-free object timings
+python3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \
+ --narration-padding 0.5 --force
+
+# 2B. Re-export with audio embedded
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
- --recorded-narration audio
+ --no-merge --recorded-narration audio --narration-padding 0.5
+
+# 2C. Merge page-local SRT against timing values read from the final PPTX
+python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \
+ --pptx <final_narrated_pptx> --force
```
If `notes_to_audio.py` errors with a missing dependency or missing provider API key, fix the prerequisite and re-run — do NOT swallow the error.
+The edge command writes each MP3 and its SRT from the same `edge-tts` stream. SRT cues use the stream's `WordBoundary` timing: sentence-ending punctuation always closes a cue; text over the default 20-character limit first splits at commas, semicolons, or colons, then at the nearest word boundary only when still too long. Each SRT uses a page-local timeline whose origin is `00:00:00,000`, including any leading silence before the first cue. Override the limit with `--subtitle-max-chars`. Cloud-provider commands currently write audio only.
+
+**Generate PPTX narration timing plan**: before `narration_sync.py animations`, compare every current SVG content group with that page's SRT and write `<project_path>/narration_timing.json`. Pin the plan to the ordered page-local SRT set with `srt_sha256`, and record the same `narration_padding` that the later PPTX export will use. Each slide contains one ordered `groups` list. Set `cue` to the matching 1-based SRT cue number; omit `cue` when the group has no spoken counterpart. The list must cover every non-static content group exactly once. The sync command rejects a stale SRT fingerprint, then rebuilds `animations.json` from scratch with `after-previous` timing; it does not migrate legacy narration fields. Matched groups wait for their cue, while unmatched groups follow the preceding animation with the page rhythm's normal stagger.
+
+Get the exact fingerprint value with:
+
+```bash
+python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path>
+```
+
+```json
+{
+ "version": 1,
+ "srt_sha256": "<sha256 of the ordered page-local SRT set>",
+ "narration_padding": 0.5,
+ "slides": {
+ "01_title": {
+ "groups": [
+ { "id": "page-title", "cue": 1 },
+ { "id": "supporting-visual" }
+ ]
+ }
+ }
+}
+```
+
+After the narrated PPTX is exported, `narration_sync.py subtitles` reads the actual presentation relationship order plus integer `advTm` and transition duration from every slide, then writes `<project_path>/notes/subtitles/total.srt`. Relative `--pptx` paths are project-relative. This keeps the deck-wide SRT aligned with PowerPoint's native video timeline, including page transitions and narration padding.
+
+This stage keeps subtitles as external SRT files. It does not embed subtitles into PPTX or export MP4 directly.
+
**Caller integration**:
| Caller | After audio generation |
|---|---|
-| Generate PPTX | When embedding was confirmed, run `svg_to_pptx.py --recorded-narration audio` as shown above |
+| Generate PPTX | With Edge SRT, rebuild animations, export with `--recorded-narration audio`, then merge `total.srt` from the final PPTX as shown above |
| 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 |
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 audio duration plus padding. The re-export is saved as `exports/<project_name>_<timestamp>_narrated.pptx`, telling it apart from silent exports.
+**Narrated SVG export**: keep `--no-merge` on the final synchronized export. Separate SVG line frames preserve authored coordinates; default paragraph merging can make PowerPoint recalculate multiline text geometry and introduce visible offsets.
+
---
## Step 5: Completion report
@@ -165,6 +205,8 @@ For Generate PPTX, `--recorded-narration audio` prepares PowerPoint's recorded t
Output one summary block listing:
- Number of audio files generated and their location (`<project_path>/audio/*`).
+- For edge, number of matching page-local SRT files and their location (`<project_path>/notes/subtitles/*`).
+- For Generate PPTX with Edge SRT, rebuilt animation group count and merged SRT path (`<project_path>/notes/subtitles/total.srt`).
- 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`.