"""Transcript parsing (VTT/SRT) and alignment to visual segments.""" from __future__ import annotations import re from dataclasses import dataclass from pathlib import Path @dataclass class Cue: start: float # seconds end: float text: str # One timestamp: [HH:]MM:SS.mmm — the hours group is optional because the # WebVTT spec permits the short mm:ss.ttt form (a lecture clip under an hour # is often exported that way). SRT always includes hours, so it still # matches. Comma or dot as the ms separator (SRT uses ',', VTT uses '.'). _TS_PART = r"(?:(\d{1,3}):)?(\d{1,2}):(\d{2})[.,](\d{3})" _TS = re.compile(_TS_PART + r"\s*-->\s*" + _TS_PART) def _ts_to_seconds(h: str | None, m: str, s: str, ms: str) -> float: return (int(h) if h else 0) * 3600 + int(m) * 60 + int(s) + int(ms) / 1000.0 def parse_transcript(source: str | Path) -> list[Cue]: """Parse VTT or SRT content. `source` may be a path or raw text.""" if isinstance(source, Path) or (isinstance(source, str) and "\n" not in source and Path(source).exists()): text = Path(source).read_text(encoding="utf-8-sig") else: text = source text = text.replace("\r\n", "\n").replace("\r", "\n") cues: list[Cue] = [] current_start: float | None = None current_end: float | None = None current_lines: list[str] = [] def flush() -> None: nonlocal current_start, current_end, current_lines if current_start is not None and current_lines: joined = " ".join(line.strip() for line in current_lines if line.strip()) joined = re.sub(r"<[^>]+>", "", joined).strip() if joined: cues.append(Cue(current_start, current_end or current_start, joined)) current_start = current_end = None current_lines = [] for line in text.split("\n"): match = _TS.search(line) if match: flush() h1, m1, s1, ms1, h2, m2, s2, ms2 = match.groups() current_start = _ts_to_seconds(h1, m1, s1, ms1) current_end = _ts_to_seconds(h2, m2, s2, ms2) current_lines = [] continue if not line.strip(): flush() continue if line.strip().upper() == "WEBVTT" or line.strip().startswith("NOTE"): continue if current_start is None and re.fullmatch(r"\d+", line.strip()): continue # SRT cue index if current_start is not None: current_lines.append(line) flush() cues.sort(key=lambda c: c.start) return cues _SPEAKER_PREFIX = re.compile(r"^[A-Z][A-Z0-9 .'-]{1,30}:\s") _SENTENCE_END = re.compile(r"[.!?][\"')\]]*$") _COMMON_ABBREVIATIONS = { "dr", "mr", "mrs", "ms", "prof", "sr", "jr", "st", "vs", "etc", "e.g", "i.e", "u.s", "u.k", } def _ends_sentence(text: str) -> bool: return bool(_SENTENCE_END.search(text.rstrip())) def _is_sentence_boundary(text: str, punct_index: int, after_closers: int) -> bool: ch = text[punct_index] if ch == ".": prev_ch = text[punct_index - 1] if punct_index > 0 else "" next_ch = text[after_closers] if after_closers < len(text) else "" if prev_ch.isdigit() and next_ch.isdigit(): return False prefix = text[:punct_index].rstrip() # A cue can start with the punctuation itself (e.g. text == ". Next"), # leaving an empty prefix; rsplit on "" returns [] and [-1] would # raise IndexError. No preceding token means no abbreviation to # exempt, so fall through to the generic boundary check. parts = prefix.rsplit(None, 1) token = parts[-1].lower() if parts else "" if token in _COMMON_ABBREVIATIONS: return False remainder = text[after_closers:] if not remainder: return True if not remainder[0].isspace(): return False stripped = remainder.lstrip() return not stripped or stripped[0].isupper() or stripped[0].isdigit() def _split_at_first_sentence_end(text: str) -> tuple[str, str] | None: """Split text after its first sentence terminator. Returns (first_sentence, remainder) or None if no terminator appears. Closing quotes/brackets immediately after the terminator stay with the sentence, matching _SENTENCE_END's idea of a completed sentence. """ closers = "\"')]" for i, ch in enumerate(text): if ch not in ".!?": continue end = i + 1 while end < len(text) and text[end] in closers: end += 1 if not _is_sentence_boundary(text, i, end): continue return text[:end].strip(), text[end:].strip() return None def _group_into_paragraphs( cues: list[Cue], *, gap_threshold: float = 1.5, max_chars: int = 450, ) -> list[str]: """Group consecutive cues into readable paragraphs. Breaks on (a) a noticeable gap between cues, (b) a speaker label starting the next cue, or (c) accumulated length once a sentence ends. """ if not cues: return [] paragraphs: list[str] = [] current: list[str] = [] current_chars = 0 prev_end: float | None = None def flush() -> None: nonlocal current, current_chars if current: paragraphs.append(" ".join(current).strip()) current = [] current_chars = 0 for cue in cues: gap = (cue.start - prev_end) if prev_end is not None else 0.0 speaker_change = bool(_SPEAKER_PREFIX.match(cue.text)) and current length_break = current_chars >= max_chars and current and _ends_sentence(current[-1]) gap_break = gap >= gap_threshold and current and _ends_sentence(current[-1]) if speaker_change or length_break or gap_break: flush() current.append(cue.text) current_chars += len(cue.text) + 1 prev_end = cue.end flush() return paragraphs def _bucket_cues( cues: list[Cue], boundaries: list[float], total_duration: float ) -> list[list[Cue]]: """Bucket cues into the segment whose [start, next_start) window contains the cue's midpoint, then stitch sentences across boundaries. Shared by align_segments (text) and cue_bounds_per_segment (audio) so both stay in sync. Cues with midpoints earlier than the first boundary spill into the first bucket rather than being silently dropped. That matters when the caller deselects the first topic in the topic-preview flow: without this spill, the opening narration would vanish because the new first boundary starts well after the transcript does. For the common case where a transcript begins at the same time as the first scene this is a no-op. """ if not boundaries: return [] edges = list(boundaries) + [max(total_duration, boundaries[-1] + 0.001)] buckets: list[list[Cue]] = [[] for _ in boundaries] last = len(boundaries) - 1 for cue in cues: mid = (cue.start + cue.end) / 2.0 if mid < edges[0]: buckets[0].append(cue) continue placed = False for i in range(len(boundaries)): # The last bucket has no upper bound: a trailing cue whose # midpoint lands at or past the computed tail edge (e.g. the # video's measured duration undershot the final cue's end) # would otherwise match no window and be silently dropped from # both narration text and sliced audio. Spill it into the last # segment instead — symmetric to the head spill above. if edges[i] <= mid and (i == last or mid < edges[i + 1]): buckets[i].append(cue) placed = True break if not placed: buckets[last].append(cue) _stitch_sentences_across_boundaries(buckets) return buckets # Cap on how many cues we'll absorb across a boundary to complete a # sentence. A real sentence rarely spans more than two cues; the cap # stops a malformed transcript (no terminal punctuation anywhere) from # pulling everything into the first segment. _MAX_SENTENCE_ABSORB_CUES = 3 def _stitch_sentences_across_boundaries(buckets: list[list[Cue]]) -> None: """In-place: when segment A ends mid-sentence, pull only the sentence completion from segment B's start back into A. Two strategies, in order of preference: 1. **Terminator split.** If the first sentence-ending cue in B (within _MAX_SENTENCE_ABSORB_CUES) contains the terminator mid-text, split that cue so the completion stays with A and the next sentence remains in B. Strongest signal — works on any punctuated transcript. 2. **Lowercase-continuation fallback.** When no terminator exists in range (common with Whisper auto-transcripts that omit periods), use casing as the boundary signal: a B-cue starting with a lower- case letter is almost certainly continuing A's sentence. Absorb consecutive lowercase-starting cues until we hit one starting with a capital (next sentence) or the cap. """ for i in range(len(buckets) - 1): a = buckets[i] b = buckets[i + 1] if not a or not b: continue prev_text = " ".join(c.text.strip() for c in a if c.text.strip()) if not prev_text or _ends_sentence(prev_text): continue scan_limit = min(len(b), _MAX_SENTENCE_ABSORB_CUES) # Strategy 1: find a cue containing a sentence terminator and split it. split_at: tuple[int, str, str] | None = None for j in range(scan_limit): split = _split_at_first_sentence_end(b[j].text.strip()) if split is not None: completion, remainder = split split_at = (j, completion, remainder) break if split_at is not None: terminator_idx, completion, remainder = split_at a.extend(b[:terminator_idx]) terminator = b[terminator_idx] a.append(Cue(terminator.start, terminator.end, completion)) if remainder: b[terminator_idx] = Cue(terminator.start, terminator.end, remainder) del b[:terminator_idx] else: del b[: terminator_idx + 1] continue # Strategy 2: lowercase-continuation fallback. first = b[0].text.strip() if not first or not first[0].islower(): # B already opens a new sentence (capitalised) — the # mid-sentence cut is on A's side and can't be fixed by # moving cues. Leave the buckets alone. continue absorb_through = 0 for j in range(1, scan_limit): text = b[j].text.strip() if not text or not text[0].islower(): break absorb_through = j else: # Every scanned B-cue starts lowercase — absorb the whole # in-range run as one continuous open sentence. Cap protects # against transcripts with no casing signal anywhere. absorb_through = scan_limit - 1 a.extend(b[: absorb_through + 1]) del b[: absorb_through + 1] def align_segments( cues: list[Cue], boundaries: list[float], total_duration: float ) -> list[list[str]]: """Assign cue text to each visual segment defined by `boundaries`. `boundaries` is an ascending list of segment-start timestamps (seconds). A cue belongs to the segment whose [start, next_start) window contains the cue's midpoint. Returns a list of paragraphs per segment. """ return [_group_into_paragraphs(b) for b in _bucket_cues(cues, boundaries, total_duration)] def cue_bounds_per_segment( cues: list[Cue], boundaries: list[float], total_duration: float ) -> list[tuple[float, float] | None]: """For each segment, return (first_cue_start, last_cue_end) of the cues bucketed into it, or None if no cues landed there. Used to snap per-segment audio slice bounds outward to whole cues so clips don't end mid-sentence — scene-change boundaries rarely align with sentence boundaries. """ out: list[tuple[float, float] | None] = [] for b in _bucket_cues(cues, boundaries, total_duration): if not b: out.append(None) else: out.append((b[0].start, b[-1].end)) return out