Snap per-segment audio bounds to whole cues so clips don't end mid-sentence

Audio slicing used each scene's [start_seconds, end_seconds) verbatim,
but scene-change timestamps rarely fall on sentence boundaries —
clips routinely cut mid-word at the start and mid-sentence at the end.

Add cue_bounds_per_segment in transcript.py: for each segment, return
the first-cue-start / last-cue-end of the cues align_segments already
bucketed into it. The orchestrator now extends each slice outward to
those bounds so the clip contains the full sentences whose text is
shown under the segment, falling back to the scene bounds when no cue
landed in the bucket.

app/pipeline/orchestrator.py

@@ -18,7 +18,7 @@ from .llm_extract import LLMToggles, extract_all, is_enabled as llm_enabled
 from .metadata import PageMetadata, SourceInfo, page_metadata_from_segments
 from .ocr import ocr_frame
 from .scenes import detect_and_extract, video_duration
-from .transcript import Cue, align_segments, parse_transcript
+from .transcript import Cue, align_segments, cue_bounds_per_segment, parse_transcript
 from .types import SceneFrame
 from .html_gen import Segment, build_segments
 
@@ -196,9 +196,22 @@ def run_pipeline(
         # Audio shares the static/ folder with frames so the published bundle
         # has one asset directory. The two namespaces don't collide because
         # frames are scene_*.jpg and clips are segment_*.mp3.
+        # Snap each clip's bounds outward to whole cues so it doesn't end
+        # mid-sentence — scene-change boundaries rarely align with sentence
+        # boundaries. Falls back to scene bounds for segments with no cues.
+        cue_bounds = cue_bounds_per_segment(cues, boundaries, full_duration)
+        audio_segments: list[tuple[int, float, float]] = []
+        for i, f in enumerate(kept):
+            cb = cue_bounds[i] if i < len(cue_bounds) else None
+            if cb is None:
+                audio_segments.append((i, f.start_seconds, f.end_seconds))
+            else:
+                audio_segments.append(
+                    (i, min(f.start_seconds, cb[0]), max(f.end_seconds, cb[1]))
+                )
         audio_paths = slice_segment_audio(
             inputs.video_path,
-            [(i, f.start_seconds, f.end_seconds) for i, f in enumerate(kept)],
+            audio_segments,
             inputs.frames_dir,
         )
         log.info("Sliced %d/%d narration audio clips", len(audio_paths), len(kept))

app/pipeline/transcript.py

@@ -121,14 +121,12 @@ def _group_into_paragraphs(
     return paragraphs
 
 
-def align_segments(
+def _bucket_cues(
     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.
+) -> list[list[Cue]]:
+    """Bucket cues into the segment whose [start, next_start) window
+    contains the cue's midpoint. Shared by align_segments (text) and
+    cue_bounds_per_segment (audio).
     """
     if not boundaries:
         return []
@@ -140,4 +138,35 @@ def align_segments(
             if edges[i] <= mid < edges[i + 1]:
                 buckets[i].append(cue)
                 break
-    return [_group_into_paragraphs(b) for b in buckets]
+    return buckets
+
+
+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

tests/test_transcript.py

@@ -1,4 +1,4 @@
-from app.pipeline.transcript import align_segments, parse_transcript
+from app.pipeline.transcript import align_segments, cue_bounds_per_segment, parse_transcript
 
 VTT_SAMPLE = """WEBVTT
 
@@ -145,3 +145,50 @@ def test_align_segments_breaks_on_length_at_sentence_boundary():
     paras = align_segments(cues, [0.0], total_duration=35.0)[0]
     # Expect at least two paragraphs once length threshold is exceeded.
     assert len(paras) >= 2
+
+
+def test_cue_bounds_snap_audio_outward_to_full_cues():
+    """Scene-change boundaries rarely align with sentence boundaries, so
+    slicing audio at exactly each segment's [start, end) cuts mid-sentence.
+    cue_bounds_per_segment returns the first-cue-start / last-cue-end of
+    the cues bucketed into each segment so the orchestrator can extend
+    the audio slice outward to whole cues. The first cue here straddles
+    segment 0's start and the last cue extends past segment 1's end —
+    both must be reflected in the bounds.
+    """
+    vtt = (
+        "WEBVTT\n\n"
+        "1\n00:00:09.000 --> 00:00:13.000\nFirst sentence crosses boundary.\n\n"
+        "2\n00:00:13.500 --> 00:00:18.000\nMiddle sentence in segment one.\n\n"
+        "3\n00:00:19.500 --> 00:00:22.500\nSecond segment opener.\n\n"
+        "4\n00:00:28.500 --> 00:00:33.000\nFinal sentence runs past end.\n"
+    )
+    cues = parse_transcript(vtt)
+    # Visual segment boundaries at 10 and 20; the last visual frame ends
+    # at 30 but the final cue extends to 33.
+    bounds = cue_bounds_per_segment(cues, [10.0, 20.0], total_duration=33.0)
+    assert len(bounds) == 2
+    assert bounds[0] is not None and bounds[1] is not None
+    # Segment 0 must cover from cue 1 start (9.0) to cue 2 end (18.0),
+    # i.e. extend backward past the segment start (10) to capture the
+    # word that began at 9.0 — that's the "mid-sentence cut" fix.
+    assert bounds[0][0] == 9.0
+    assert bounds[0][1] == 18.0
+    # Segment 1 must extend forward past the segment end (30) to 33.0
+    # so the trailing sentence isn't truncated.
+    assert bounds[1][0] == 19.5
+    assert bounds[1][1] == 33.0
+
+
+def test_cue_bounds_returns_none_for_segments_with_no_cues():
+    """When no cue's midpoint lands in a segment, the orchestrator must
+    fall back to the scene's own bounds; signal that with None.
+    """
+    vtt = (
+        "WEBVTT\n\n"
+        "1\n00:00:00.000 --> 00:00:05.000\nIntro.\n"
+    )
+    cues = parse_transcript(vtt)
+    bounds = cue_bounds_per_segment(cues, [0.0, 100.0], total_duration=200.0)
+    assert bounds[0] is not None
+    assert bounds[1] is None