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.mdindex 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 embeddedpython3 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:```bashdiff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex 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 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg1. **备注本身就是为 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` 是必填项,可从账户中列出音色:```bashdiff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex 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.pynew file mode 100644index 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.pyindex 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 1generated += 1print(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 0diff --git a/skills/ppt-master/scripts/tts_backends/backend_edge.py b/skills/ppt-master/scripts/tts_backends/backend_edge.pyindex 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 osimport re+import tempfile+from dataclasses import dataclassfrom 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_ttsexcept ImportError as exc:@@ -56,6 +100,399 @@ async def generate(text: str, output_path: Path, *, voice: str, rate: str) -> Noawait 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.mdindex 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 embeddedpython3 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 tOutput 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`.