Video2Guide / app /pipeline /transcript.py
Claude
fix: crash + data-loss bugs from the audit (transcript parsing, download headers)
4f70b55
Raw History Blame Contribute Delete
12.5 kB
"""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