@ossclip/core 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossclip/core",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "ossclip's framework-free pipeline: schema, transcription, analysis, cutlist, captions, framing, and the LLM producer",
   "type": "module",
   "license": "MIT",

package/src/blooper.ts

@@ -0,0 +1,102 @@
+import { normalizeToken } from "./analyze";
+import { isSentenceStart } from "./clip";
+import type { Transcript } from "./schema";
+
+/**
+ * Blooper removal by SPOKEN MARKER (R27 §122).
+ *
+ * The ask is "drop the flubbed takes, not just the silences", and the general
+ * form of that is semantic: a model reading the transcript deciding which
+ * attempt was bad. The authoring roadmap flags exactly why that is expensive —
+ * `buildCutlist` is today a pure function of (raw transcript, analysis,
+ * duration, level), and a model in that path ends the guarantee that the same
+ * input and `--cleanup` always produce the same edit.
+ *
+ * A marker the speaker says OUT LOUD is the deterministic subset. It needs no
+ * judgement: the word is in the transcript or it is not. So this ships the
+ * useful half of the feature and leaves the guarantee intact — the semantic
+ * detector remains unbuilt, deliberately.
+ *
+ * The pattern, from the take that motivated it:
+ *
+ *     "That could be one of the cases where you can say"   flubbed attempt
+ *     "blooper."                                            marker
+ *     "That could be one of"                                flubbed again
+ *     "blooper."                                            marker
+ *     "That could be the exit condition."                   the good take
+ *
+ * The marker TERMINATES a bad attempt, so removal runs backwards from it to
+ * the start of the sentence it spoiled, and consecutive marked attempts
+ * collapse into one cut.
+ */
+
+/** A span of transcript to drop, in word indices (inclusive) and source seconds. */
+export interface BloopSpan {
+  startWord: number;
+  endWord: number;
+  startSec: number;
+  endSec: number;
+  /** How many marker words this span swallowed — 2+ means repeated attempts. */
+  markers: number;
+}
+
+/**
+ * Spans the speaker marked as bloopers.
+ *
+ * `marker` is matched with `normalizeToken`, the same normalizer the filler
+ * detector uses, so case and trailing punctuation do not matter — ASR writes
+ * the word as "blooper." with the period riding on it.
+ *
+ * Returns spans in transcript order, non-overlapping.
+ */
+export function findBloopSpans(transcript: Transcript, marker: string): BloopSpan[] {
+  const want = normalizeToken(marker);
+  if (!want) return [];
+  const words = transcript.words;
+  const isMarker = (i: number): boolean => normalizeToken(words[i]?.text ?? "") === want;
+
+  const spans: BloopSpan[] = [];
+  for (let i = 0; i < words.length; i++) {
+    if (!isMarker(i)) continue;
+
+    // Walk back over the attempt this marker spoiled, to the start of its
+    // sentence. The marker's own text usually ENDS a sentence ("blooper."), so
+    // the scan starts at the word before it.
+    let start = i;
+    while (start > 0 && !isSentenceStart(transcript, start)) start--;
+
+    // Consecutive attempts: if everything between the previous span's end and
+    // this attempt's start is already being dropped, merge rather than leave a
+    // one-word island of a sentence nobody finished.
+    const prev = spans[spans.length - 1];
+    let markers = 1;
+    if (prev && start <= prev.endWord + 1) {
+      spans.pop();
+      start = prev.startWord;
+      markers = prev.markers + 1;
+    }
+
+    spans.push({
+      startWord: start,
+      endWord: i,
+      startSec: words[start]!.start,
+      endSec: words[i]!.end,
+      markers,
+    });
+  }
+  return spans;
+}
+
+/**
+ * A one-line account per span, for `report.txt`. The cut report justifies every
+ * other removal; a cut this aggressive — whole sentences, not dead air — owes
+ * the user the words it took.
+ */
+export function formatBloopSpan(transcript: Transcript, span: BloopSpan): string {
+  const said = transcript.words
+    .slice(span.startWord, span.endWord + 1)
+    .map((w) => w.text)
+    .join(" ");
+  const attempts = span.markers > 1 ? ` (${span.markers} attempts)` : "";
+  return `"${said}"${attempts}`;
+}

package/src/clip.ts

@@ -33,9 +33,10 @@ export const CLIP_SNAP_TOLERANCE = 0.2;
 /** Word that closes a sentence — ASR punctuation rides on the word text. */
 const SENTENCE_END = /[.!?…]["'")\]»]*$/u;
 
-const isSentenceEnd = (t: Transcript, i: number): boolean =>
+/** Exported since R27 §122: the blooper cut walks back to a sentence start. */
+export const isSentenceEnd = (t: Transcript, i: number): boolean =>
   SENTENCE_END.test(t.words[i]?.text ?? "");
-const isSentenceStart = (t: Transcript, i: number): boolean =>
+export const isSentenceStart = (t: Transcript, i: number): boolean =>
   i === 0 || isSentenceEnd(t, i - 1);
 
 const durSec = (t: Transcript, start: number, end: number): number =>

package/src/config.ts

@@ -1,4 +1,4 @@
-import { readFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
@@ -41,6 +41,42 @@ const DEFAULTS: OssclipConfig = {
   model: "small.en",
 };
 
+/** Everything ossclip owns on disk lives under here: config.json, models/, bin/, .env. */
+export const CONFIG_DIR = join(homedir(), ".ossclip");
+
+export function configFilePath(baseDir: string = CONFIG_DIR): string {
+  return join(baseDir, "config.json");
+}
+
+/**
+ * Merge a patch into `~/.ossclip/config.json`, creating it if needed.
+ *
+ * Read-merge-write over the RAW file, not a loaded OssclipConfig: users
+ * hand-edit this file, and keys the patch doesn't touch (`pricing`,
+ * `speaker`, comments-by-convention like `_note`) must survive a
+ * `ossclip setup` run untouched.
+ */
+export function saveConfigPatch(patch: Partial<OssclipConfig>, baseDir: string = CONFIG_DIR): string {
+  const path = configFilePath(baseDir);
+  let existing: Record<string, unknown> = {};
+  try {
+    existing = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+  } catch {
+    // absent or unparseable — a fresh object; setup never destroys a broken
+    // file silently, so keep a .bak when the file existed but didn't parse
+    try {
+      const raw = readFileSync(path, "utf8");
+      writeFileSync(`${path}.bak`, raw);
+    } catch {
+      // truly absent — nothing to back up
+    }
+  }
+  mkdirSync(baseDir, { recursive: true });
+  const merged = { ...existing, ...patch };
+  writeFileSync(path, `${JSON.stringify(merged, null, 2)}\n`);
+  return path;
+}
+
 /**
  * Resolution order per key: env (OSSCLIP_FFMPEG, OSSCLIP_FFPROBE, OSSCLIP_WHISPER,
  * OSSCLIP_MODEL_DIR, OSSCLIP_MODEL, OSSCLIP_BROWSER) → ~/.ossclip/config.json → defaults.

package/src/content-rect.ts

@@ -96,6 +96,19 @@ export function stableContentRect(
   const whole: ContentRect = { x: 0, y: 0, w: width, h: height, full: true };
   if (rects.length === 0 || width <= 0 || height <= 0) return whole;
 
+  // A measurement that does not FIT the frame was taken in a different
+  // coordinate space than the one we are reconciling it against, so nothing it
+  // says can be trusted (R27 §119). This is how a portrait take read as
+  // landscape used to produce a "letterbox": cropdetect measured the rotated
+  // 2160x3840 frame, the caller believed 3840x2160, and clamping the union of
+  // the two orientations yielded a 2160x2160 square that was never on screen.
+  // Refuse, exactly as MIN_CONTENT_FRAC refuses an implausibly small rect —
+  // cropping on bad evidence is far worse than leaving bars alone.
+  const fits = rects.every(
+    (r) => r.x >= 0 && r.y >= 0 && r.x + r.w <= width && r.y + r.h <= height,
+  );
+  if (!fits) return whole;
+
   let left = Infinity;
   let top = Infinity;
   let right = -Infinity;

package/src/cutlist.ts

@@ -6,12 +6,23 @@ interface LevelPolicy {
   /** Resulting gap length after tightening. */
   tightenTo: number;
   removeFillers: boolean;
+  /**
+   * Run-up kept before the first word and after the last (R27 §127).
+   *
+   * Level-dependent, because "how hard should I cut" plainly covers the ends
+   * too, and a fixed 0.25/0.35 was the one thing `--cleanup aggressive` could
+   * not tighten. On a short that LOOPS, a third of a second of the speaker
+   * sitting there after the last word is a visible dead beat every time the
+   * video repeats — the reason this surfaced on a real render.
+   */
+  leadKeep: number;
+  tailKeep: number;
 }
 
 const POLICIES: Record<Exclude<CleanupLevel, "exact">, LevelPolicy> = {
-  light: { pauseMin: 1.2, tightenTo: 0.3, removeFillers: false },
-  standard: { pauseMin: 0.7, tightenTo: 0.22, removeFillers: true },
-  aggressive: { pauseMin: 0.5, tightenTo: 0.18, removeFillers: true },
+  light: { pauseMin: 1.2, tightenTo: 0.3, removeFillers: false, leadKeep: 0.35, tailKeep: 0.45 },
+  standard: { pauseMin: 0.7, tightenTo: 0.22, removeFillers: true, leadKeep: 0.25, tailKeep: 0.35 },
+  aggressive: { pauseMin: 0.5, tightenTo: 0.18, removeFillers: true, leadKeep: 0.12, tailKeep: 0.15 },
 };
 
 /** Dead air kept before the first word / after the last word. Exported for
@@ -49,10 +60,26 @@ export interface BuildCutlistArgs {
   analysis: Analysis;
   duration: number;
   level: CleanupLevel;
+  /**
+   * Spans the speaker marked as bloopers out loud (R27 §122), from
+   * `findBloopSpans`. Passed in rather than detected here so this stays a pure
+   * function of its arguments — and so `--blooper-marker` is the only thing
+   * that can put a `retake` cut in the timeline.
+   */
+  bloops?: readonly { startWord: number; endWord: number; startSec: number; endSec: number }[];
 }
 
-export function buildCutlist({ transcript, analysis, duration, level }: BuildCutlistArgs): Segment[] {
+export function buildCutlist({
+  transcript,
+  analysis,
+  duration,
+  level,
+  bloops,
+}: BuildCutlistArgs): Segment[] {
   const keepAll: Segment[] = [{ srcIn: 0, srcOut: duration, kind: "keep" }];
+  // `exact` means exact: it is the escape hatch for "touch nothing", and a
+  // blooper cut is still a cut. --blooper-marker with --cleanup exact is a
+  // contradiction, and the flag the user typed second does not get to win.
   if (level === "exact") return keepAll;
   const policy = POLICIES[level];
   const words = transcript.words;
@@ -62,17 +89,49 @@ export function buildCutlist({ transcript, analysis, duration, level }: BuildCut
 
   const removals: Removal[] = [];
 
+  // Marked bloopers, injected BEFORE the sort/merge below so they inherit the
+  // whole existing machine: merging with the silence that brackets the flub,
+  // MIN_KEEP sliver folding, and the partition emit. Source is "acoustic"
+  // because the boundaries are word stamps we chose deliberately — the
+  // protected-word pass must not push them back off the words they exist to
+  // remove.
+  for (const b of bloops ?? []) {
+    removals.push({
+      start: b.startSec,
+      end: b.endSec,
+      reason: "retake",
+      confidence: 1,
+      source: "acoustic",
+    });
+  }
+
   for (const pause of analysis.cuttable) {
-    const isLead = first !== undefined && pause.end <= first.start + 1e-6;
-    const isTail = last !== undefined && pause.start >= last.end - 1e-6;
+    // Lead and tail are decided by the SILENCE's position in the file, not by
+    // comparing it to a word stamp (R27 §127). Whisper's `-ml 1` stamps stretch
+    // to fill gaps: on a real take the first word was stamped 0.00–0.53 over
+    // silence that plainly starts at 0.00, so `pause.end <= first.start` was
+    // false and the opening dead air fell through to the interior rule — where
+    // it was under `pauseMin` and survived. The tail failed the same way, by a
+    // 0.07s overlap, leaving the speaker on screen looking down after the last
+    // word. Dead air touching either end of the file IS lead/tail, whatever the
+    // recognizer claims about where words begin.
+    const isLead = pause.start <= 1e-6;
+    const isTail = pause.end >= duration - 1e-6;
     if (isLead) {
-      // Trim dead air before the first word down to LEAD_KEEP (hook starts fast).
-      const end = Math.min(pause.end, (first?.start ?? pause.end) - LEAD_KEEP);
+      // Keep LEAD_KEEP of run-up before speech starts (hook starts fast).
+      // Measured back from the END of the silence — where speech actually
+      // begins — rather than from a word stamp that may cover the silence.
+      const speechStarts = first !== undefined ? Math.max(pause.end, first.start) : pause.end;
+      const end = Math.min(pause.end, speechStarts - policy.leadKeep);
       if (end - pause.start >= MIN_REMOVAL) {
         removals.push({ start: pause.start, end, reason: "silence", confidence: 0.95, source: "acoustic" });
       }
     } else if (isTail) {
-      const start = Math.max(pause.start, (last?.end ?? pause.start) + TAIL_KEEP);
+      // Same, mirrored: the take ends when the speech does, so keep TAIL_KEEP
+      // past the last word and drop everything after — including the pause the
+      // recognizer's final stamp bled into.
+      const speechEnds = last !== undefined ? Math.min(pause.start, last.end) : pause.start;
+      const start = Math.max(pause.start, speechEnds + policy.tailKeep);
       if (pause.end - start >= MIN_REMOVAL) {
         removals.push({ start, end: pause.end, reason: "silence", confidence: 0.95, source: "acoustic" });
       }

package/src/grounding.ts

@@ -88,7 +88,17 @@ function needsSupport(token: string): boolean {
 function stringsOf(value: unknown): string[] {
   if (typeof value === "string") return [value];
   if (Array.isArray(value)) return value.flatMap(stringsOf);
-  if (value && typeof value === "object") return Object.values(value).flatMap(stringsOf);
+  if (value && typeof value === "object") {
+    // A structured line carries its copy in `text`; its siblings are RENDERING
+    // DIRECTIVES, not words anyone reads (R27 §126). Walking every value made
+    // the check judge them as on-screen copy, so a StrikethroughReveal line
+    // `{text, struck, mark: "cross"}` was reported as inventing "cross" — and
+    // the take can never contain those tokens, so the warning was unfixable
+    // by construction. Two of the four warnings on a real render were this.
+    const text = (value as Record<string, unknown>).text;
+    if (typeof text === "string") return [text];
+    return Object.values(value).flatMap(stringsOf);
+  }
   return [];
 }
 

package/src/index.ts

@@ -11,6 +11,7 @@ export * from "./transcribe";
 export * from "./analyze";
 export * from "./cutlist";
 export * from "./clip";
+export * from "./blooper";
 export * from "./captions";
 export * from "./zoom";
 export * from "./grounding";

package/src/ingest.ts

@@ -6,6 +6,27 @@ export interface IngestTools {
   ffprobePath: string;
 }
 
+/**
+ * The stream's rotation, normalized to 0/90/180/270 (R27 §119).
+ *
+ * Two spellings, because containers disagree: a Display Matrix side-datum
+ * (modern ffprobe, and the only one a concatenated MP4 keeps) or the legacy
+ * `rotate` tag. ffprobe reports the matrix angle signed — -90 and 270 are the
+ * same quarter turn — so everything is folded into [0, 360).
+ */
+export function normalizeRotation(raw: number | string | undefined): number {
+  const n = typeof raw === "string" ? Number(raw) : raw;
+  if (n === undefined || !Number.isFinite(n)) return 0;
+  const deg = ((Math.round(n) % 360) + 360) % 360;
+  // Anything that is not a quarter turn cannot swap an axis; treat as upright.
+  return deg % 90 === 0 ? deg : 0;
+}
+
+/** A quarter turn exchanges the axes, so the DISPLAYED frame is w/h swapped. */
+export function rotationSwapsAxes(rotation: number): boolean {
+  return rotation === 90 || rotation === 270;
+}
+
 export async function probe(tools: IngestTools, path: string): Promise<Probe> {
   const { stdout } = await run(tools.ffprobePath, [
     "-v", "error",
@@ -21,6 +42,8 @@ export async function probe(tools: IngestTools, path: string): Promise<Probe> {
       height?: number;
       avg_frame_rate?: string;
       r_frame_rate?: string;
+      side_data_list?: Array<{ rotation?: number }>;
+      tags?: { rotate?: string };
     }>;
     format?: { duration?: string };
   };
@@ -31,12 +54,25 @@ export async function probe(tools: IngestTools, path: string): Promise<Probe> {
   const [num, den] = (rate ?? "30/1").split("/").map(Number);
   const duration = Number(info.format?.duration);
   if (!Number.isFinite(duration) || duration <= 0) throw new Error(`could not determine duration of ${path}`);
+  // `side_data_list` carries several kinds of datum (ambient viewing
+  // environment, content light level); only one of them has a rotation.
+  const matrix = video.side_data_list?.find((s) => typeof s.rotation === "number");
+  const rotation = normalizeRotation(matrix?.rotation ?? video.tags?.rotate);
+  const rawW = video.width ?? 0;
+  const rawH = video.height ?? 0;
+  // Report what is DISPLAYED. ffmpeg auto-rotates in the filter chain, so every
+  // measurement taken through it (cropdetect, face, the mezzanine) is already
+  // in this space; returning the raw stream size made the pipeline reconcile
+  // two orientations into a bogus square and "detect" a letterbox on a
+  // full-frame portrait take (R27 §119).
+  const swap = rotationSwapsAxes(rotation);
   return {
     duration,
-    width: video.width ?? 0,
-    height: video.height ?? 0,
+    width: swap ? rawH : rawW,
+    height: swap ? rawW : rawH,
     fps: den ? (num ?? 30) / den : 30,
     hasAudio: Boolean(audio),
+    ...(rotation !== 0 ? { rotation } : {}),
   };
 }
 

package/src/normalize.ts

@@ -1,3 +1,4 @@
+import { rename, rm } from "node:fs/promises";
 import { run } from "./exec";
 import type { ContentRectSegment } from "./content-rect";
 import type { WindowFace } from "./face";
@@ -368,7 +369,14 @@ export function normalizationFilterGraph(plan: NormalizePlan): string {
     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},` +
-      `scale=${plan.canvas.width}:${plan.canvas.height}[v${i}]`
+      // 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("");
@@ -386,12 +394,27 @@ export async function bakeNormalizedSource(
   plan: NormalizePlan,
   outPath: string,
 ): Promise<void> {
-  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",
-    outPath,
-  ]);
+  // 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/beats.ts

@@ -6,13 +6,39 @@ import { MAX_SCENE_SEC } from "../assemble";
 import { COVER_MAX_WORDS, coverHeadline } from "../cover";
 import type { LlmProvider } from "./provider";
 
+/**
+ * Free text from the model, capped rather than refused (R27 §123).
+ *
+ * The standing doctrine (§112) is that LLM output is untrusted input,
+ * "validated where the pipeline can still degrade instead of at the point
+ * where it can only die". A bare `.max(n)` is the second kind: on two of three
+ * real runs the editorial call came back with a 61-character `onScreenCopy`
+ * and the whole produce died at the Zod boundary — transcription, analysis and
+ * the cut all discarded over one character of a headline.
+ *
+ * `preprocess` keeps `maxLength: n` in the JSON schema the provider is handed,
+ * so the model is still ASKED for the limit; it just no longer costs a run
+ * when the model misses by a word. Truncation prefers the last word boundary,
+ * and adds no ellipsis — the prompt explicitly forbids one on cover text.
+ */
+export function cappedText(max: number): z.ZodType<string> {
+  return z.preprocess((v) => {
+    if (typeof v !== "string" || v.length <= max) return v;
+    const cut = v.slice(0, max);
+    const lastSpace = cut.lastIndexOf(" ");
+    // Only honour a word boundary that keeps most of the budget; a single very
+    // long word would otherwise collapse to nothing.
+    return (lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd();
+  }, z.string().max(max)) as z.ZodType<string>;
+}
+
 /** Call 1 — the editorial call (PHASE1 §4): moments, copy, component picks. */
 export const MomentSchema = z.object({
   startWord: z.number().int().nonnegative(),
   endWord: z.number().int().nonnegative(),
-  purpose: z.string().max(100),
+  purpose: cappedText(100),
   /** Short on-screen copy for this beat — the fallback TitleCard title. */
-  onScreenCopy: z.string().max(60),
+  onScreenCopy: cappedText(60),
   /** "none" = plain talking head with captions; otherwise a library component. */
   sceneKind: z.union([SceneComponentIdSchema, z.literal("none")]),
   /**
@@ -24,25 +50,30 @@ export const MomentSchema = z.object({
   layout: LayoutSchema.optional().describe(
     "stage layout for this scene; omit for the component default. NEVER a layout the framing brief marks UNAVAILABLE for these words",
   ),
-  rationale: z.string().max(120).optional(),
+  rationale: cappedText(120).optional(),
 });
 export type Moment = z.infer<typeof MomentSchema>;
 
 export const BeatSheetSchema = z.object({
-  hook: z.string().max(120),
+  hook: cappedText(120),
   /**
    * Banner text for the cover image (FINDINGS §31). Written here rather than
    * by a second LLM call, because the producer is already choosing the hook —
    * this is the same editorial judgement, shortened for a thumbnail.
    */
-  coverText: z
-    .string()
-    .max(60)
+  coverText: cappedText(60)
     .optional()
     .describe(
       `cover banner: at most ${COVER_MAX_WORDS} words, the hook compressed to a thumbnail headline`,
     ),
-  moments: z.array(MomentSchema).min(1).max(12),
+  /**
+   * Raised from 12 to 24 (§118): with the alternation policy above, a cap of
+   * 12 moments is a ceiling of ~6 graphics however long the take is. A 64s
+   * take enumerating five features needs seven graphic beats — hook, five
+   * features, payoff — and therefore ~14 moments to alternate between them.
+   * The cap was binding before the coverage budget ever was.
+   */
+  moments: z.array(MomentSchema).min(1).max(24),
 });
 export type BeatSheet = z.infer<typeof BeatSheetSchema>;
 
@@ -77,7 +108,8 @@ Virality grammar — follow these as hard policies:
 - Use contrast/negation beats (StrikethroughReveal, RuleCard with struck alternatives) when the speaker rejects an idea.
 - End with a payoff or takeaway moment.
 - A moment spans the FULL stretch of speech about its beat — typically 5-15 seconds — in transcript order, non-overlapping. The graphic stays on screen for the ENTIRE moment, so the word range must cover everything the graphic refers to: a stat card leaves when the speaker moves on, not before.
-- COVERAGE: graphics should be on screen for roughly 40-50% of the runtime. A graphic spends its whole moment against that budget, so be selective — give graphics to the moments where one genuinely earns the frame, and spread them evenly: never leave a stretch longer than ~10 seconds with no graphic.
+- COUNT: the user prompt states how many graphic moments this take should get. That number is a TARGET, not a maximum — hit it. Planning under it is the most common failure: a take that makes five distinct points and gets two graphics has been under-produced, whatever the coverage percentage says.
+- COVERAGE: graphics should be on screen for roughly 40-50% of the runtime. A graphic spends its whole moment against that budget, so when the target implies many graphics, make each moment SHORTER rather than dropping moments — more, tighter graphics beats fewer, longer ones. Spread them evenly: never leave a stretch longer than ~10 seconds with no graphic.
 - VARIETY: never the same component twice in a row, and prefer a component you have NOT used yet in this video — reuse a treatment only when the beat genuinely calls for it. A repeat reads as a template.
 - Keep the face LARGE: prefer StatCard/RuleCard/ScreenshotFrame (they sit under a big face) over TitleCard (face becomes a small bubble); use FlowDiagram/TerminalMock sparingly — they remove the face entirely and only earn that when the graphic IS the point.
 - The transcript is ASR output and may contain mishearings: an unfamiliar proper noun is more likely a mistranscription of a common phrase than a real entity — write on-screen copy with the common-sense reading, never a suspected mishearing.
@@ -117,11 +149,23 @@ export function buildBeatsUserPrompt(
   const menu = Object.entries(SCENE_REGISTRY)
     .map(([id, meta]) => `- ${id}: ${meta.whenToUse}`)
     .join("\n");
+  // §118: state the graphic COUNT explicitly. Everything else in this prompt
+  // describes what a good graphic is; nothing said how many to plan, and the
+  // coverage budget downstream only ever removes.
+  const enumerated = countEnumeratedBeats(transcript);
+  const target = graphicsTarget(clip?.targetSec ?? duration, enumerated);
+  const targetLine =
+    `Graphic moments to plan: ${target}` +
+    (enumerated > 0
+      ? ` — the speaker enumerates ${enumerated} points out loud, so each one earns its own graphic, plus a hook and a payoff.\n`
+      : ` (about one per ${SEC_PER_GRAPHIC}s of runtime). Plan this many unless the take genuinely cannot carry them.\n`);
   return (
     `Intent: ${intent ?? "make this clear, punchy and viral-worthy"}\n` +
     (clip
-      ? `Target clip length: ~${clip.targetSec.toFixed(0)}s (see CLIP SELECTION below)\n\n`
-      : `Output duration after the cut: ${duration.toFixed(1)}s\n\n`) +
+      ? `Target clip length: ~${clip.targetSec.toFixed(0)}s (see CLIP SELECTION below)\n`
+      : `Output duration after the cut: ${duration.toFixed(1)}s\n`) +
+    targetLine +
+    "\n" +
     // Landscape layout guidance (R21 §101): without it the first real 16:9
     // run put nearly every graphic in a lower third. A deterministic variety
     // pass downstream is the guarantee; this is the steer.
@@ -146,6 +190,87 @@ export interface BeatsValidationIssue {
   issue: string;
 }
 
+/**
+ * How many graphics a take of this length should be asked for (§118).
+ *
+ * The failure this exists for: nothing ever told the producer how many
+ * graphics to plan. `GRAPHICS_COVERAGE_TARGET` reads like a target and is
+ * only a ceiling — the demote loop below runs when the model plans too MANY
+ * and does nothing at all when it plans too few. On one 64s take the model
+ * planned three graphics against a budget that allowed roughly twenty-nine
+ * seconds of them; the loop never executed once, so no existing mechanism
+ * had an opinion.
+ *
+ * One graphic per ~9s of runtime, which is the density the prompt's own
+ * "never leave a stretch longer than ~10 seconds with no graphic" rule
+ * implies, floored at the §29 short-take count.
+ */
+export const SEC_PER_GRAPHIC = 9;
+
+/**
+ * Ordinal cues a speaker uses to enumerate. A take that counts its own
+ * points out loud is telling us how many graphics it wants, and that signal
+ * is free, deterministic, and better than any runtime heuristic.
+ */
+const ORDINAL_WORDS = [
+  "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten",
+];
+const ORDINAL_ADJECTIVES = [
+  "first", "second", "third", "fourth", "fifth",
+  "sixth", "seventh", "eighth", "ninth", "tenth",
+];
+
+/**
+ * How many distinct enumerated beats the speaker announces — "number one …
+ * number two", "first … second", "step 3". Counts DISTINCT ordinals so a
+ * speaker who says "number two" twice doesn't inflate the target, and
+ * requires at least two so a passing "first of all" isn't read as a list.
+ */
+export function countEnumeratedBeats(transcript: Transcript): number {
+  const words = transcript.words.map((w) =>
+    w.text.toLowerCase().replace(/[^a-z0-9]/g, ""),
+  );
+  const seen = new Set<number>();
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i]!;
+    const adj = ORDINAL_ADJECTIVES.indexOf(w);
+    if (adj !== -1) {
+      seen.add(adj + 1);
+      continue;
+    }
+    // "number one" / "step 2" / "point three" — the ordinal must FOLLOW a
+    // counting noun, or every stray "one" in the take counts as a beat.
+    if (w !== "number" && w !== "step" && w !== "point" && w !== "tip") continue;
+    const next = words[i + 1];
+    if (!next) continue;
+    const spelled = ORDINAL_WORDS.indexOf(next);
+    if (spelled !== -1) {
+      seen.add(spelled + 1);
+      continue;
+    }
+    const digit = Number.parseInt(next, 10);
+    if (Number.isInteger(digit) && digit >= 1 && digit <= 10) seen.add(digit);
+  }
+  return seen.size >= 2 ? seen.size : 0;
+}
+
+/**
+ * The number of graphics to ASK for — whichever of structure and runtime is
+ * larger. An enumerated take earns its own count plus a hook and a payoff
+ * (the virality grammar demands both anyway), but a long take that happens
+ * to enumerate three points still has everything else in it, so runtime
+ * density is a floor rather than a loser.
+ */
+export function graphicsTarget(runtimeSec: number, enumerated: number): number {
+  const byRuntime = Math.max(
+    SHORT_TAKE_MIN_GRAPHICS,
+    Math.round(runtimeSec / SEC_PER_GRAPHIC),
+  );
+  const byStructure = enumerated > 0 ? enumerated + 2 : 0;
+  // Never more than the moment schema can carry once alternation is counted.
+  return Math.min(Math.max(byRuntime, byStructure), 12);
+}
+
 /** Fraction of the runtime that should show a graphic (FINDINGS §7). */
 export const GRAPHICS_COVERAGE_TARGET = 0.45;
 /**
@@ -157,6 +282,28 @@ export const GRAPHICS_COVERAGE_TARGET = 0.45;
 export const SHORT_TAKE_SEC = 45;
 export const SHORT_TAKE_MIN_GRAPHICS = 4;
 
+/** Why the target was what it was, when the take enumerated itself. */
+function enumeratedNote(transcript: Transcript): string | null {
+  const n = countEnumeratedBeats(transcript);
+  return n > 0 ? ` — the take enumerates ${n} points` : null;
+}
+
+/**
+ * The one-line graphics accounting (§118b): delivered vs asked, and why the
+ * ask was what it was. One formatter for the console issue and `report.txt`,
+ * so the two can never say different things about the same run.
+ */
+export function formatGraphicsAccounting(
+  delivered: number,
+  asked: number,
+  transcript: Transcript,
+): string {
+  return (
+    `graphics: ${delivered} of ${asked} planned` +
+    (enumeratedNote(transcript) ?? ` (target is ~1 per ${SEC_PER_GRAPHIC}s)`)
+  );
+}
+
 /** A moment's approximate seconds of speech, from the transcript word stamps. */
 function momentDuration(m: Moment, transcript: Transcript): number {
   const first = transcript.words[m.startWord];
@@ -170,10 +317,21 @@ function momentMidpoint(m: Moment, transcript: Transcript): number {
   return first && last ? (first.start + last.end) / 2 : 0;
 }
 
-/** Semantic validation beyond the schema; repairs what it can, reports the rest. */
+/**
+ * Semantic validation beyond the schema; repairs what it can, reports the rest.
+ *
+ * `askedGraphics` is the count the PROMPT stated (§118b): pass it so the
+ * shortfall check measures against what was actually asked for — on a clip
+ * run the internal fallback would measure against the full take's runtime,
+ * not the clip target the prompt named. `null` skips the check entirely (the
+ * pre-slice pass of a clip run, whose sheet is renormalized after slicing —
+ * two passes reporting the same shortfall would say it twice). Omitted, the
+ * ask is derived from the transcript's own span.
+ */
 export function normalizeBeatSheet(
   sheet: BeatSheet,
   transcript: Transcript,
+  askedGraphics?: number | null,
 ): { sheet: BeatSheet; issues: BeatsValidationIssue[] } {
   const wordCount = transcript.words.length;
   const issues: BeatsValidationIssue[] = [];
@@ -225,6 +383,15 @@ export function normalizeBeatSheet(
 
   // On a short take the count floor outranks the percentage — never demote
   // below it, whatever the coverage budget says (§29).
+  //
+  // §118 decided NOT to extend this floor above 45s, and the reason matters:
+  // a floor that outranks the ceiling at every length would fight §114's
+  // full-span pricing — more graphics × whole moments blows past 45%, the
+  // loop below starts removing what the floor just required, and the two
+  // rules oscillate. It would also be treating the wrong failure. When the
+  // producer UNDER-plans, this loop never runs at all, so no floor here
+  // could have helped; the fix is the target in the prompt. What this layer
+  // owes the user instead is to SAY so — see the shortfall issue below.
   const minGraphics = runtime < SHORT_TAKE_SEC ? SHORT_TAKE_MIN_GRAPHICS : 0;
 
   for (;;) {
@@ -293,6 +460,22 @@ export function normalizeBeatSheet(
     issues.push({ moment: -1, issue: `coverText shortened to "${coverText}"` });
   }
 
+  // §118b: a run that under-delivers must say so. The producer was asked for
+  // a specific number of graphics; if fewer survive, that is a fact about
+  // this render the report should carry, exactly as every cut is justified.
+  // Silence is what let three graphics on a five-point take look normal.
+  const delivered = surviving().length;
+  const asked =
+    askedGraphics === undefined
+      ? graphicsTarget(runtime, countEnumeratedBeats(transcript))
+      : askedGraphics;
+  if (asked !== null && delivered < asked) {
+    issues.push({
+      moment: -1,
+      issue: formatGraphicsAccounting(delivered, asked, transcript),
+    });
+  }
+
   return { sheet: { hook: sheet.hook, coverText, moments }, issues };
 }
 
@@ -305,10 +488,22 @@ export async function generateBeatSheet(
   framingBrief?: string,
   clip?: { targetSec: number },
   aspect?: "9:16" | "16:9",
-): Promise<{ sheet: BeatSheet; issues: BeatsValidationIssue[]; highlight?: ClipHighlight }> {
+): Promise<{
+  sheet: BeatSheet;
+  issues: BeatsValidationIssue[];
+  /** The graphic count the prompt asked for (§118b) — what "asked" means everywhere downstream. */
+  asked: number;
+  highlight?: ClipHighlight;
+}> {
   const user =
     (speaker ? `The speaker: ${speaker}\n\n` : "") +
     buildBeatsUserPrompt(transcript, duration, intent, framingBrief, clip, aspect);
+  // The same number `buildBeatsUserPrompt` states — computed from the same
+  // inputs by the same pure functions, so the check and the ask agree.
+  const asked = graphicsTarget(
+    clip?.targetSec ?? duration,
+    countEnumeratedBeats(transcript),
+  );
   if (clip) {
     // Same editorial call, extended schema (R19 §93d) — the highlight and the
     // beat sheet come from ONE judgement, so they cannot disagree.
@@ -318,7 +513,8 @@ export async function generateBeatSheet(
       schema: ClipBeatSheetSchema,
       schemaName: "clip_beat_sheet",
     });
-    return { ...normalizeBeatSheet(raw, transcript), highlight: raw.highlight };
+    // `null`: the post-slice renormalization owns the shortfall check.
+    return { ...normalizeBeatSheet(raw, transcript, null), asked, highlight: raw.highlight };
   }
   const raw = await provider.complete({
     system: PRODUCER_SYSTEM,
@@ -326,5 +522,5 @@ export async function generateBeatSheet(
     schema: BeatSheetSchema,
     schemaName: "beat_sheet",
   });
-  return normalizeBeatSheet(raw, transcript);
+  return { ...normalizeBeatSheet(raw, transcript, asked), asked };
 }

package/src/producer/index.ts

@@ -106,6 +106,13 @@ export function defaultProviderName(env: NodeJS.ProcessEnv = process.env): Provi
 export interface ProduceScenesResult {
   beatSheet: BeatSheet;
   beatIssues: BeatsValidationIssue[];
+  /**
+   * The graphics accounting (§118b): how many the prompt asked for and how
+   * many survived planning. `delivered` equals the scene count — layout
+   * repair never demotes, and a failed props call falls back to a TitleCard
+   * rather than dropping the scene.
+   */
+  graphics: { asked: number; delivered: number };
   scenes: Scene[];
   failures: ScenePropsFailure[];
   /**
@@ -154,7 +161,7 @@ export async function produceScenes(
   const framingBrief = args.framing
     ? buildFramingBrief(args.framing, args.transcript)
     : undefined;
-  const { sheet, issues, highlight } = await generateBeatSheet(
+  const { sheet, issues, asked, highlight } = await generateBeatSheet(
     provider,
     args.transcript,
     args.outputDuration,
@@ -187,6 +194,9 @@ export async function produceScenes(
     const renorm = normalizeBeatSheet(
       { hook: sheet.hook, coverText: sheet.coverText, moments: anchored },
       transcript,
+      // The ask the prompt stated — NOT re-derived from the slice, which
+      // would compare the model against a number it was never given (§118b).
+      asked,
     );
     workingSheet = renorm.sheet;
     issues.push(...renorm.issues);
@@ -213,5 +223,13 @@ export async function produceScenes(
   const { scenes, failures } = await generateScenes(provider, moments, transcript, {
     framing: args.framing,
   });
-  return { beatSheet: { ...workingSheet, moments }, beatIssues: issues, scenes, failures, clip };
+  const delivered = moments.filter((m) => m.sceneKind !== "none").length;
+  return {
+    beatSheet: { ...workingSheet, moments },
+    beatIssues: issues,
+    graphics: { asked, delivered },
+    scenes,
+    failures,
+    clip,
+  };
 }

package/src/schema.ts

@@ -71,10 +71,22 @@ export type Analysis = z.infer<typeof AnalysisSchema>;
 
 export const ProbeSchema = z.object({
   duration: z.number().positive(),
+  /**
+   * DISPLAYED dimensions, after the rotation matrix (R27 §119) — not the raw
+   * stream's. A phone/camera writes a portrait take as a landscape stream plus
+   * a 90° display matrix, and ffmpeg's filter chain auto-rotates, so the raw
+   * numbers disagree with every measurement taken through ffmpeg.
+   */
   width: z.number().int().positive(),
   height: z.number().int().positive(),
   fps: z.number().positive(),
   hasAudio: z.boolean(),
+  /**
+   * The stream's rotation in degrees (0/90/180/270), recorded so a workdir says
+   * why its geometry is what it is. Optional: pre-§119 `production.json` files
+   * predate it and must still parse.
+   */
+  rotation: z.number().int().optional(),
 });
 export type Probe = z.infer<typeof ProbeSchema>;