@ossclip/core 0.1.35 → 0.1.36

package/package.json

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

package/src/browser.ts

@@ -18,6 +18,21 @@ export * from "./fill";
 // on this surface), but only this one function is exposed: the rest of the
 // module is the pipeline's, not the bundle's.
 export { sceneStartSeconds } from "./assemble";
+// The editor's live grade preview computes the SVG filter spec with the SAME
+// math produce bakes into render-props (`gradeToSvgFilterSpec`) — a browser
+// copy of the curve sampler is how the preview and the render would drift.
+// color-grade.ts is already in this surface's runtime graph (./overrides
+// imports ColorGradeSchema for the doc-global `colorGrade` key), so these
+// value exports add no new modules; only the functions the preview needs are
+// exposed, the `sceneStartSeconds` posture.
+export {
+  GRADE_PRESETS,
+  gradeToSvgFilterSpec,
+  resolveGradeToLook,
+  type ColorGrade,
+  type GradePresetId,
+  type SvgGradeFilterSpec,
+} from "./color-grade";
 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.

package/src/color-grade.ts

@@ -0,0 +1,562 @@
+import { z } from "zod/v4";
+
+/**
+ * Color grade — the whole module is pure (no filesystem, no TTY) so every
+ * curve, LUT sample and matrix can be tested against hand-computed values.
+ * `node:crypto` is the one Node import, and it is deterministic.
+ *
+ * The user-facing shape below is shared by config.json, overrides.json and
+ * the CLI, so it is parsed with zod here once rather than coerced at three
+ * consumers. `preset` names a bundled parametric look; `lut` names a `.cube`
+ * file (basename only — path resolution is the caller's I/O, not ours).
+ */
+export const ColorGradeSchema = z
+  .strictObject({
+    /** Bundled parametric look id — one of `Object.keys(GRADE_PRESETS)`. */
+    preset: z.string().optional(),
+    /** `.cube` filename in `~/.ossclip/luts`, basename only. */
+    lut: z.string().optional(),
+    /** 0..1 blend toward the graded image. Default: the preset's own, or 1 for a LUT. */
+    intensity: z.number().min(0).max(1).optional(),
+    /** Exposure in EV (stops). */
+    exposure: z.number().min(-2).max(2).optional(),
+    /** Warm (+) / cool (−), a deliberately small per-channel gain. */
+    temperature: z.number().min(-100).max(100).optional(),
+    /** 1 = unchanged. */
+    saturation: z.number().min(0).max(2).optional(),
+    /** 1 = unchanged. */
+    contrast: z.number().min(0).max(2).optional(),
+  })
+  .refine((g) => (g.preset !== undefined) !== (g.lut !== undefined), {
+    message: 'set exactly one of "preset" or "lut" — a grade needs one look, not zero or two',
+  });
+export type ColorGrade = z.infer<typeof ColorGradeSchema>;
+
+/**
+ * The internal parametric look. Tints are small additive per-channel biases
+ * weighted by luma (split-toning): `shadowTint` pulls the darks, one minus
+ * luma at a time, `highlightTint` the brights.
+ */
+export interface LookParams {
+  /** -100..100, warm (+) / cool (−) — mapped to per-channel gains in `applyGrade`. */
+  temperature: number;
+  /** Green-magenta axis, same tiny-gain scale as temperature. */
+  tint: number;
+  /** EV. */
+  exposure: number;
+  /** Pivot-0.5 slope; 1 = unchanged. */
+  contrast: number;
+  /** Raised black floor, 0..~0.1 in practice. */
+  lift: number;
+  /** 1 = unchanged, 0 = mono. */
+  saturation: number;
+  shadowTint: [number, number, number];
+  highlightTint: [number, number, number];
+  /** What `intensity` means when the user didn't set one. */
+  defaultIntensity: number;
+}
+
+/** A look that changes nothing — the base every preset and tweak builds on. */
+export const IDENTITY_LOOK: LookParams = {
+  temperature: 0,
+  tint: 0,
+  exposure: 0,
+  contrast: 1,
+  lift: 0,
+  saturation: 1,
+  shadowTint: [0, 0, 0],
+  highlightTint: [0, 0, 0],
+  defaultIntensity: 1,
+};
+
+export type GradePresetId = "talking-head" | "teal-orange" | "filmic-fade" | "cwa" | "punchy" | "mono";
+
+export const GRADE_PRESETS: Record<GradePresetId, LookParams> = {
+  // The flagship for YouTube talking-head footage: skin-safe, so hue shifts
+  // stay mild — warmth and a gentle S-curve, nothing that moves skin tones.
+  // Tuned on real channel footage (2026-08-30): the source is already warm
+  // tungsten light, so temperature stays small; and because contrast runs
+  // before lift in applyGrade, a 1.08 slope at pivot 0.5 pulls black down
+  // 0.04 — more than a 0.03 lift puts back. 1.06/0.045 keeps the fade.
+  "talking-head": {
+    ...IDENTITY_LOOK,
+    temperature: 10,
+    contrast: 1.06,
+    lift: 0.045,
+    saturation: 1.05,
+    defaultIntensity: 0.6,
+  },
+  // The blockbuster split-tone: teal shadows against warm highlights.
+  "teal-orange": {
+    ...IDENTITY_LOOK,
+    shadowTint: [-0.03, 0.01, 0.04],
+    highlightTint: [0.04, 0.01, -0.03],
+    contrast: 1.15,
+    saturation: 1.05,
+    defaultIntensity: 0.7,
+  },
+  // Faded film stock: lifted blacks, softened contrast, muted color.
+  "filmic-fade": {
+    ...IDENTITY_LOOK,
+    lift: 0.06,
+    contrast: 0.95,
+    saturation: 0.9,
+    temperature: 8,
+    defaultIntensity: 0.8,
+  },
+  // Thumbnail-bright: more contrast and more color, for footage shot flat.
+  punchy: {
+    ...IDENTITY_LOOK,
+    contrast: 1.2,
+    saturation: 1.15,
+    defaultIntensity: 0.7,
+  },
+  // Ahsan's channel look (2026-08-30), designed against his published footage:
+  // camera runs ~0.1 EV under, the room's tungsten already supplies warmth, so
+  // exposure does the lifting and temperature barely moves. Teal in the
+  // shadows / warm highlights for depth that doesn't announce itself; params
+  // are at final strength, hence defaultIntensity 1.
+  cwa: {
+    ...IDENTITY_LOOK,
+    temperature: 6,
+    exposure: 0.1,
+    contrast: 1.09,
+    lift: 0.05,
+    saturation: 1.06,
+    shadowTint: [-0.015, 0.0, 0.02],
+    highlightTint: [0.02, 0.005, -0.01],
+    defaultIntensity: 1,
+  },
+  // Black and white with a touch of contrast to keep it from going gray mush.
+  mono: {
+    ...IDENTITY_LOOK,
+    saturation: 0,
+    contrast: 1.1,
+    defaultIntensity: 1,
+  },
+};
+
+/** Rec.709 luma weights — the footage this pipeline grades is Rec.709. */
+const LUMA: [number, number, number] = [0.2126, 0.7152, 0.0722];
+
+const clamp01 = (c: number): number => Math.min(1, Math.max(0, c));
+const mix = (a: number, b: number, t: number): number => a + (b - a) * t;
+
+/**
+ * Steps 1–4 of the pipeline — the channel-INDEPENDENT portion (exposure,
+ * temperature/tint gains, contrast, lift). Split out so `applyGrade` and the
+ * SVG filter's per-channel transfer tables are the same math by construction:
+ * a curve sampled here IS the curve the evaluator ran.
+ *
+ * Unclamped on purpose: `applyGrade` clamps once at the end, and clamping
+ * here would bake a different (earlier) clip point into the tables.
+ */
+function channelCurve(params: LookParams, channel: 0 | 1 | 2, value: number): number {
+  // 1. exposure, in stops.
+  let c = value * 2 ** params.exposure;
+  // 2. temperature/tint as per-channel gains. 0.0015/unit keeps the full
+  //    ±100 range at a ±15% gain — a grade, not a gel.
+  const gain =
+    channel === 0
+      ? 1 + params.temperature * 0.0015
+      : channel === 1
+        ? 1 + params.tint * 0.0015
+        : 1 - params.temperature * 0.0015;
+  c *= gain;
+  // 3. contrast about a 0.5 pivot. A linear pivot, not a filmic S — fine for
+  //    v1 in gamma-encoded space, where 0.5 is already perceptual mid-gray.
+  c = 0.5 + (c - 0.5) * params.contrast;
+  // 4. lift: raise the black floor without touching white.
+  c = c * (1 - params.lift) + params.lift;
+  return c;
+}
+
+/**
+ * The single source of truth for what a look DOES to a pixel. Everything
+ * else — the SVG filter spec, the baked .cube — is an encoding of this
+ * function, and the tests hold them to it.
+ *
+ * Operates in gamma-encoded space (pragmatic: the footage is Rec.709, and a
+ * linearize/delinearize round-trip buys little for these mild looks).
+ * Input and output are 0..1 per channel; output is clamped.
+ */
+export function applyGrade(
+  params: LookParams,
+  rgb: [number, number, number],
+): [number, number, number] {
+  const c: [number, number, number] = [
+    channelCurve(params, 0, rgb[0]),
+    channelCurve(params, 1, rgb[1]),
+    channelCurve(params, 2, rgb[2]),
+  ];
+  // 5. split-tone: tint shadows and highlights by luma weight.
+  const luma = LUMA[0] * c[0] + LUMA[1] * c[1] + LUMA[2] * c[2];
+  for (let i = 0; i < 3; i++) {
+    c[i] = c[i]! + params.shadowTint[i]! * (1 - luma) + params.highlightTint[i]! * luma;
+  }
+  // 6. saturation: pull toward (or push away from) the pixel's luma.
+  const luma2 = LUMA[0] * c[0] + LUMA[1] * c[1] + LUMA[2] * c[2];
+  return [
+    clamp01(mix(luma2, c[0], params.saturation)),
+    clamp01(mix(luma2, c[1], params.saturation)),
+    clamp01(mix(luma2, c[2], params.saturation)),
+  ];
+}
+
+/** `mix(rgb, applyGrade(rgb), intensity)` — the user's blend knob. */
+export function applyGradeWithIntensity(
+  params: LookParams,
+  intensity: number,
+  rgb: [number, number, number],
+): [number, number, number] {
+  const graded = applyGrade(params, rgb);
+  return [
+    mix(rgb[0], graded[0], intensity),
+    mix(rgb[1], graded[1], intensity),
+    mix(rgb[2], graded[2], intensity),
+  ];
+}
+
+export interface ResolvedGrade {
+  params: LookParams;
+  intensity: number;
+}
+
+/** The two-stage SVG filter: feComponentTransfer tables, then feColorMatrix. */
+export interface SvgGradeFilterSpec {
+  /** 33 samples each, for `<feFuncR type="table">` etc. */
+  tableR: number[];
+  tableG: number[];
+  tableB: number[];
+  /** 20 values row-major, for `<feColorMatrix type="matrix">`. */
+  colorMatrix: number[];
+}
+
+/** Samples per transfer-table channel — 33 matches the default .cube lattice. */
+const SVG_TABLE_SAMPLES = 33;
+
+/** 4x5 affine identity in feColorMatrix's 20-value row-major layout. */
+const IDENTITY_MATRIX: number[] = [
+  1, 0, 0, 0, 0,
+  0, 1, 0, 0, 0,
+  0, 0, 1, 0, 0,
+  0, 0, 0, 1, 0,
+];
+
+/** `a ∘ b` for 4x5 affine color matrices (apply `b` first, then `a`). */
+function composeColorMatrix(a: number[], b: number[]): number[] {
+  const out = new Array<number>(20).fill(0);
+  for (let r = 0; r < 4; r++) {
+    for (let c = 0; c < 4; c++) {
+      let v = 0;
+      for (let k = 0; k < 4; k++) v += a[r * 5 + k]! * b[k * 5 + c]!;
+      out[r * 5 + c] = v;
+    }
+    let konst = a[r * 5 + 4]!;
+    for (let k = 0; k < 4; k++) konst += a[r * 5 + k]! * b[k * 5 + 4]!;
+    out[r * 5 + 4] = konst;
+  }
+  return out;
+}
+
+/**
+ * Encode a resolved grade as an SVG filter. Per-channel curves cannot carry
+ * cross-channel ops, so the pipeline decomposes into:
+ *
+ *  - Stage A (feComponentTransfer tables): the channel-independent steps 1–4,
+ *    sampled at 33 points per channel via the same `channelCurve` the
+ *    evaluator runs.
+ *  - Stage B (feColorMatrix): split-tone + saturation. Both are affine in
+ *    rgb — luma is a dot product — so the stage is EXACT: the split-tone
+ *    matrix (row c gains `(highlight_c − shadow_c)·L`, constant `shadow_c`)
+ *    composed with the standard Rec.709 saturation matrix.
+ *
+ * Intensity blends Stage A toward identity tables and Stage B toward the
+ * identity matrix, each by `k`. That is an approximation of blending the
+ * COMPOSED pipeline (blend-then-compose ≠ compose-then-blend), accepted
+ * because it is exact at k=0 and k=1 and visually indistinguishable between,
+ * and the alternative — a third filter input carrying the ungraded image —
+ * costs an feImage round-trip per frame.
+ */
+export function gradeToSvgFilterSpec(grade: ResolvedGrade): SvgGradeFilterSpec {
+  const { params, intensity } = grade;
+  const table = (channel: 0 | 1 | 2): number[] => {
+    const out: number[] = [];
+    for (let i = 0; i < SVG_TABLE_SAMPLES; i++) {
+      const x = i / (SVG_TABLE_SAMPLES - 1);
+      // Clamp before blending: feComponentTransfer table values live in 0..1,
+      // and blending toward x keeps the result there.
+      out.push(mix(x, clamp01(channelCurve(params, channel, x)), intensity));
+    }
+    return out;
+  };
+
+  const d: [number, number, number] = [
+    params.highlightTint[0] - params.shadowTint[0],
+    params.highlightTint[1] - params.shadowTint[1],
+    params.highlightTint[2] - params.shadowTint[2],
+  ];
+  const split: number[] = [
+    1 + d[0] * LUMA[0], d[0] * LUMA[1], d[0] * LUMA[2], 0, params.shadowTint[0],
+    d[1] * LUMA[0], 1 + d[1] * LUMA[1], d[1] * LUMA[2], 0, params.shadowTint[1],
+    d[2] * LUMA[0], d[2] * LUMA[1], 1 + d[2] * LUMA[2], 0, params.shadowTint[2],
+    0, 0, 0, 1, 0,
+  ];
+  const s = params.saturation;
+  const sat: number[] = [
+    (1 - s) * LUMA[0] + s, (1 - s) * LUMA[1], (1 - s) * LUMA[2], 0, 0,
+    (1 - s) * LUMA[0], (1 - s) * LUMA[1] + s, (1 - s) * LUMA[2], 0, 0,
+    (1 - s) * LUMA[0], (1 - s) * LUMA[1], (1 - s) * LUMA[2] + s, 0, 0,
+    0, 0, 0, 1, 0,
+  ];
+  const composed = composeColorMatrix(sat, split);
+  const colorMatrix = composed.map((v, i) => mix(IDENTITY_MATRIX[i]!, v, intensity));
+
+  return { tableR: table(0), tableG: table(1), tableB: table(2), colorMatrix };
+}
+
+/** A parsed .cube 3D LUT — `data` is r-fastest, length `3 * size³`. */
+export interface CubeLut {
+  size: number;
+  domainMin: [number, number, number];
+  domainMax: [number, number, number];
+  data: Float32Array;
+  title?: string;
+}
+
+/**
+ * Parse Adobe/Resolve `.cube` text. Lenient about FORM — BOM, CRLF, tabs,
+ * comments anywhere, keywords in any position — because .cube files come
+ * from a dozen exporters that each format differently. Strict about
+ * CONTENT — size range, exact line count, finite floats — because a
+ * half-parsed LUT is a wrong grade on every frame, and the file is user
+ * input the caller will report, not swallow.
+ *
+ * Values outside 0..1 are PRESERVED here: log/HDR LUTs legitimately exceed
+ * the domain, and clamping belongs at apply time (`sampleCubeLut`), not
+ * parse time. `Number`, never `parseFloat` with a locale — a comma decimal
+ * must fail loudly, not truncate silently.
+ */
+export function parseCubeLut(text: string): CubeLut {
+  const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+  let size: number | undefined;
+  let title: string | undefined;
+  const domainMin: [number, number, number] = [0, 0, 0];
+  const domainMax: [number, number, number] = [1, 1, 1];
+  const values: number[] = [];
+
+  const parseTriple = (fields: string[], line: string): [number, number, number] => {
+    if (fields.length !== 3) throw new Error(`.cube: expected 3 values per line, got "${line}"`);
+    const nums = fields.map(Number) as [number, number, number];
+    if (nums.some((n) => !Number.isFinite(n))) {
+      throw new Error(`.cube: non-numeric value in line "${line}"`);
+    }
+    return nums;
+  };
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const fields = line.split(/\s+/);
+    const first = fields[0]!; // a trimmed non-empty line always has a first field
+    const keyword = first.toUpperCase();
+    if (keyword === "TITLE") {
+      // Everything after the keyword, quotes stripped — titles contain spaces.
+      title = line.slice(first.length).trim().replace(/^"(.*)"$/, "$1");
+      continue;
+    }
+    if (keyword === "LUT_1D_SIZE") throw new Error(".cube: 1D LUTs not supported");
+    if (keyword === "LUT_3D_SIZE") {
+      const n = Number(fields[1]);
+      if (!Number.isInteger(n) || n < 2 || n > 256) {
+        throw new Error(`.cube: LUT_3D_SIZE must be an integer in 2..256, got "${fields[1]}"`);
+      }
+      size = n;
+      continue;
+    }
+    if (keyword === "DOMAIN_MIN" || keyword === "DOMAIN_MAX") {
+      const nums = parseTriple(fields.slice(1), line);
+      const target = keyword === "DOMAIN_MIN" ? domainMin : domainMax;
+      for (let i = 0; i < 3; i++) target[i] = nums[i]!;
+      continue;
+    }
+    if (/^[A-Za-z_]/.test(first)) {
+      throw new Error(`.cube: unrecognized keyword "${first}"`);
+    }
+    values.push(...parseTriple(fields, line));
+  }
+
+  if (size === undefined) throw new Error(".cube: missing LUT_3D_SIZE");
+  const expected = 3 * size ** 3;
+  if (values.length !== expected) {
+    throw new Error(
+      `.cube: expected ${size}³ = ${expected / 3} data lines, got ${values.length / 3}`,
+    );
+  }
+  return { size, domainMin, domainMax, data: Float32Array.from(values), title };
+}
+
+/** Trilinear sample. Input mapped through the LUT's domain; output clamped 0..1. */
+export function sampleCubeLut(
+  lut: CubeLut,
+  rgb: [number, number, number],
+): [number, number, number] {
+  const n = lut.size;
+  const axis = (i: 0 | 1 | 2): number => {
+    const span = lut.domainMax[i] - lut.domainMin[i];
+    const t = span === 0 ? 0 : (rgb[i] - lut.domainMin[i]) / span;
+    return clamp01(t) * (n - 1);
+  };
+  const coord: [number, number, number] = [axis(0), axis(1), axis(2)];
+  const lo = coord.map(Math.floor) as [number, number, number];
+  const hi = lo.map((v) => Math.min(v + 1, n - 1)) as [number, number, number];
+  const f = coord.map((v, i) => v - lo[i]!) as [number, number, number];
+  // r fastest in the data layout: index = 3 * (r + n*g + n²*b).
+  const at = (r: number, g: number, b: number, ch: number): number =>
+    lut.data[3 * (r + n * g + n * n * b) + ch]!;
+  const out: [number, number, number] = [0, 0, 0];
+  for (let ch = 0; ch < 3; ch++) {
+    const c00 = mix(at(lo[0], lo[1], lo[2], ch), at(hi[0], lo[1], lo[2], ch), f[0]);
+    const c10 = mix(at(lo[0], hi[1], lo[2], ch), at(hi[0], hi[1], lo[2], ch), f[0]);
+    const c01 = mix(at(lo[0], lo[1], hi[2], ch), at(hi[0], lo[1], hi[2], ch), f[0]);
+    const c11 = mix(at(lo[0], hi[1], hi[2], ch), at(hi[0], hi[1], hi[2], ch), f[0]);
+    out[ch] = clamp01(mix(mix(c00, c10, f[1]), mix(c01, c11, f[1]), f[2]));
+  }
+  return out;
+}
+
+/**
+ * Emit .cube text for a look — the renderer-agnostic encoding. Each lattice
+ * point p (r fastest) becomes `mix(p, pipeline(p), intensity)` where the
+ * pipeline is the base LUT sample (when one is given) with
+ * `applyGrade(params)` composed ON TOP of it (when given): sample first, then
+ * tweak. Composition, not either/or — `resolveGradeToLook` hands a LUT grade
+ * back as `lutRef` + `tweaks`, and a bake that ignored `params` next to a
+ * `base` would silently drop the user's exposure/saturation knobs exactly
+ * when a LUT is in play (the pre-2026-08-30 behavior, once a documented
+ * deviation). Deterministic on purpose — fixed 6-decimal formatting, stable
+ * key order — so `lutHash` of the output is a valid cache key.
+ */
+export function bakeCube(opts: {
+  base?: CubeLut;
+  params?: LookParams;
+  intensity: number;
+  size?: number;
+}): string {
+  const size = opts.size ?? opts.base?.size ?? 33;
+  const pipeline = (p: [number, number, number]): [number, number, number] => {
+    const sampled = opts.base ? sampleCubeLut(opts.base, p) : p;
+    return opts.params ? applyGrade(opts.params, sampled) : sampled;
+  };
+  const lines: string[] = ['TITLE "ossclip"', `LUT_3D_SIZE ${size}`];
+  for (let b = 0; b < size; b++) {
+    for (let g = 0; g < size; g++) {
+      for (let r = 0; r < size; r++) {
+        const p: [number, number, number] = [r / (size - 1), g / (size - 1), b / (size - 1)];
+        const out = pipeline(p);
+        lines.push(
+          ([0, 1, 2] as const).map((i) => mix(p[i], out[i], opts.intensity).toFixed(6)).join(" "),
+        );
+      }
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Short fingerprint of baked .cube text, for cache filenames. FNV-1a 64-bit,
+ * not sha256: this module is in `@ossclip/core/browser`'s graph (overrides.ts
+ * imports the schema), so a top-level `node:crypto` import broke the editor's
+ * Vite build outright. A cache key needs determinism, not cryptography, and
+ * 64 bits is collision-safe at the scale of one user's LUT directory.
+ */
+export function lutHash(cubeText: string): string {
+  const PRIME = 0x100000001b3n;
+  let h = 0xcbf29ce484222325n;
+  for (let i = 0; i < cubeText.length; i++) {
+    h ^= BigInt(cubeText.charCodeAt(i));
+    h = (h * PRIME) & 0xffffffffffffffffn;
+  }
+  return h.toString(16).padStart(16, "0").slice(0, 12);
+}
+
+/**
+ * Validate a grade value from config/overrides/CLI. Never throws and never
+ * coerces (CLAUDE.md's parse-don't-coerce): a malformed grade is one warning
+ * naming the source and no grade at all — a typo must cost the look, not the
+ * run. The warning is RETURNED rather than printed so this stays pure, the
+ * `resolveSfxBundledPack` shape.
+ *
+ * An unknown preset id is caught HERE, not in the schema, so the warning can
+ * list what exists — a schema enum would reject with zod's generic message.
+ */
+export function resolveColorGrade(
+  value: unknown,
+  source: string,
+): { grade?: ColorGrade; warning?: string } {
+  if (value === undefined) return {};
+  const parsed = ColorGradeSchema.safeParse(value);
+  if (!parsed.success) {
+    return { warning: `⚠ ${source} colorGrade ignored — ${parsed.error.issues[0]?.message}` };
+  }
+  const preset = parsed.data.preset;
+  if (preset !== undefined && !(preset in GRADE_PRESETS)) {
+    return {
+      warning:
+        `⚠ ${source} colorGrade ignored — unknown preset "${preset}" ` +
+        `(have: ${Object.keys(GRADE_PRESETS).join(", ")})`,
+    };
+  }
+  return { grade: parsed.data };
+}
+
+export interface ResolvedLutGrade {
+  kind: "lut";
+  /** The `.cube` basename — the caller resolves it under `~/.ossclip/luts`. */
+  lutRef: string;
+  /** User tweaks as a look, applied ON TOP of the LUT sample. */
+  tweaks: LookParams;
+  intensity: number;
+}
+export interface ResolvedPresetGrade extends ResolvedGrade {
+  kind: "preset";
+}
+
+/**
+ * Merge a validated grade into something the renderer can run: preset params
+ * with the user's tweaks composed on top (exposure/temperature ADD,
+ * saturation/contrast MULTIPLY — a tweak is relative to the look, not a
+ * replacement for it), or a LUT reference with the tweaks as their own look.
+ * Intensity falls back to the preset's `defaultIntensity`, or 1 for a LUT.
+ */
+export function resolveGradeToLook(grade: ColorGrade): ResolvedPresetGrade | ResolvedLutGrade {
+  if (grade.lut !== undefined) {
+    return {
+      kind: "lut",
+      lutRef: grade.lut,
+      tweaks: {
+        ...IDENTITY_LOOK,
+        exposure: grade.exposure ?? 0,
+        temperature: grade.temperature ?? 0,
+        saturation: grade.saturation ?? 1,
+        contrast: grade.contrast ?? 1,
+      },
+      intensity: grade.intensity ?? 1,
+    };
+  }
+  // `resolveColorGrade` guarantees the id exists; a caller who skipped it and
+  // passed an unknown preset gets the identity look rather than a crash.
+  const base =
+    (GRADE_PRESETS as Partial<Record<string, LookParams>>)[grade.preset ?? ""] ?? IDENTITY_LOOK;
+  return {
+    kind: "preset",
+    params: {
+      ...base,
+      exposure: base.exposure + (grade.exposure ?? 0),
+      temperature: base.temperature + (grade.temperature ?? 0),
+      saturation: base.saturation * (grade.saturation ?? 1),
+      contrast: base.contrast * (grade.contrast ?? 1),
+    },
+    intensity: grade.intensity ?? base.defaultIntensity,
+  };
+}

package/src/config.ts

@@ -128,6 +128,21 @@ export interface OssclipConfig {
    * with a warning instead of silently half-applying.
    */
   theme?: Partial<Theme>;
+  /**
+   * Color grade applied to every produce run — the `ColorGradeSchema` shape
+   * (`{"preset": "talking-head"}` or `{"lut": "kodak.cube"}`, plus optional
+   * intensity/exposure/temperature/saturation/contrast tweaks), for a channel
+   * whose look is a standing decision rather than a per-run flag.
+   * `--color-grade` / `--no-color-grade` win over this per run, and an
+   * overrides.json `colorGrade` beats both (`resolveProductionColorGrade` in
+   * produce.ts). File-only, the `theme` posture: a structured value from
+   * hand-edited JSON, validated where it is USED (via core's
+   * `resolveColorGrade`), so a malformed grade or unknown preset earns one
+   * warning naming the source and an ungraded run, never a coerced look.
+   * Typed `unknown` deliberately — the type promising `ColorGrade` here would
+   * imply a parse `loadConfig` never performs.
+   */
+  colorGrade?: unknown;
   /**
    * Run the `--youtube` pack (SEO metadata + AI thumbnail) on every produce,
    * so the preference is a one-time config write like `watermark`.
@@ -321,6 +336,13 @@ export function resolveConfig(
     // warning naming the problem and the safe default, never a coercion.
     dictionary: fileCfg.dictionary,
     theme: fileCfg.theme,
+    // File-only, the `theme` posture, and NO env spelling (a grade is a
+    // structured object no env var can carry honestly): validated at the
+    // consumer (`resolveProductionColorGrade` in produce.ts via
+    // `resolveColorGrade`), where a malformed value earns one warning naming
+    // the source and an ungraded run — the postizUrl lesson says the mapping
+    // must still copy it, or the key is invisible at runtime.
+    colorGrade: fileCfg.colorGrade,
     // File-only, the same posture: both are validated where they are USED —
     // `validModelSources` / `resolveWhisperLanguage` — so a hand-edited
     // non-record or non-string earns one warning there, never a coercion.

package/src/index.ts

@@ -20,6 +20,8 @@ export * from "./retake";
 export * from "./captions";
 export * from "./fonts";
 export * from "./sfx-pack";
+export * from "./color-grade";
+export * from "./lut-library";
 export * from "./dictionary";
 export * from "./zoom";
 export * from "./grounding";

package/src/ingest.ts

@@ -190,11 +190,56 @@ export function mezzanineScale(
  * the legacy names so existing workdir caches stay valid; a scaled run
  * rebuilds once under its own name and old workdirs' render-props keep
  * referencing (and rendering from) the file they were emitted against.
+ *
+ * The LUT hash is in the name for the same reason: grading is baked into the
+ * mezzanine at build time, so a warm workdir keyed only on crop/scale would
+ * satisfy a graded run with UNGRADED frames (or a re-graded run with the old
+ * look). No LUT keeps today's names byte-for-byte, so existing warm workdirs
+ * stay valid.
  */
-export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null): string {
+export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null, lutHash?: string): string {
   const base = cropped ? "mezzanine-content" : "mezzanine";
-  if (!scale) return `${base}.mp4`;
-  return `${base}-${scale.width}x${scale.height}@${Math.round(scale.fps)}.mp4`;
+  const scaleSeg = scale ? `-${scale.width}x${scale.height}@${Math.round(scale.fps)}` : "";
+  const lutSeg = lutHash ? `-lut${lutHash}` : "";
+  return `${base}${scaleSeg}${lutSeg}.mp4`;
+}
+
+/** A 3D LUT to bake into the mezzanine; `hash` keys the cache (see `mezzanineFileName`). */
+export interface MezzanineLut {
+  path: string;
+  hash: string;
+}
+
+/**
+ * Escape a filesystem path for use as an ffmpeg filter option value.
+ *
+ * A `-vf` string is parsed twice: once as a filtergraph (where `\` `'` `[`
+ * `]` `,` `;` are special) and once as the filter's option value (where `:`
+ * `\` `'` are special — `:` is the option separator, so an unescaped drive
+ * letter like `C:` truncates the path there). Each level strips one layer of
+ * backslashes, so the option-level escapes must themselves be escaped for
+ * the graph level: `:` → `\\:`, `'` → `\\\'`, `\` → `\\\\`. Spaces need
+ * nothing — the argv goes straight to ffmpeg, no shell in between.
+ */
+export function escapeFilterPath(p: string): string {
+  // Level 1: filter option value — `:` `\` `'` are special.
+  const option = p.replace(/[\\':]/g, (c) => `\\${c}`);
+  // Level 2: filtergraph — escape again so level-1 backslashes survive.
+  return option.replace(/[\\'[\],;]/g, (c) => `\\${c}`);
+}
+
+/**
+ * The mezzanine's `-vf` chain, pure so the ordering contract is testable:
+ * LUT strictly AFTER crop/scale — grading the letterbox bars would be
+ * wasted math, and grading pre-scale pixels the render never sees changes
+ * nothing but costs full-res per-pixel lookups.
+ */
+export function mezzanineVf(opts: { cropVf?: string; scale?: MezzanineScale; lut?: MezzanineLut }): string {
+  return [
+    ...(opts.cropVf ? [opts.cropVf] : []),
+    ...(opts.scale ? [`scale=${opts.scale.width}:${opts.scale.height}`] : []),
+    ...(opts.lut ? [`lut3d=file=${escapeFilterPath(opts.lut.path)}:interp=tetrahedral`] : []),
+  ].join(",");
 }
 
 /**
@@ -206,17 +251,15 @@ export function mezzanineFileName(cropped: boolean, scale: MezzanineScale | null
  *
  * `scale` (from `mezzanineScale`) downsizes to display size in the SAME
  * pass, crop first — the scale dims are computed on the post-crop picture.
+ * `lut` bakes a 3D grade in last, on exactly the pixels the render will see.
  */
 export async function makeMezzanine(
   tools: IngestTools,
   src: string,
   out: string,
-  opts: { cropVf?: string; scale?: MezzanineScale } = {},
+  opts: { cropVf?: string; scale?: MezzanineScale; lut?: MezzanineLut } = {},
 ): Promise<void> {
-  const vf = [
-    ...(opts.cropVf ? [opts.cropVf] : []),
-    ...(opts.scale ? [`scale=${opts.scale.width}:${opts.scale.height}`] : []),
-  ].join(",");
+  const vf = mezzanineVf(opts);
   await run(tools.ffmpegPath, [
     "-y", "-i", src,
     ...(vf ? ["-vf", vf] : []),

package/src/lut-library.ts

@@ -0,0 +1,81 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { CONFIG_DIR } from "./config";
+import { parseCubeLut } from "./color-grade";
+
+/**
+ * The user's .cube LUT directory, discovered — the `sfx-pack.ts` shape for
+ * color grades. `parseCubeLut` stays pure; this module is the thin fs layer
+ * that walks `~/.ossclip/luts` and reports, per file, either a usable LUT or
+ * the reason it is not one. Nothing here throws: a hand-dropped .cube is user
+ * input, and a broken one must cost that one menu entry, not the editor.
+ */
+
+/** Where user LUTs live: `~/.ossclip/luts/<name>.cube`. */
+export function userLutDir(): string {
+  return join(CONFIG_DIR, "luts");
+}
+
+/** One LUT the menu can offer. `path` stays server-side, like SFX `absPath`. */
+export interface LutLibraryItem {
+  /** The filename stem — what `ColorGrade.lut` (basename) resolves against. */
+  id: string;
+  /** The .cube's own TITLE when it has one, else the stem. */
+  title: string;
+  /** Absolute path — the caller's I/O concern, never sent to a client. */
+  path: string;
+}
+
+/** Why one file is not in the library — `SfxPackIssue`'s shape, per file. */
+export interface LutLibraryIssue {
+  /** The .cube filename (basename) that failed. */
+  file: string;
+  message: string;
+}
+
+export interface LutLibrary {
+  items: LutLibraryItem[];
+  issues: LutLibraryIssue[];
+}
+
+/**
+ * Every parseable `.cube` under `dir`, plus an issue per file that is not one.
+ * Each file is fully parsed here — not just listed — because the menu is the
+ * ONLY surface where a broken LUT can be reported before a render silently
+ * drops it: `parseCubeLut` is strict about content on purpose, and offering a
+ * file the bake will refuse is the exact mismatch the SFX library gate exists
+ * to avoid.
+ *
+ * A missing directory is the normal case (most users never drop a LUT), not
+ * an issue. `dir` is a parameter with a default rather than a `homedir()`
+ * read inside, so tests point it at a tmp dir and never touch a real home
+ * (`loadSfxLibrary`'s rule).
+ */
+export function loadLutLibrary(dir: string = userLutDir()): LutLibrary {
+  let names: string[] = [];
+  try {
+    names = readdirSync(dir, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.toLowerCase().endsWith(".cube"))
+      .map((e) => e.name)
+      // Sorted so the menu reads the same on every machine — readdir order is
+      // not a promise (loadSfxLibrary's merge-order rule).
+      .sort();
+  } catch {
+    return { items: [], issues: [] };
+  }
+  const items: LutLibraryItem[] = [];
+  const issues: LutLibraryIssue[] = [];
+  for (const name of names) {
+    const path = join(dir, name);
+    const stem = basename(name, extname(name));
+    try {
+      const lut = parseCubeLut(readFileSync(path, "utf8"));
+      // TITLE when the exporter wrote one — a human-readable label the stem
+      // (often `Vendor_Look_33pt_v2`) cannot match. Empty titles fall back.
+      items.push({ id: stem, title: lut.title?.trim() || stem, path });
+    } catch (e) {
+      issues.push({ file: name, message: e instanceof Error ? e.message : String(e) });
+    }
+  }
+  return { items, issues };
+}

package/src/overrides.ts

@@ -1,4 +1,5 @@
 import { z } from "zod/v4";
+import { ColorGradeSchema } from "./color-grade";
 import {
   LayoutSchema,
   SceneAnchorSchema,
@@ -142,6 +143,19 @@ export const SceneOverrideSchema = z.object({
       dx: z.number().optional(),
       /** `false` switches the automatic idle-zoom layer off for this scene. */
       autoZoom: z.boolean().optional(),
+      /**
+       * Audio gain for this window's footage, 1 = as recorded (field report
+       * 2026-08-31: one concatenated clip was recorded quieter than the
+       * rest). Lives inside `video` on purpose — it is a property of this
+       * window's playback, and the key already merges per scene, inherits
+       * across split halves, and has patch/clear plumbing. 0 mutes. Above 1
+       * amplifies — in the render via allowAmplificationDuringRender, and in
+       * the preview via the Player's own WebAudio gain (Remotion ≥4.0.5xx,
+       * use-amplification). Max 4: a field clip arrived quiet enough that 2x
+       * did not reach its neighbours (2026-08-31); past 4x you are boosting
+       * noise floor, not speech.
+       */
+      volume: z.number().min(0).max(4).optional(),
     })
     .optional(),
   /**
@@ -527,6 +541,24 @@ export type SfxAddedPlacement = z.infer<typeof SfxAddedPlacementSchema>;
 export const OverrideDocSchema = z.object({
   /** Global style tokens — the look is a system, so these are not per-element. */
   theme: ThemeSchema.partial().default({}),
+  /**
+   * Doc-global color grade — the `ColorGradeSchema` shape, or `false` for
+   * "explicitly no grade on this project". Doc-global like `theme`: a grade
+   * is one decision about the whole output, not a per-scene key. Optional
+   * with NO default (the `captionsHidden` rule) so every overrides.json
+   * written before the key existed parses byte-identically — but UNLIKE
+   * `captionsHidden`, an explicit `false` is meaningful and kept: it
+   * disables a config-level default grade for this one project, which
+   * deleting the key cannot express (absent means "let the flag, then the
+   * config, decide" — `resolveProductionColorGrade` in produce.ts owns that
+   * precedence). Schema-valid is not yet USABLE: an unknown preset id passes
+   * here (the schema cannot list what exists without going stale) and is
+   * caught by `resolveColorGrade` at the consumer, where it warns and falls
+   * through to the next layer instead of failing the whole doc. Timeless —
+   * no seconds anywhere — so `remapOverridesThroughRecut`'s `...doc` spreads
+   * carry it through a recut untouched.
+   */
+  colorGrade: z.union([ColorGradeSchema, z.literal(false)]).optional(),
   /**
    * Captions OFF for the whole video. Doc-global like `theme`, deliberately
    * NOT a per-scene key: visibility is one decision about the output —

package/src/recut.ts

@@ -269,6 +269,11 @@ export function resolveCutSourceRanges(
  * user cut exactly like an automatic one, with no separate report path
  * needed for "what got removed."
  */
+/** See the sliver comment inside `subtractRangesFromCutlist` — a keep this
+ * short only ever comes from rounded cut edges meeting full-precision span
+ * floats, and it crashes the Remotion player if it survives. */
+const SLIVER_EPS = 0.002;
+
 export function subtractRangesFromCutlist(
   cutlist: readonly Segment[],
   ranges: readonly { start: number; end: number }[],
@@ -292,11 +297,35 @@ export function subtractRangesFromCutlist(
       const overlapStart = Math.max(cursor, r.start);
       const overlapEnd = Math.min(seg.srcOut, r.end);
       if (overlapStart >= overlapEnd) continue;
-      if (overlapStart > cursor) out.push({ srcIn: cursor, srcOut: overlapStart, kind: "keep" });
-      out.push({ srcIn: overlapStart, srcOut: overlapEnd, kind: "remove", reason: "user", confidence: 1 });
+      // A keep sliver shorter than SLIVER_EPS joins the removal instead of
+      // surviving as its own segment (2026-08-31, the ADK crash): the cut
+      // writers round `src` to 3 decimals while the cutlist keeps full float
+      // precision, so the honest set difference can leave a keep of ~100µs.
+      // EdlVideo rounds both ends of such a span to the SAME frame and
+      // Remotion throws ("trimAfter must be greater than trimBefore"),
+      // blanking the whole player — in the preview AND the next render.
+      // 2ms covers the worst rounding drift (0.5ms per edge) and is far
+      // under one frame at any real fps, so nothing watchable is lost.
+      if (overlapStart - cursor >= SLIVER_EPS) {
+        out.push({ srcIn: cursor, srcOut: overlapStart, kind: "keep" });
+        out.push({ srcIn: overlapStart, srcOut: overlapEnd, kind: "remove", reason: "user", confidence: 1 });
+      } else {
+        out.push({ srcIn: cursor, srcOut: overlapEnd, kind: "remove", reason: "user", confidence: 1 });
+      }
       cursor = overlapEnd;
     }
-    if (cursor < seg.srcOut) out.push({ srcIn: cursor, srcOut: seg.srcOut, kind: "keep" });
+    if (seg.srcOut - cursor >= SLIVER_EPS) {
+      out.push({ srcIn: cursor, srcOut: seg.srcOut, kind: "keep" });
+    } else if (cursor < seg.srcOut) {
+      // Tail sliver: extend the removal that ends at `cursor` (there always
+      // is one — cursor only advances past a pushed removal).
+      const last = out[out.length - 1];
+      if (last && last.kind === "remove" && last.srcOut === cursor) {
+        out[out.length - 1] = { ...last, srcOut: seg.srcOut };
+      } else {
+        out.push({ srcIn: cursor, srcOut: seg.srcOut, kind: "remove", reason: "user", confidence: 1 });
+      }
+    }
   }
   return out;
 }

package/src/scene-schema.ts

@@ -146,6 +146,9 @@ export const SceneCueSchema = z
       dx: z.number().optional(),
       /** `false` switches the automatic idle-zoom layer off for this scene. */
       autoZoom: z.boolean().optional(),
+      /** Audio gain for this window, 1 = as recorded — mirror of
+       * `SceneOverrideSchema.video.volume`, which owns the argument. */
+      volume: z.number().min(0).max(4).optional(),
     })
     .optional(),
   /**