@ossclip/core 0.1.0

package/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Ahsan Ayaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note (not part of the MIT grant above, which covers this repository's own
+code): rendering depends on Remotion, which is source-available under its own
+two-tier licence — see https://github.com/remotion-dev/remotion/blob/main/LICENSE.md.

package/README.md

@@ -0,0 +1,20 @@
+# @ossclip/core
+
+Part of [**ossclip**](https://github.com/AhsanAyaz/ossclip) — a local-first CLI that turns a talking-head take into a finished short: silence and filler words cut, word-timed kinetic captions, face-aware framing, and LLM-planned code-rendered on-screen graphics.
+
+This package is the framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer.
+
+It is published so the CLI can depend on it and so the pieces are reusable, but the supported entry point is the CLI:
+
+```sh
+npm install -g ossclip
+ossclip doctor
+```
+
+APIs here move between rounds — pin an exact version if you depend on them directly.
+
+**Documentation:** [github.com/AhsanAyaz/ossclip](https://github.com/AhsanAyaz/ossclip)
+
+## Licence
+
+MIT. Rendering depends on [Remotion](https://www.remotion.dev/), which carries [its own two-tier licence](https://github.com/remotion-dev/remotion/blob/main/LICENSE.md).

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ossclip/core",
+  "version": "0.1.0",
+  "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AhsanAyaz/ossclip.git",
+    "directory": "packages/core"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./browser": "./src/browser.ts"
+  },
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.115.0",
+    "zod": "^3.25.0"
+  },
+  "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
+  "bugs": {
+    "url": "https://github.com/AhsanAyaz/ossclip/issues"
+  },
+  "author": "Muhammad Ahsan Ayaz"
+}

package/src/analyze.ts

@@ -0,0 +1,299 @@
+import { run } from "./exec";
+import type { Analysis, Span, Transcript } from "./schema";
+
+/**
+ * Standalone interjections only. Deliberately excludes "like"/"you know"/"ah"/"oh":
+ * without an LLM adjudicating, false positives feel far worse than fillers.
+ */
+const FILLER_WORDS = new Set(["um", "uh", "uhm", "erm", "er", "hmm", "hm", "mmm", "mm", "mhm", "uh-huh"]);
+
+export function normalizeToken(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}-]+$/gu, "");
+}
+
+export interface SilenceDetectOptions {
+  ffmpegPath: string;
+  noiseDb?: number;
+  minDuration?: number;
+}
+
+export interface LevelStats {
+  /** Noise floor — 10th percentile of per-window RMS, dBFS. */
+  floorDb: number;
+  /** Speech level — 90th percentile of per-window RMS, dBFS. */
+  speechDb: number;
+  /** Silence threshold derived from the two, dBFS. */
+  thresholdDb: number;
+  /** Per-window RMS in dBFS, in order. */
+  windowsDb: number[];
+  /** Window length, seconds. */
+  windowSec: number;
+}
+
+/** Window length used for level measurement, seconds. */
+const WINDOW_SEC = 0.1;
+
+/**
+ * Typical level of a dB series — the MEDIAN window, not an energy average.
+ * Energy averaging is peak-dominated: one speech window straddling the edge of
+ * a 3 s silence drags its measured level from −51 dB to −26 dB and the region
+ * stops looking like dead air. The median ignores that single window.
+ */
+export function typicalLevelDb(windowsDb: readonly number[]): number {
+  if (windowsDb.length === 0) return Number.NEGATIVE_INFINITY;
+  const sorted = [...windowsDb].sort((a, b) => a - b);
+  return percentile(sorted, 0.5);
+}
+
+/** Typical level of [start, end) from a per-window dB series. */
+export function regionLevelDb(
+  windowsDb: readonly number[],
+  windowSec: number,
+  start: number,
+  end: number,
+): number {
+  const lo = Math.max(0, Math.floor(start / windowSec));
+  const hi = Math.min(windowsDb.length, Math.ceil(end / windowSec));
+  return typicalLevelDb(windowsDb.slice(lo, hi));
+}
+
+/** Widest and narrowest silence thresholds we'll ever derive, dBFS. */
+const THRESHOLD_FLOOR = -40;
+const THRESHOLD_CEIL = -20;
+/**
+ * How far below the speech level the threshold sits.
+ *
+ * Anchored to speech, NOT to the noise floor: a "silent" room is only quiet on
+ * average. Measured room tone in real footage averaged −49 dB but peaked at
+ * −28 dB, and silencedetect needs a *continuous* run below the threshold — so
+ * anything under about −27 dB broke a 3 s pause into 0.4 s fragments and the
+ * pause was never cut. The mean tells you nothing; the peaks decide.
+ */
+const SPEECH_DROP = 12;
+/** Never put the threshold within this much of the measured noise floor… */
+const FLOOR_HEADROOM = 6;
+/** …nor this close to the speech level, or speech itself reads as silence. */
+const SPEECH_HEADROOM = 8;
+
+export function deriveThreshold(floorDb: number, speechDb: number): number {
+  const bounded = Math.min(Math.max(speechDb - SPEECH_DROP, THRESHOLD_FLOOR), THRESHOLD_CEIL);
+  const lo = floorDb + FLOOR_HEADROOM;
+  const hi = speechDb - SPEECH_HEADROOM;
+  // Material with no dynamic range at all (near-silent or clipped throughout)
+  // leaves no valid window — the midpoint is the least-wrong answer.
+  if (lo > hi) return (floorDb + speechDb) / 2;
+  return Math.min(Math.max(bounded, lo), hi);
+}
+
+export function percentile(sorted: readonly number[], p: number): number {
+  if (sorted.length === 0) return Number.NaN;
+  return sorted[Math.min(sorted.length - 1, Math.max(0, Math.floor(p * (sorted.length - 1))))]!;
+}
+
+/**
+ * Measure the take's own noise floor and speech level, so the silence
+ * threshold tracks the recording instead of a hardcoded dB value. A hot
+ * lav mic and a quiet room condenser have floors 25 dB apart; one fixed
+ * threshold silently no-ops on the loud one.
+ */
+export async function measureLevels(opts: { ffmpegPath: string }, audioPath: string): Promise<LevelStats> {
+  // 1600 samples @ 16 kHz (the ASR wav rate) = 100 ms windows.
+  const { stdout, stderr } = await run(
+    opts.ffmpegPath,
+    [
+      "-hide_banner", "-nostats", "-i", audioPath,
+      "-af",
+      "asetnsamples=n=1600,astats=metadata=1:reset=1,ametadata=print:key=lavfi.astats.Overall.RMS_level:file=-",
+      "-f", "null", "-",
+    ],
+    { allowNonZero: true },
+  );
+  const values: number[] = [];
+  for (const line of `${stdout}\n${stderr}`.split("\n")) {
+    const m = line.match(/lavfi\.astats\.Overall\.RMS_level=(-?[\d.]+|-?inf)/);
+    if (!m) continue;
+    const v = Number(m[1]);
+    if (Number.isFinite(v)) values.push(v);
+  }
+  if (values.length === 0) {
+    // No usable measurement — fall back to the old fixed threshold.
+    return { floorDb: -60, speechDb: -20, thresholdDb: -35, windowsDb: [], windowSec: WINDOW_SEC };
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  const floorDb = percentile(sorted, 0.1);
+  const speechDb = percentile(sorted, 0.9);
+  return {
+    floorDb,
+    speechDb,
+    thresholdDb: deriveThreshold(floorDb, speechDb),
+    windowsDb: values,
+    windowSec: WINDOW_SEC,
+  };
+}
+
+/** Acoustic silences via ffmpeg silencedetect (parsed from stderr). */
+export async function detectSilences(opts: SilenceDetectOptions, audioPath: string): Promise<Span[]> {
+  const noise = opts.noiseDb ?? (await measureLevels(opts, audioPath)).thresholdDb;
+  const minDur = opts.minDuration ?? 0.35;
+  const { stderr } = await run(
+    opts.ffmpegPath,
+    ["-i", audioPath, "-af", `silencedetect=noise=${noise}dB:d=${minDur}`, "-f", "null", "-"],
+    { allowNonZero: true },
+  );
+  const silences: Span[] = [];
+  let pendingStart: number | null = null;
+  for (const line of stderr.split("\n")) {
+    const startMatch = line.match(/silence_start:\s*(-?[\d.]+)/);
+    if (startMatch) pendingStart = Math.max(0, Number(startMatch[1]));
+    const endMatch = line.match(/silence_end:\s*(-?[\d.]+)/);
+    if (endMatch && pendingStart !== null) {
+      silences.push({ start: pendingStart, end: Number(endMatch[1]) });
+      pendingStart = null;
+    }
+  }
+  if (pendingStart !== null) silences.push({ start: pendingStart, end: Number.POSITIVE_INFINITY });
+  return silences;
+}
+
+/** A cuttable region shorter than this isn't worth considering. */
+const MIN_CUTTABLE = 0.1;
+/**
+ * Mean level this far below speech is dead air, whatever the transcript claims.
+ * Quiet or off-mic speech still averages nearer the speech level than this.
+ */
+const DEAD_AIR_DROP = 25;
+
+/** Subtract `blockers` from `span`, returning the surviving pieces. */
+export function subtractSpans(span: Span, blockers: readonly Span[]): Span[] {
+  let pieces: Span[] = [{ ...span }];
+  for (const b of blockers) {
+    const next: Span[] = [];
+    for (const p of pieces) {
+      if (b.end <= p.start || b.start >= p.end) {
+        next.push(p);
+        continue;
+      }
+      if (b.start > p.start) next.push({ start: p.start, end: b.start });
+      if (b.end < p.end) next.push({ start: b.end, end: p.end });
+    }
+    pieces = next;
+  }
+  return pieces;
+}
+
+/**
+ * Acoustics decide what is cuttable; the transcript only vetoes.
+ *
+ * The previous rule ("cut only where a transcript gap and a silence agree")
+ * cannot fire on real whisper output: with `-ml 1` the word stamps are
+ * contiguous — each word's end IS the next word's start — so pauses are
+ * absorbed into word durations and the transcript reports no gap to agree
+ * with. Measured on a real 68 s take: 164/167 word boundaries contiguous,
+ * every detected silence landing *inside* a word, zero agreed pauses, zero
+ * cuts.
+ *
+ * Inverted rule: a region below the silence threshold contains no audible
+ * speech by definition, so it is cuttable. The transcript vetoes only the
+ * pathological case where a whole non-filler word is claimed to live inside
+ * that silence — a real signal conflict, where the safe move is to keep it.
+ *
+ * That veto is itself overridden when the region's MEAN energy is far below
+ * the speech level (`levels` supplied): whisper stamps words over dead air
+ * often enough that trusting it there would cancel obvious lead-in trims,
+ * while genuinely quiet speech still averages well above room tone.
+ */
+export function analyze(
+  transcript: Transcript,
+  silences: Span[],
+  duration: number,
+  levels?: Pick<LevelStats, "windowsDb" | "windowSec" | "speechDb">,
+): Analysis {
+  const words = transcript.words;
+  const gaps: Span[] = [];
+  if (words.length > 0) {
+    const first = words[0]!;
+    const last = words[words.length - 1]!;
+    if (first.start > 0) gaps.push({ start: 0, end: first.start });
+    for (let i = 0; i < words.length - 1; i++) {
+      const a = words[i]!;
+      const b = words[i + 1]!;
+      if (b.start > a.end) gaps.push({ start: a.end, end: b.start });
+    }
+    if (duration > last.end) gaps.push({ start: last.end, end: duration });
+  } else {
+    gaps.push({ start: 0, end: duration });
+  }
+
+  const bounded = silences.map((s) => ({ start: s.start, end: Math.min(s.end, duration) }));
+
+  const fillers = words.flatMap((w, wordIndex) => {
+    const norm = normalizeToken(w.text);
+    return FILLER_WORDS.has(norm) ? [{ wordIndex, text: w.text, start: w.start, end: w.end }] : [];
+  });
+  const fillerIndices = new Set(fillers.map((f) => f.wordIndex));
+
+  const cuttable: Span[] = [];
+  for (const sil of bounded) {
+    if (sil.end - sil.start < MIN_CUTTABLE) continue;
+    // Veto: a non-filler word wholly inside the silence means the two signals
+    // disagree about where speech is. Keep that word and cut around it…
+    let conflicts = words.filter(
+      (w, i) => !fillerIndices.has(i) && w.start >= sil.start && w.end <= sil.end && w.end > w.start,
+    );
+    // …unless the region is measurably dead air, in which case the transcript
+    // is the signal that's wrong.
+    if (conflicts.length > 0 && levels && levels.windowsDb.length > 0) {
+      const meanDb = regionLevelDb(levels.windowsDb, levels.windowSec, sil.start, sil.end);
+      if (meanDb <= levels.speechDb - DEAD_AIR_DROP) conflicts = [];
+    }
+    for (const piece of subtractSpans(sil, conflicts)) {
+      if (piece.end - piece.start >= MIN_CUTTABLE) cuttable.push(piece);
+    }
+  }
+  cuttable.sort((a, b) => a.start - b.start);
+
+  return { silences: bounded, gaps, cuttable, breaths: detectBreaths(levels, duration), fillers };
+}
+
+/** A dip must last at least this long to be a breath and not a plosive gap. */
+const MIN_BREATH_SEC = 0.12;
+/** Dips this quiet are pauses; the silencedetect threshold is stricter still. */
+const BREATH_DROP = 10;
+
+/**
+ * Sub-silence pauses — where a speaker draws breath between phrases.
+ *
+ * `silences` cannot serve this purpose: `silencedetect` runs with a 0.35 s
+ * minimum (see `detectSilences`), while real inter-phrase breaths are
+ * 120–300 ms. On the reference take that floor left 8 silences across 68 s,
+ * which is why anything driven off them degenerates to uniform pacing.
+ *
+ * The 100 ms RMS series is already measured for threshold derivation, so this
+ * costs no extra ffmpeg pass: a run of windows sitting `BREATH_DROP` below
+ * the take's own speech level is a pause, whatever the transcript claims.
+ * These are phrase boundaries the word stamps cannot provide — whisper `-ml 1`
+ * emits contiguous stamps, so inter-word gaps do not exist (PHASE0 "Signal
+ * fusion", FINDINGS §18).
+ */
+export function detectBreaths(
+  levels: Pick<LevelStats, "windowsDb" | "windowSec" | "speechDb"> | undefined,
+  duration: number,
+): Span[] {
+  if (!levels || levels.windowsDb.length === 0) return [];
+  const threshold = levels.speechDb - BREATH_DROP;
+  const breaths: Span[] = [];
+  let runStart: number | null = null;
+  for (let i = 0; i <= levels.windowsDb.length; i++) {
+    const quiet = i < levels.windowsDb.length && levels.windowsDb[i]! <= threshold;
+    if (quiet && runStart === null) runStart = i;
+    if (!quiet && runStart !== null) {
+      const start = runStart * levels.windowSec;
+      const end = Math.min(i * levels.windowSec, duration);
+      if (end - start >= MIN_BREATH_SEC) breaths.push({ start, end });
+      runStart = null;
+    }
+  }
+  return breaths;
+}

package/src/assemble.ts

@@ -0,0 +1,124 @@
+import type { Transcript } from "./schema";
+import type { Scene, SceneCue } from "./scene-schema";
+import { resolveSceneProps } from "./scene-registry";
+import type { TimeMap } from "./timemap";
+
+/** Scenes shorter than this on screen get extended; still shorter → dropped. */
+const MIN_SCENE_SEC = 1.2;
+const DROP_BELOW_SEC = 0.8;
+/**
+ * On a short take a 2s graphic reads as a flicker, and there is no later beat
+ * to make up for it — hold every surviving scene longer (FINDINGS §29).
+ */
+const SHORT_TAKE_SEC = 45;
+const SHORT_TAKE_MIN_SCENE_SEC = 3;
+/**
+ * A graphic punches in, makes its point, and hands the frame back to the
+ * speaker — it does not have to span the moment that motivated it. Keeps the
+ * §4.5 pattern-interrupt rhythm instead of 10s static cards (FINDINGS §3).
+ * Exported: the beat scheduler budgets coverage with this same number (§7).
+ */
+export const MAX_SCENE_SEC = 5;
+/**
+ * A lower third never TAKES the frame — the speaker stays full-bleed the
+ * whole time — so the pattern-interrupt argument behind MAX_SCENE_SEC does
+ * not apply and the punch-out at 5s was cutting cards off mid-sentence
+ * (R20 §95, seen on the first real landscape run). It holds through its
+ * whole moment instead, under this generous ceiling so a rambling moment
+ * still cannot pin one static card up for a minute.
+ */
+export const MAX_OVERLAY_SCENE_SEC = 15;
+
+/** The on-screen cap for a cue, by how much frame its layout takes. */
+const maxSceneSecFor = (layout: SceneCue["layout"]): number =>
+  layout === "lower-third" ? MAX_OVERLAY_SCENE_SEC : MAX_SCENE_SEC;
+/** Breathing room enforced between consecutive scenes. */
+const SCENE_GAP_SEC = 0.05;
+
+export interface AssembleResult {
+  cues: SceneCue[];
+  dropped: Array<{ id: string; reason: string }>;
+}
+
+/**
+ * Resolve word-anchored scenes into output-timed cues (PHASE1 §5):
+ * anchors → output time via the TimeMap (scenes whose words were cut are
+ * dropped), props resolved as defaults←props←overrides, then sorted,
+ * de-overlapped and given a minimum on-screen duration. Gaps are implicit
+ * full-bleed — the stage defaults to the talking head when no cue is active.
+ */
+export function assembleScenes(
+  scenes: readonly Scene[],
+  transcript: Transcript,
+  map: TimeMap,
+): AssembleResult {
+  const dropped: AssembleResult["dropped"] = [];
+  const resolved: SceneCue[] = [];
+
+  for (const scene of scenes) {
+    const words = transcript.words.slice(scene.anchor.startWord, scene.anchor.endWord + 1);
+    if (words.length === 0) {
+      dropped.push({ id: scene.id, reason: "anchor out of transcript range" });
+      continue;
+    }
+    const mapped = words
+      .map((w) => map.mapWord(w))
+      .filter((m): m is { start: number; end: number } => m !== null);
+    if (mapped.length === 0) {
+      dropped.push({ id: scene.id, reason: "anchor words were entirely cut" });
+      continue;
+    }
+    const props = resolveSceneProps(scene.component, scene.props, scene.overrides);
+    if (props === null) {
+      dropped.push({ id: scene.id, reason: `invalid props for ${scene.component}` });
+      continue;
+    }
+    resolved.push({
+      id: scene.id,
+      layout: scene.layout,
+      component: scene.component,
+      props,
+      startSec: Math.min(...mapped.map((m) => m.start)),
+      endSec: Math.max(...mapped.map((m) => m.end)),
+    });
+  }
+
+  resolved.sort((a, b) => a.startSec - b.startSec);
+
+  // Never let the floor eat the video: a 3s minimum is right on a 30s take and
+  // absurd on a 6s one, so it is also capped at a share of the runtime.
+  const minScene =
+    map.outputDuration < SHORT_TAKE_SEC
+      ? Math.max(MIN_SCENE_SEC, Math.min(SHORT_TAKE_MIN_SCENE_SEC, map.outputDuration * 0.15))
+      : MIN_SCENE_SEC;
+
+  // Scenes are exclusive — one stage state at a time.
+  const cues: SceneCue[] = [];
+  for (const cue of resolved) {
+    const prev = cues[cues.length - 1];
+    if (prev && cue.startSec < prev.endSec + SCENE_GAP_SEC) {
+      cue.startSec = prev.endSec + SCENE_GAP_SEC;
+    }
+    if (cue.endSec - cue.startSec < minScene) {
+      cue.endSec = cue.startSec + minScene;
+    }
+    cue.endSec = Math.min(cue.endSec, cue.startSec + maxSceneSecFor(cue.layout), map.outputDuration);
+    if (cue.endSec - cue.startSec < DROP_BELOW_SEC) {
+      dropped.push({ id: cue.id, reason: "too short after clamping" });
+      continue;
+    }
+    cues.push(cue);
+  }
+
+  // The min-duration extension above can re-introduce overlap with the NEXT
+  // cue's start; walk once more and trim forward.
+  for (let i = 0; i < cues.length - 1; i++) {
+    const cur = cues[i]!;
+    const next = cues[i + 1]!;
+    if (next.startSec < cur.endSec + SCENE_GAP_SEC) {
+      cur.endSec = Math.max(cur.startSec + DROP_BELOW_SEC, next.startSec - SCENE_GAP_SEC);
+    }
+  }
+
+  return { cues, dropped };
+}

package/src/browser.ts

@@ -0,0 +1,24 @@
+/**
+ * Browser-safe surface of @ossclip/core — everything the Remotion bundle may
+ * import AT RUNTIME. No node built-ins, no SDKs, no fs/child_process anywhere
+ * in this module graph (scene-schema + scene-registry + zod only); the rest of
+ * core is re-exported as types, which erase at compile time.
+ */
+export * from "./scene-schema";
+export * from "./scene-registry";
+export * from "./overrides";
+// The editor derives its plain takes with the SAME function the pipeline
+// uses — a copy would drift and the two timelines would disagree.
+export * from "./fill";
+export { ZOOM_MAX_SCALE, zoomScaleAt, type ZoomSegment } from "./zoom";
+// Pure geometry only — the ffmpeg/cache half lives in ./content-rect-detect
+// and must never enter the Remotion bundle.
+export {
+  contentRectAt,
+  cropFilter,
+  type ContentRect,
+  type ContentRectSegment,
+} from "./content-rect";
+export type { CaptionLine, CaptionWord } from "./captions";
+export type { KeptSpan } from "./timemap";
+export type { Probe, Production, RenderSettings, Segment, Transcript, Word } from "./schema";

package/src/captions.ts

@@ -0,0 +1,92 @@
+import type { Transcript, Word } from "./schema";
+import type { TimeMap } from "./timemap";
+
+/** Caption timing lives in OUTPUT time — captions never know about cuts. */
+export interface CaptionWord {
+  text: string;
+  start: number;
+  end: number;
+}
+
+export interface CaptionLine {
+  words: CaptionWord[];
+  start: number;
+  end: number;
+}
+
+export interface CaptionOptions {
+  maxWordsPerLine?: number;
+  maxLineDuration?: number;
+  /** A speech gap longer than this starts a fresh line. */
+  maxGap?: number;
+  /** How long a line lingers after its last word (clamped to the next line). */
+  hold?: number;
+  /**
+   * Output times a line must not span — scene-cue starts/ends. The caption
+   * anchor is resolved once per line from the layout at its start, so a line
+   * crossing a layout boundary would sit in the WRONG layout's band and can
+   * land on a card or the face (FINDINGS §6b). Lines flush at boundaries and
+   * their hold never extends past one.
+   */
+  breakpoints?: number[];
+}
+
+export function buildCaptionLines(
+  transcript: Transcript,
+  map: TimeMap,
+  opts: CaptionOptions = {},
+): CaptionLine[] {
+  const maxWords = opts.maxWordsPerLine ?? 3;
+  const maxDur = opts.maxLineDuration ?? 1.2;
+  const maxGap = opts.maxGap ?? 0.6;
+  const hold = opts.hold ?? 0.35;
+  const breakpoints = [...(opts.breakpoints ?? [])].sort((a, b) => a - b);
+
+  const mapped: CaptionWord[] = [];
+  for (const w of transcript.words) {
+    const m = map.mapWord(w as Word);
+    if (m) mapped.push({ text: w.text, start: m.start, end: m.end });
+  }
+
+  const lines: CaptionLine[] = [];
+  let current: CaptionWord[] = [];
+  const flush = () => {
+    if (current.length === 0) return;
+    lines.push({
+      words: current,
+      start: current[0]!.start,
+      end: current[current.length - 1]!.end,
+    });
+    current = [];
+  };
+
+  for (const w of mapped) {
+    const lineStart = current[0]?.start ?? w.start;
+    const prevEnd = current[current.length - 1]?.end;
+    const crossesBoundary =
+      current.length > 0 && breakpoints.some((b) => b > lineStart + 1e-6 && b <= w.start + 1e-6);
+    if (
+      current.length >= maxWords ||
+      w.end - lineStart > maxDur ||
+      (prevEnd !== undefined && w.start - prevEnd > maxGap) ||
+      crossesBoundary
+    ) {
+      flush();
+    }
+    current.push(w);
+  }
+  flush();
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const next = lines[i + 1];
+    const lastWordEnd = line.words[line.words.length - 1]!.end;
+    const boundary = breakpoints.find((b) => b > line.start + 1e-6);
+    let end = line.end + hold;
+    if (next) end = Math.min(end, next.start);
+    if (boundary !== undefined) end = Math.min(end, boundary);
+    // A single word physically spanning a boundary stays readable to its end.
+    line.end = Math.min(Math.max(end, lastWordEnd), map.outputDuration);
+  }
+  return lines;
+}