@ossclip/core 0.1.24 → 0.1.25

package/src/normalize.ts

@@ -1,6 +1,4 @@
-import { rename, rm } from "node:fs/promises";
-import { run } from "./exec";
-import type { ContentRectSegment } from "./content-rect";
+import { MIN_FRAMING_CLASS_FRAC, type ContentRectSegment } from "./content-rect";
 import type { WindowFace } from "./face";
 
 /**
@@ -14,21 +12,29 @@ import type { WindowFace } from "./face";
  * Smoothing the boundaries cannot fix that; the output would still alternate
  * between two shots.
  *
- * The fix is editorial, applied at bake time: pick ONE field of view — the
- * tightest the source ever shows, i.e. the strip, since the strip's pixels
- * are all those stretches have — and crop every other segment down to a
- * window of that same shape, placed on the measured face. The result is a
- * single, uniform landscape source with constant apparent framing, and the
- * ENTIRE downstream pipeline (face bias, source-text, cover, layouts, zoom)
- * runs its ordinary uniform-source path on it. Tight but stable, by choice.
+ * The fix is editorial: pick ONE field of view — the tightest the source ever
+ * shows, i.e. the strip, since the strip's pixels are all those stretches
+ * have — and crop every other segment down to a window of that same shape,
+ * placed on the measured face. One consistent apparent framing, by choice.
+ *
+ * The plan used to be BAKED into a re-encoded file. That ended with the
+ * 2026-08-16 incident: an over-eager plan destroyed 55% of a screen
+ * recording's picture and the only undo was deleting the baked mp4 — the
+ * editor could not even see the crop had happened. The plan is now emitted
+ * into render-props.json as `framingTimeline` and applied at render time as a
+ * transform (packages/scenes/src/content-crop.ts), fully visible to and
+ * counteractable from the editor. The plan's GEOMETRY is unchanged by that
+ * move: every window shares one aspect, so per-segment render-time cover
+ * shows the same apparent framing on both sides of every boundary — the
+ * invariant the bake existed to enforce (144bbfb).
  *
  * When even the strip cannot cover the output frame without excessive
- * upscaling, normalization refuses (`ok: false`) and the caller falls back to
- * render-time FIT — the strip shown at its natural size rather than
- * fake-zoomed (option (b)).
+ * upscaling — or the plan would discard too much picture — normalization
+ * refuses (`ok: false`) and the caller falls back to render-time FIT — the
+ * strip shown at its natural size rather than fake-zoomed (option (b)).
  */
 
-/** One baked stretch: this window of the source, scaled to the canvas. */
+/** One planned stretch: this window of the source, covering the slot. */
 export interface NormalizeSegment {
   startSec: number;
   endSec: number;
@@ -53,6 +59,28 @@ export interface NormalizePlan {
    * soft fake is worse than an honest fit.
    */
   coverUpscale: number;
+  /**
+   * Duration-weighted mean of the picture area each window discards from its
+   * segment's rect (`1 - windowArea / rectArea`). The other half of the
+   * quality gate, and the number the refusal log reports: coverUpscale alone
+   * measured softness, never loss (2026-08-16 incident).
+   */
+  areaDiscardWeighted: number;
+  /**
+   * Per timeline segment, what the window is anchored on. "face" means the
+   * segment passed `segmentIsFaceOnly` and its window is sized and placed on
+   * the measured face; "screen" means the window is the segment's own rect,
+   * centered and clipped to the shared aspect — the picture, not the person,
+   * is the subject there (2026-08-16 incident: the PiP was not the subject).
+   */
+  subject: ("face" | "screen")[];
+  /**
+   * Per timeline segment, where the subject sits INSIDE its window, both axes
+   * in 0..1. For a face segment this is the measured face centre relative to
+   * the final window, so a render-time cover crop can keep the head where the
+   * plan put it; a screen segment's subject is the whole picture, so 0.5/0.5.
+   */
+  bias: { x: number; y: number }[];
   ok: boolean;
 }
 
@@ -64,6 +92,52 @@ export interface NormalizePlan {
  */
 export const MAX_NORMALIZE_UPSCALE = 2.6;
 
+/**
+ * Ceiling on the duration-weighted mean fraction of picture area a plan may
+ * throw away. coverUpscale 0.77 passed while 37% of the frame area was being
+ * thrown away — the gate measured softness, never loss (2026-08-16 incident).
+ */
+export const MAX_MEAN_AREA_DISCARD = 0.5;
+
+/**
+ * Ceiling on the picture area a SCREEN-subject segment's window may discard
+ * from its own rect. A screen segment's window is its rect clipped to the
+ * shared aspect — losing more than this means the shared aspect is genuinely
+ * fighting that segment's shape, and cropping screen content slides text and
+ * UI out of frame. Face segments are exempt: a face crop discards area by
+ * design. Applies to MATERIAL segments only, mirroring the aspect vote — a
+ * sliver class gets no vote on the aspect, so it cannot veto the plan for
+ * being clipped to it either (the 1.1% dark segment of the 2026-08-16
+ * incident loses ~16% to the shared aspect; the duration-weighted mean gate
+ * is what bounds slivers).
+ */
+export const MAX_SCREEN_AREA_DISCARD = 0.1;
+
+/**
+ * Smallest face (box height over segment-rect height) that makes a segment
+ * "just a face". Equals DEFAULT_FACE.sizeFrac (stage.ts): a face smaller than
+ * the assumed arm's-length selfie box is not the frame's subject. 2026-08-16
+ * incident: the camera PiP measured 0.119 and the crop chased it, discarding
+ * the screen content that WAS the subject; a real talking head measures 0.28+.
+ */
+export const FACE_ONLY_MIN_FRAC = 0.22;
+
+/**
+ * Below this fraction of sampled frames with a detection, the measurement is
+ * not confident enough to reframe on — a face seen in under half the looks is
+ * as likely a false positive or an occasional glance at a webcam.
+ */
+export const FACE_MIN_DETECTION_RATIO = 0.5;
+
+/**
+ * Extra breathing room, as a fraction of the window height, kept above the
+ * crown and below the chin when the window slides to contain the head. The
+ * user's rule (2026-08-16): the ENTIRE head including hair stays in frame,
+ * with ~1% of margin — touching the frame edge reads as a crop even when
+ * nothing is technically cut.
+ */
+export const HEAD_WINDOW_MARGIN = 0.01;
+
 /**
  * A head is about 1.55x the detector's face box tall — the box bounds eyes,
  * nose and mouth, and `stage.ts` models the crown at 0.35x above it and the
@@ -96,6 +170,25 @@ const median = (xs: number[]): number => {
   return s.length % 2 ? s[m]! : (s[m - 1]! + s[m]!) / 2;
 };
 
+/**
+ * Is this segment essentially JUST a face — the only case where a
+ * face-anchored reframe is allowed (user decision, 2026-08-16)?
+ *
+ * Classified on the representative `sizeFrac`, not `sizeFracMax`: a segment
+ * is face-only by what it looks like most of the time, not at its one biggest
+ * lean-in (sizing, once classified, still uses the max — see planNormalization).
+ * The detection ratio guards against reframing on a face the detector barely
+ * ever saw.
+ */
+export function segmentIsFaceOnly(face: WindowFace | null): boolean {
+  if (!face) return false;
+  if (face.sizeFrac < FACE_ONLY_MIN_FRAC) return false;
+  return (
+    face.framesSampled > 0 &&
+    face.framesDetected / face.framesSampled >= FACE_MIN_DETECTION_RATIO
+  );
+}
+
 /**
  * Decide the canvas and each segment's crop window.
  *
@@ -119,6 +212,12 @@ const median = (xs: number[]): number => {
  * zoom out as far as its own rect — clamping there rather than inventing
  * pixels. The median (not the max) is what keeps that clamping rare and the
  * upscale inside the quality gate.
+ *
+ * All of that applies ONLY to segments that are essentially just a face
+ * (`segmentIsFaceOnly`). Anything else — a screen share, a face-and-screen
+ * mix, a PiP — keeps its whole rect, centered and clipped to the shared
+ * aspect: the 2026-08-16 incident chased a 0.119 PiP and cropped away the
+ * screen content that was the actual subject.
  */
 export function planNormalization(
   timeline: readonly ContentRectSegment[],
@@ -133,10 +232,22 @@ export function planNormalization(
       segments: [],
       faceFracOfCanvas: [],
       coverUpscale: Infinity,
+      // Nothing was planned, so nothing was discarded; `ok: false` is the
+      // refusal signal, not this number.
+      areaDiscardWeighted: 0,
+      subject: [],
+      bias: [],
       ok: false,
     };
   }
 
+  // Face-anchored sizing and placement ONLY where the frame is essentially
+  // just a face (user decision, 2026-08-16). Everything else is a "screen"
+  // subject: its window is its own rect, centered and clipped to the shared
+  // aspect — the incident's PiP (sizeFrac 0.119) must never drag the crop
+  // to the bottom-right corner of a screen recording again.
+  const faceOnly = timeline.map((_, i) => segmentIsFaceOnly(faces[i] ?? null));
+
   /**
    * The LARGEST face fraction in each segment, not the median. A window sized
    * on the median is correct only at the median moment: the author's clip
@@ -144,39 +255,60 @@ export function planNormalization(
    * the frame edge whenever they leaned in — which is precisely the frame they
    * flagged. Sizing on the maximum makes the tightest moment the safe one and
    * every other moment merely roomier.
+   *
+   * Only FACE-ONLY segments contribute a measurement: a PiP-sized face must
+   * not drag the target down for the real talking heads (2026-08-16 incident).
    */
-  const measured = timeline.map((_, i) => faces[i]?.sizeFracMax ?? faces[i]?.sizeFrac ?? null);
+  const measured = timeline.map((_, i) =>
+    faceOnly[i] ? (faces[i]!.sizeFracMax ?? faces[i]!.sizeFrac) : null,
+  );
   const known = measured.filter((v): v is number => v !== null);
 
   // ---- Window heights ------------------------------------------------------
-  // Without a single measurement there is no subject to hold constant, so the
-  // rect-shaped fallback stands: the tightest field of view, uniformly.
+  // Without a single face-only segment there is no subject to hold constant,
+  // and the whole plan degrades to rect-shaped windows: the tightest field of
+  // view, uniformly, with nothing anchored on a face.
   const target = known.length > 0 ? Math.min(median(known), MAX_FACE_FRACTION) : null;
-  const rectShapedHeights = (): number[] => {
-    const canvasRect = boxed.reduce((a, b) => (b.rect.h < a.rect.h ? b : a)).rect;
-    const a = canvasRect.w / canvasRect.h;
-    return timeline.map((s) => even(Math.min(s.rect.w, s.rect.h * a) / a));
-  };
-  const windowHeights =
-    target === null
-      ? rectShapedHeights()
-      : timeline.map((s, i) => {
-          // An unmeasured segment inherits the median fraction of the segments
-          // framed like it (same rect height), so it is sized in ITS OWN class
-          // rather than averaged across two different shots.
-          const sameClass = timeline.flatMap((o, j) =>
-            measured[j] !== null && Math.abs(o.rect.h - s.rect.h) <= 2 ? [measured[j]!] : [],
-          );
-          const frac = measured[i] ?? (sameClass.length > 0 ? median(sameClass) : median(known));
-          return even(clamp((frac * s.rect.h) / target, 16, s.rect.h));
-        });
+  const canvasRect = boxed.reduce((a, b) => (b.rect.h < a.rect.h ? b : a)).rect;
+  const canvasRectAspect = canvasRect.w / canvasRect.h;
+  /** The tallest window of the tightest rect's shape that fits in `s.rect`. */
+  const rectShapedHeight = (s: ContentRectSegment): number =>
+    even(Math.min(s.rect.w, s.rect.h * canvasRectAspect) / canvasRectAspect);
+  const windowHeights = timeline.map((s, i) =>
+    target === null || !faceOnly[i]
+      ? rectShapedHeight(s)
+      : even(clamp((measured[i]! * s.rect.h) / target, 16, s.rect.h)),
+  );
 
   // ---- Canvas --------------------------------------------------------------
-  // The widest aspect every window can actually hold. Wider than the output's
-  // own aspect leaves the stage some horizontal freedom for the face bias;
-  // narrower simply means the output crops height, which cover already does.
+  // The widest aspect every MATERIAL window can actually hold. Wider than the
+  // output's own aspect leaves the stage some horizontal freedom for the face
+  // bias; narrower simply means the output crops height, which cover already
+  // does.
+  //
+  // Material = the segment's framing class (same rect within 2px) totals at
+  // least
+  // MIN_FRAMING_CLASS_FRAC of the runtime — the constant content-rect's
+  // materiality filter uses, belt-and-braces with it. A sliver class still gets a
+  // window — the rect clamp below bounds it — it just gets no vote here: one
+  // 15.4s segment (1.1% of a 1435s take, rect 2848x2234) set canvas aspect
+  // 1.2748 for the whole video and baked away 28% of source width
+  // (2026-08-16 incident).
+  const totalDur = timeline.reduce((a, s) => a + Math.max(0, s.endSec - s.startSec), 0);
+  const classDur = timeline.map((s) =>
+    timeline.reduce(
+      (a, o) =>
+        Math.abs(o.rect.w - s.rect.w) <= 2 && Math.abs(o.rect.h - s.rect.h) <= 2
+          ? a + Math.max(0, o.endSec - o.startSec)
+          : a,
+      0,
+    ),
+  );
+  const material = classDur.map((d) => totalDur > 0 && d / totalDur >= MIN_FRAMING_CLASS_FRAC);
+  // If every class is a sliver there is no majority to defer to — all vote.
+  const votes = material.some(Boolean) ? material : material.map(() => true);
   const aspect = timeline.reduce(
-    (a, s, i) => Math.min(a, s.rect.w / windowHeights[i]!),
+    (a, s, i) => (votes[i] ? Math.min(a, s.rect.w / windowHeights[i]!) : a),
     Number.POSITIVE_INFINITY,
   );
   // The smallest window, so baking never upscales — the tightest segment sets
@@ -185,14 +317,16 @@ export function planNormalization(
   const canvas = { width: even(canvasHeight * aspect), height: canvasHeight };
 
   // ---- Face placement inside the window ------------------------------------
-  // Taken from the segments whose window IS their rect: their framing is the
-  // author's own and survives untouched, so it is the one to reproduce.
+  // Taken from the FACE-ONLY segments whose window IS their rect: their
+  // framing is the author's own and survives untouched, so it is the one to
+  // reproduce. Screen segments get no say — the incident's PiP at 0.88/0.76
+  // would anchor every window bottom-right.
   let wx = 0;
   let wy = 0;
   let weight = 0;
   timeline.forEach((seg, i) => {
     const f = faces[i];
-    if (!f || windowHeights[i]! < seg.rect.h - 2) return;
+    if (!f || !faceOnly[i] || windowHeights[i]! < seg.rect.h - 2) return;
     const dur = Math.max(1e-6, seg.endSec - seg.startSec);
     wx += f.centerXFrac * dur;
     wy += f.centerYFrac * dur;
@@ -205,31 +339,54 @@ export function planNormalization(
     const r = seg.rect;
     const wH = windowHeights[i]!;
     const wW = even(Math.min(r.w, wH * aspect));
-    const f = faces[i];
-    // Face position in source px; the rect centre when nothing was measured.
-    const faceX = r.x + (f ? f.centerXFrac : 0.5) * r.w;
-    const faceY = r.y + (f ? f.centerYFrac : 0.5) * r.h;
+
+    // Screen subject: no face math at all. The window is the segment's own
+    // rect clipped to the shared aspect, centered on BOTH axes — the picture
+    // is the subject, and a centered clip is the only placement that does not
+    // pick a corner of it to sacrifice (2026-08-16 incident).
+    if (!faceOnly[i]) {
+      return {
+        startSec: seg.startSec,
+        endSec: seg.endSec,
+        window: {
+          x: even(r.x + (r.w - wW) / 2),
+          y: even(r.y + (r.h - wH) / 2),
+          w: wW,
+          h: wH,
+        },
+      };
+    }
+
+    const f = faces[i]!;
+    // Face position in source px.
+    const faceX = r.x + f.centerXFrac * r.w;
+    const faceY = r.y + f.centerYFrac * r.h;
     const x = even(clamp(faceX - targetX * wW, r.x, r.x + r.w - wW));
 
     let y = clamp(faceY - targetY * wH, r.y, r.y + r.h - wH);
     // Then slide — never resize — so the whole HEAD is inside the window at
     // the segment's largest face, since the aesthetic anchor above is about
-    // where the face sits, and this is about not amputating it. Bounded by
-    // the rect: if the head genuinely runs past the source's own edge there
-    // is nothing to slide toward, and the clamp leaves it where it was.
-    if (f) {
-      const maxFace = (f.sizeFracMax ?? f.sizeFrac) * r.h;
-      const headTop = faceY - HEAD_ABOVE * maxFace;
-      const headBottom = faceY + HEAD_BELOW * maxFace;
-      if (headBottom - headTop <= wH) {
-        y = clamp(y, headBottom - wH, headTop);
-      } else {
-        // Head taller than the window: centre it, so what is lost is shared
-        // between crown and chin instead of taking the whole bite off one end.
-        y = (headTop + headBottom) / 2 - wH / 2;
-      }
-      y = clamp(y, r.y, r.y + r.h - wH);
+    // where the face sits, and this is about not amputating it. The margin is
+    // the user's ~1% rule (2026-08-16): the entire head including hair stays
+    // in frame with a hair of breathing room — a crown touching the edge
+    // reads as cropped. Bounded by the rect: if the head genuinely runs past
+    // the source's own edge there is nothing to slide toward, and the clamp
+    // leaves it where it was.
+    const maxFace = (f.sizeFracMax ?? f.sizeFrac) * r.h;
+    const headTop = faceY - HEAD_ABOVE * maxFace;
+    const headBottom = faceY + HEAD_BELOW * maxFace;
+    const margin = HEAD_WINDOW_MARGIN * wH;
+    if (headBottom - headTop + 2 * margin <= wH) {
+      y = clamp(y, headBottom + margin - wH, headTop - margin);
+    } else if (headBottom - headTop <= wH) {
+      // Head fits but its margin does not: keep the head, split the shortfall.
+      y = clamp(y, headBottom - wH, headTop);
+    } else {
+      // Head taller than the window: centre it, so what is lost is shared
+      // between crown and chin instead of taking the whole bite off one end.
+      y = (headTop + headBottom) / 2 - wH / 2;
     }
+    y = clamp(y, r.y, r.y + r.h - wH);
     return {
       startSec: seg.startSec,
       endSec: seg.endSec,
@@ -237,6 +394,23 @@ export function planNormalization(
     };
   });
 
+  const subject = timeline.map((_, i): "face" | "screen" => (faceOnly[i] ? "face" : "screen"));
+  // Where the subject sits inside its FINAL window (post-clamp, post-even):
+  // the render-time cover crop uses this to keep the head where the plan put
+  // it. Clamped to 0..1 because a rect-bounded window can leave the face
+  // centre outside it in the degenerate edge cases the clamps above allow.
+  const bias = timeline.map((seg, i) => {
+    if (!faceOnly[i]) return { x: 0.5, y: 0.5 };
+    const f = faces[i]!;
+    const w = segments[i]!.window;
+    const faceX = seg.rect.x + f.centerXFrac * seg.rect.w;
+    const faceY = seg.rect.y + f.centerYFrac * seg.rect.h;
+    return {
+      x: clamp(w.w > 0 ? (faceX - w.x) / w.w : 0.5, 0, 1),
+      y: clamp(w.h > 0 ? (faceY - w.y) / w.h : 0.5, 0, 1),
+    };
+  });
+
   // Cover the output with the canvas: for a canvas wider than the output's
   // aspect the height binds, otherwise the width does.
   const coverUpscale =
@@ -246,19 +420,54 @@ export function planNormalization(
 
   // What each segment actually achieved once its window is scaled to the
   // canvas — measured from the plan, never assumed to equal the target: a
-  // segment clamped at its own rect lands wherever its rect put it.
+  // segment clamped at its own rect lands wherever its rect put it. A screen
+  // segment reports 0: it has no face SUBJECT, and downstream framing advice
+  // (assessCueFraming, framing.ts) rightly skips zeros rather than warning
+  // about the head of a PiP nobody is framing on.
   const faceFracOfCanvas = timeline.map((seg, i) => {
     const frac = measured[i];
-    if (frac === null || frac === undefined) return target ?? 0;
+    if (frac === null || frac === undefined) return 0;
     return (frac * seg.rect.h) / segments[i]!.window.h;
   });
 
+  /** Picture area the window throws away from its segment's rect. */
+  const discardFrac = (i: number): number => {
+    const r = timeline[i]!.rect;
+    const w = segments[i]!.window;
+    return r.w * r.h > 0 ? 1 - (w.w * w.h) / (r.w * r.h) : 0;
+  };
+
+  // How much of each segment's picture the windows throw away, weighted by
+  // how long the viewer looks at it. coverUpscale 0.77 passed while 37% of
+  // the frame area was being thrown away — the gate measured softness, never
+  // loss (2026-08-16 incident).
+  const areaDiscardWeighted = timeline.reduce((acc, seg, i) => {
+    const dur = Math.max(0, seg.endSec - seg.startSec);
+    return acc + (totalDur > 0 ? dur / totalDur : 0) * discardFrac(i);
+  }, 0);
+
+  // Per-segment bound for SCREEN subjects: their window is meant to be
+  // (essentially) their whole rect, so a material screen segment losing more
+  // than MAX_SCREEN_AREA_DISCARD means the plan is cropping content nobody
+  // asked it to reframe — refuse and let render-time fit show it honestly.
+  // Face segments are exempt (a face crop discards area by design); sliver
+  // segments are exempt for the same reason they get no aspect vote.
+  const screenLossOk = timeline.every(
+    (_, i) => faceOnly[i] || !material[i] || discardFrac(i) <= MAX_SCREEN_AREA_DISCARD,
+  );
+
   return {
     canvas,
     segments,
     faceFracOfCanvas,
     coverUpscale,
-    ok: coverUpscale <= MAX_NORMALIZE_UPSCALE,
+    areaDiscardWeighted,
+    subject,
+    bias,
+    ok:
+      coverUpscale <= MAX_NORMALIZE_UPSCALE &&
+      areaDiscardWeighted <= MAX_MEAN_AREA_DISCARD &&
+      screenLossOk,
   };
 }
 
@@ -355,66 +564,3 @@ export function assessCueFraming(
   }
   return out;
 }
-
-/**
- * The ffmpeg filter graph baking the plan: each segment trimmed, cropped to
- * its window, scaled to the canvas, and the pieces concatenated back into one
- * continuous stream. The segment boundaries partition the source exactly, so
- * the output timeline equals the input's and the untouched audio stays in
- * sync.
- */
-export function normalizationFilterGraph(plan: NormalizePlan): string {
-  const parts = plan.segments.map((s, i) => {
-    const w = s.window;
-    return (
-      `[0:v]trim=start=${s.startSec.toFixed(3)}:end=${s.endSec.toFixed(3)},` +
-      `setpts=PTS-STARTPTS,crop=${w.w}:${w.h}:${w.x}:${w.y},` +
-      // setsar=1 is load-bearing, not tidiness (R27 §125). Every segment is
-      // scaled to the SAME canvas, but from a DIFFERENT crop, and ffmpeg
-      // derives a sample aspect from that ratio: a 946x1682 crop yields SAR
-      // 1683:1682 and a 932x1660 crop 1377:1376. `concat` requires identical
-      // SAR across inputs and aborts the whole bake when they disagree, so a
-      // take whose framing varies — exactly the take normalization exists
-      // for — failed to render at all.
-      `scale=${plan.canvas.width}:${plan.canvas.height},setsar=1[v${i}]`
-    );
-  });
-  const inputs = plan.segments.map((_, i) => `[v${i}]`).join("");
-  return `${parts.join(";")};${inputs}concat=n=${plan.segments.length}:v=1:a=0[v]`;
-}
-
-/**
- * Bake the normalized source. Encoded with the mezzanine's own settings
- * (dense keyframes) because it REPLACES the mezzanine — normalizing and then
- * re-encoding for seekability would be two generations of loss for nothing.
- */
-export async function bakeNormalizedSource(
-  tools: { ffmpegPath: string },
-  input: string,
-  plan: NormalizePlan,
-  outPath: string,
-): Promise<void> {
-  // Encode to a sibling temp path and rename only on success (R27 §125).
-  // ffmpeg writes the container header as it goes, so a bake that dies
-  // mid-graph leaves a file with no `moov` atom — and the cache upstream keys
-  // on EXISTENCE, so that corpse is then reused as a valid normalized source
-  // on every later run. The failure surfaces as "moov atom not found" from a
-  // step that never ran, and deleting the workdir is the only way out. Rename
-  // is atomic on a POSIX filesystem, so the cache can only ever see a file
-  // ffmpeg finished writing.
-  const partial = `${outPath}.partial.mp4`;
-  try {
-    await run(tools.ffmpegPath, [
-      "-y", "-i", input,
-      "-filter_complex", normalizationFilterGraph(plan),
-      "-map", "[v]", "-map", "0:a?",
-      "-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-g", "30", "-pix_fmt", "yuv420p",
-      "-c:a", "aac", "-b:a", "192k",
-      partial,
-    ]);
-    await rename(partial, outPath);
-  } catch (err) {
-    await rm(partial, { force: true });
-    throw err;
-  }
-}

package/src/producer/index.ts

@@ -25,6 +25,7 @@ import {
 export * from "./provider";
 export * from "./usage";
 export * from "./beats";
+export * from "./youtube";
 export * from "./scene-props";
 export * from "./repair";
 export { AnthropicProvider, DEFAULT_CLAUDE_MODEL } from "./anthropic";

package/src/producer/repair.ts

@@ -76,7 +76,11 @@ A correction must sound essentially identical to what was heard. If a span is no
 
 For each fix give the word-index span, the exact text you are replacing (\`heard\`), and the corrected text.`;
 
-export function buildRepairUserPrompt(transcript: Transcript, speaker?: string): string {
+export function buildRepairUserPrompt(
+  transcript: Transcript,
+  speaker?: string,
+  dictionary?: readonly string[],
+): string {
   const words = transcript.words.map((w, i) => `[${i}]${w.text}`).join(" ");
   return (
     (speaker
@@ -89,6 +93,13 @@ export function buildRepairUserPrompt(transcript: Transcript, speaker?: string):
         `About the speaker (use this to recognise names the recognizer mangled, ` +
         `never to introduce facts): ${speaker}\n\n`
       : "") +
+    (dictionary && dictionary.length > 0
+      ? // The user's dictionary (F4, 2026-08-16): same failure class as the
+        // speaker hint — "Jason" for JSON is a lookup once the model knows
+        // the term, a guess otherwise.
+        `Vouched terms the speaker uses — prefer these spellings when the ` +
+        `audio matches: ${dictionary.join(", ")}\n\n`
+      : "") +
     `Word-indexed transcript (indices refer to THIS list):\n${words}\n\n` +
     `Report only spans that are clearly mishearings.`
   );
@@ -171,6 +182,13 @@ export interface ApplyRepairsOptions {
    * phonetic gate. Everything else about it is still checked.
    */
   speaker?: string;
+  /**
+   * The user's dictionary (F4, 2026-08-16) — vouched the same way the
+   * speaker hint is: terms the user typed themselves join the vouched set,
+   * so a fully-vouched correction ("Jason" → "JSON") may pass the phonetic
+   * gate. Every other guard still applies.
+   */
+  dictionary?: readonly string[];
 }
 
 export function applyRepairs(
@@ -180,18 +198,23 @@ export function applyRepairs(
 ): { transcript: Transcript; applied: AppliedRepair[] } {
   const maxIndex = transcript.words.length - 1;
   /**
-   * Names the user vouched for via `--speaker`. A recognizer that turned
-   * "Ahsan" into the initialism "SM" produces a correction no phonetic
-   * measure will accept — and refusing it leaves the wrong name in the
-   * captions, which is the failure the hint exists to prevent. So a correction
-   * built ENTIRELY from words the user supplied is exempt from that one gate.
-   * Every other guard still applies, and the exemption can only ever
-   * substitute text the user typed themselves.
+   * Words the user vouched for — via `--speaker` and, since F4 (2026-08-16),
+   * via the dictionary. A recognizer that turned "Ahsan" into the initialism
+   * "SM" produces a correction no phonetic measure will accept — and refusing
+   * it leaves the wrong name in the captions, which is the failure the hint
+   * exists to prevent. So a correction built ENTIRELY from words the user
+   * supplied is exempt from that one gate. Every other guard still applies,
+   * and the exemption can only ever substitute text the user typed themselves.
    */
-  const speakerWords = new Set(norm(opts.speaker ?? "").split(" ").filter(Boolean));
-  const speakerVouched = (correction: string): boolean => {
+  const vouchedWords = new Set(
+    [
+      ...norm(opts.speaker ?? "").split(" "),
+      ...(opts.dictionary ?? []).flatMap((term) => norm(term).split(" ")),
+    ].filter(Boolean),
+  );
+  const userVouched = (correction: string): boolean => {
     const tokens = norm(correction).split(" ").filter(Boolean);
-    return tokens.length > 0 && tokens.every((t) => speakerWords.has(t));
+    return tokens.length > 0 && tokens.every((t) => vouchedWords.has(t));
   };
   const results: AppliedRepair[] = [];
   const accepted: Array<{ startWord: number; endWord: number; tokens: string[] }> = [];
@@ -285,7 +308,7 @@ export function applyRepairs(
       record(`"${r.correction}" is too different in length from "${actual}"`);
       continue;
     }
-    if (!soundsSimilar(actual, r.correction) && !speakerVouched(r.correction)) {
+    if (!soundsSimilar(actual, r.correction) && !userVouched(r.correction)) {
       // The gate that keeps this a repair pass and not a rewrite pass.
       record(`"${r.correction}" does not sound like "${actual}" — rewrite, not a repair`);
       continue;
@@ -340,7 +363,7 @@ export async function repairTranscript(
     try {
       const result = await provider.complete({
         system: REPAIR_SYSTEM,
-        user: buildRepairUserPrompt(transcript, opts.speaker),
+        user: buildRepairUserPrompt(transcript, opts.speaker, opts.dictionary),
         schema: TranscriptRepairSchema,
         schemaName: "transcript_repair",
         // EDITORIAL on purpose, despite looking mechanical. Measured on the real