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

fix(narration): restore compact WordBoundary subtitles

hugohe3a3c96263abd4
diff --git a/skills/ppt-master/scripts/notes_to_audio.py b/skills/ppt-master/scripts/notes_to_audio.py
index e119aad9..f0bc1aa5 100644
--- a/skills/ppt-master/scripts/notes_to_audio.py
+++ b/skills/ppt-master/scripts/notes_to_audio.py
@@ -3,7 +3,7 @@
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 and
-also writes one sentence-timed SRT file per slide from the same TTS stream.
+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
@@ -112,10 +112,7 @@ def main() -> int:
"--subtitle-max-chars",
type=int,
default=backend_edge.DEFAULT_SUBTITLE_MAX_CHARS,
- help=(
- "deprecated compatibility option; ignored because Edge SentenceBoundary "
- "cues are preserved unchanged"
- ),
+ help="maximum visible characters per Edge subtitle cue (default: 20)",
)
parser.add_argument(
"--elevenlabs-api-key-env",
@@ -255,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")
diff --git a/skills/ppt-master/scripts/tts_backends/backend_edge.py b/skills/ppt-master/scripts/tts_backends/backend_edge.py
index 1f7e0a98..8f0e433f 100644
--- a/skills/ppt-master/scripts/tts_backends/backend_edge.py
+++ b/skills/ppt-master/scripts/tts_backends/backend_edge.py
@@ -9,9 +9,20 @@ from dataclasses import dataclass
from pathlib import Path
-# Kept for CLI compatibility. Edge sentence boundaries are no longer split by
-# a local character limit.
DEFAULT_SUBTITLE_MAX_CHARS = 20
+DEFAULT_BOUNDARY_OVERLAP_TOLERANCE_MS = 100
+_TICKS_PER_MILLISECOND = 10_000
+_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)
@@ -67,15 +78,15 @@ async def generate(
subtitle_path: Path | None = None,
subtitle_max_chars: int = DEFAULT_SUBTITLE_MAX_CHARS,
) -> None:
- """Generate narration audio and, when requested, its sentence-timed SRT."""
+ """Generate narration audio and, when requested, its compact SRT."""
if subtitle_path is not None:
- _ = subtitle_max_chars # Deprecated compatibility option; intentionally ignored.
await _generate_with_subtitles(
text,
output_path,
subtitle_path,
voice=voice,
rate=rate,
+ max_chars=subtitle_max_chars,
)
return
@@ -143,40 +154,255 @@ def _publish_pair(
backup.unlink(missing_ok=True)
-def _sentence_cues(text: str, boundaries: list[dict]) -> list[_SubtitleCue]:
- """Validate Edge sentence boundaries without re-segmenting them."""
- if not boundaries:
- raise RuntimeError("Edge TTS produced no sentence-boundary timing")
+def _text_key(text: str) -> str:
+ return "".join(character.casefold() for character in text if character.isalnum())
- cues: list[_SubtitleCue] = []
- for boundary in boundaries:
- cue_text = re.sub(r"\s+", " ", str(boundary.get("text", ""))).strip()
- try:
- start = int(boundary["offset"])
- duration = int(boundary["duration"])
- except (KeyError, TypeError, ValueError) as exc:
- raise RuntimeError(
- "Edge TTS returned an invalid sentence-boundary payload; "
- "audio and subtitles were not published"
- ) from exc
- if not cue_text or start < 0 or duration <= 0:
- raise RuntimeError(
- "Edge TTS returned an invalid subtitle timing interval; "
- "audio and subtitles were not published"
+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],
+ ),
)
- if cues and start < cues[-1].end:
+ 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 _clamp_small_overlaps(
+ cues: list[_SubtitleCue],
+ *,
+ tolerance_ms: int = DEFAULT_BOUNDARY_OVERLAP_TOLERANCE_MS,
+) -> list[_SubtitleCue]:
+ tolerance = tolerance_ms * _TICKS_PER_MILLISECOND
+ normalized: list[_SubtitleCue] = []
+ for cue in cues:
+ if normalized and cue.start < normalized[-1].end:
+ overlap = normalized[-1].end - cue.start
+ if overlap > tolerance:
+ overlap_ms = overlap / _TICKS_PER_MILLISECOND
+ raise RuntimeError(
+ f"Edge TTS returned {overlap_ms:g} ms of overlapping "
+ "word-boundary timing; audio and subtitles were not published"
+ )
+ cue = _SubtitleCue(
+ start=normalized[-1].end,
+ end=cue.end,
+ text=cue.text,
+ )
+ if cue.end <= cue.start:
raise RuntimeError(
- "Edge TTS returned overlapping sentence-boundary timing; "
+ "Edge TTS returned an invalid subtitle timing interval; "
"audio and subtitles were not published"
)
- cues.append(
- _SubtitleCue(
- start=start,
- end=start + duration,
- text=cue_text,
- )
+ normalized.append(cue)
+ return normalized
+
+
+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))
+ cues = _clamp_small_overlaps(cues)
source_text = re.sub(r"\s+", "", text)
subtitle_text = re.sub(r"\s+", "", "".join(cue.text for cue in cues))
@@ -185,6 +411,11 @@ def _sentence_cues(text: str, boundaries: list[dict]) -> list[_SubtitleCue]:
"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"
+ )
return cues
@@ -215,8 +446,9 @@ async def _generate_with_subtitles(
*,
voice: str,
rate: str,
+ max_chars: int,
) -> None:
- """Generate one MP3 and sentence-timed SRT from the same Edge stream."""
+ """Generate one MP3 and compact SRT from the same Edge word-timing stream."""
try:
import edge_tts
except ImportError as exc:
@@ -229,7 +461,7 @@ async def _generate_with_subtitles(
text,
voice=voice,
rate=normalize_rate(rate),
- boundary="SentenceBoundary",
+ boundary="WordBoundary",
)
audio_descriptor = -1
subtitle_descriptor = -1
@@ -248,7 +480,7 @@ async def _generate_with_subtitles(
if chunk["type"] == "audio":
audio_stream.write(chunk["data"])
received_audio = True
- elif chunk["type"] == "SentenceBoundary":
+ elif chunk["type"] == "WordBoundary":
boundaries.append(chunk)
audio_stream.flush()
os.fsync(audio_stream.fileno())
@@ -256,8 +488,8 @@ async def _generate_with_subtitles(
if not received_audio:
raise RuntimeError("Edge TTS returned no audio data")
if not boundaries:
- raise RuntimeError("Edge TTS returned no sentence-boundary timing")
- subtitle_text = _format_srt(_sentence_cues(text, 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,
@@ -316,4 +548,3 @@ async def print_voices(locale: str | None = None) -> None:
gender = voice.get("Gender", "")
friendly = voice.get("FriendlyName", "")
print(f"{voice_locale:<8} {short_name:<34} {gender:<8} {friendly}")
-