File size: 12,500 Bytes
b6f361a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
4f70b55
 
 
 
 
 
b6f361a
 
4f70b55
 
b6f361a
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f697ee6
 
169b4ab
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f697ee6
 
 
 
 
 
169b4ab
 
 
 
 
 
 
 
4f70b55
 
 
 
 
 
169b4ab
 
 
 
 
 
 
 
 
 
 
 
31770ae
 
 
 
 
 
 
 
 
 
 
 
 
 
169b4ab
 
31770ae
 
 
 
f697ee6
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
cae500e
f697ee6
cae500e
 
23524b2
 
 
f16b33f
 
 
 
 
 
 
 
b6f361a
 
 
 
f697ee6
4f70b55
b6f361a
 
f16b33f
 
 
4f70b55
b6f361a
4f70b55
 
 
 
 
 
 
f697ee6
4f70b55
b6f361a
4f70b55
 
23524b2
cae500e
 
 
23524b2
 
 
 
 
 
 
 
31770ae
 
 
39c2e46
 
 
 
 
 
 
 
 
 
 
 
 
23524b2
 
 
 
816dd45
 
31770ae
 
816dd45
31770ae
39c2e46
 
 
31770ae
39c2e46
31770ae
 
 
 
816dd45
39c2e46
 
 
 
 
 
 
 
 
 
 
816dd45
31770ae
39c2e46
 
 
 
 
 
 
 
 
 
 
 
 
31770ae
39c2e46
 
 
 
 
 
23524b2
 
cae500e
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
"""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