davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/server/exposure-level.mjs

@@ -0,0 +1,129 @@
+/**
+ * Clip exposure/balance LEVELING — compute a per-clip *general* offset (per-channel
+ * gain) toward a group hero from measured frame stats, and emit a round-trip-asserted
+ * Primary-Balance DRX (the series' node style, not flat CDL).
+ *
+ * LOCAL: ffmpeg-extracted PNG frames -> sharp pixel means -> arithmetic -> drx codec.
+ * No Resolve, no LLM vision. Frame extraction + grade APPLY are the caller's job
+ * (Resolve scripting API). This module is the deterministic core.
+ *
+ * Modes:
+ * within_camera_mean (default) — VALID only for one camera's drift over a record
+ * (same framing). Matches each clip's per-channel mean to the group hero.
+ * scene_aware / skin_match — NOT IMPLEMENTED (throws). overall-mean is wrong across
+ * different shots (b-roll) or different framings/cameras (use skin-match there).
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import { drxTool } from './tools/drx.mjs';
+import { provenanceLabel, gist } from './node-provenance.mjs';
+
+const require = createRequire(import.meta.url);
+function loadSharp() {
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error("exposure-level needs the optional dep 'sharp' (frame stats). Install: npm i sharp");
+  }
+}
+
+const luma = (m) => 0.2126 * m.r + 0.7152 * m.g + 0.0722 * m.b;
+const clamp = (x, lo, hi) => Math.max(lo, Math.min(hi, x));
+const mean = (a) => a.reduce((x, y) => x + y, 0) / a.length;
+const std = (a) => {
+  const m = mean(a);
+  return Math.sqrt(mean(a.map((x) => (x - m) ** 2)));
+};
+
+/** Per-channel mean (0..max) of a PNG. */
+export async function measureMeanRGB(pngPath) {
+  const s = await loadSharp()(pngPath).stats();
+  return { r: s.channels[0].mean, g: s.channels[1].mean, b: s.channels[2].mean };
+}
+
+/** Generate a Primary-Balance DRX for a per-channel gain, then decode it and THROW if
+ * a non-unity grade came back empty (the silent-empty bug guard). Returns the DRX path. */
+export async function generateAssertedGainDRX(gain, label, outPath) {
+  // gain values are raw multipliers -> pin space:'drx' (UI happens to be 1:1 for gain,
+  // but the pin keeps this emitter immune to the space default).
+  //
+  // Resolve renders the RGB gain wheels as COLOR BALANCE only: the per-channel values
+  // are luma-renormalized at render time, so a uniform [1.3,1.3,1.3] with master 1 is a
+  // NO-OP (live-validated 2026-07-03, DaVinci YRGB/Rec709). The achromatic level must be
+  // carried by gain.master. Emit master = luma-weighted common gain; keep the channels
+  // absolute — Resolve's own renormalization then yields exactly the intended per-channel
+  // multipliers (master × ch/luma(ch) == ch).
+  const master = 0.2126 * gain.r + 0.7152 * gain.g + 0.0722 * gain.b;
+  await drxTool.handler({ action: 'generate', args: { gradeParams: { space: 'drx', gain: [gain.r, gain.g, gain.b, master] }, metadata: { label }, outputPath: outPath } });
+  const back = await drxTool.handler({ action: 'parse', args: { content: fs.readFileSync(outPath, 'utf8') } });
+  const got = (back.nodes || []).flatMap((n) => (n.correctors || []).flatMap((c) => c.parameters || [])).filter((p) => /gain\.(r|g|b)/i.test(p.name)).length;
+  const nonUnity = [gain.r, gain.g, gain.b].some((v) => Math.abs(v - 1) > 0.002);
+  if (nonUnity && got === 0) throw new Error(`round-trip assert FAILED: ${label} generated an EMPTY grade (gain ${JSON.stringify(gain)})`);
+  return outPath;
+}
+
+/**
+ * @param {Array<{id:string|number, png:string, group:string}>} clips
+ * @param {{outDir:string, mode?:string, clampGain?:[number,number], maxCorrWarn?:number}} opts
+ * @returns {Promise<{grades:Array, report:Object, warnings:string[]}>}
+ */
+export async function computeLevels(clips, opts = {}) {
+  const mode = opts.mode || 'within_camera_mean';
+  if (mode !== 'within_camera_mean') {
+    throw new Error(
+      `mode '${mode}' not implemented. within_camera_mean only (overall-mean is invalid across different shots/cameras — use skin-match/scene-cluster, TODO).`,
+    );
+  }
+  const [lo, hi] = opts.clampGain || [0.5, 2];
+  const maxCorrWarn = opts.maxCorrWarn ?? 0.12; // flag >12% as likely over-correction
+  if (!opts.outDir) throw new Error('opts.outDir required');
+  fs.mkdirSync(opts.outDir, { recursive: true });
+
+  const byGroup = new Map();
+  for (const c of clips) {
+    if (!byGroup.has(c.group)) byGroup.set(c.group, []);
+    byGroup.get(c.group).push(c);
+  }
+
+  const grades = [];
+  const report = {};
+  const warnings = [];
+  for (const [group, gclips] of byGroup) {
+    for (const c of gclips) {
+      try {
+        c.mean = await measureMeanRGB(c.png);
+        c.luma = luma(c.mean);
+      } catch {
+        c.mean = null;
+      }
+    }
+    const valid = gclips.filter((c) => c.mean);
+    if (!valid.length) {
+      report[group] = { error: 'no measurable frames' };
+      continue;
+    }
+    const H = valid[0].mean; // hero = first clip in group order
+    const lr = valid.map((c) => c.luma);
+    let maxCorr = 0;
+    for (const c of valid) {
+      const gain = { r: clamp(H.r / c.mean.r, lo, hi), g: clamp(H.g / c.mean.g, lo, hi), b: clamp(H.b / c.mean.b, lo, hi) };
+      const corr = Math.max(...['r', 'g', 'b'].map((k) => Math.abs(gain[k] - 1)));
+      maxCorr = Math.max(maxCorr, corr);
+      const drxPath = `${opts.outDir}/${group}_${c.id}.drx`;
+      await generateAssertedGainDRX(gain, provenanceLabel('exposure_level', { source: `hero:${valid[0].id}`, gist: gist('gain', gain) }), drxPath);
+      grades.push({ id: c.id, group, gain, correctionPct: +(100 * corr).toFixed(2), drxPath, isHero: c === valid[0] });
+    }
+    report[group] = {
+      clips: valid.length,
+      hero_id: valid[0].id,
+      luma_pct_std: +((100 * std(lr)) / mean(lr)).toFixed(2),
+      luma_pct_range: +((100 * (Math.max(...lr) - Math.min(...lr))) / mean(lr)).toFixed(2),
+      max_correction_pct: +(100 * maxCorr).toFixed(2),
+    };
+    if (maxCorr > maxCorrWarn)
+      warnings.push(
+        `${group}: max correction ${(100 * maxCorr).toFixed(1)}% > ${(100 * maxCorrWarn).toFixed(0)}% — likely NOT one-camera drift (different shots?). Review before applying.`,
+      );
+  }
+  return { grades, report, warnings };
+}

package/resolve-advanced/server/extract-frames.mjs

@@ -0,0 +1,196 @@
+/**
+ * extract_frames (Phase-1a) — the missing front door. ffmpeg-extract DISPLAY-REFERRED
+ * frames at oracle/midpoint/TC positions so the whole grading catalog is usable standalone
+ * (today extraction is "the caller's job").
+ *
+ * THE CRUX is the working space (cross-craft review, hard rule): the matchers' skin/tone
+ * gates assume Rec.709/sRGB. SLog3 measured raw is garbage, and a caller-supplied-CDL
+ * SLog3→709 approximation is DANGEROUS (you'd match the approximation's artifacts). So this
+ * tool HARD-REFUSES a log/scene-referred source — it never approximates. Accepted:
+ *   - a source ffprobe reports as a known DISPLAY transfer (bt709/601/sRGB/HLG/PQ), or
+ *   - an explicit display-referred proxy/render path (opts.proxy / clip.proxy), or
+ *   - an explicit caller assertion `displayReferred:true` when ffprobe can't tell (unknown).
+ * A known LOG transfer, or 'log' anywhere in the stream tags → THROW. Unknown + no assertion
+ * → THROW (skip-not-fake). Resolve against real camera-log footage with a post-ODT render.
+ *
+ * Silent-lie guard: assert the extracted PNG has bytes>0 (an empty file is the empty-green lie).
+ * Deps: ffmpeg + ffprobe on PATH (peer dep; not bundled — GPL). No Resolve, no LLM.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { requireFfmpeg } from './capabilities.mjs';
+
+// color_transfer values that are DISPLAY-referred (SDR + HDR display). Camera log
+// (SLog3/LogC/RedLog) is NOT in ffmpeg's enum — it shows as 'unknown' → we refuse unless asserted.
+const DISPLAY_TRANSFERS = new Set([
+  'bt709',
+  'smpte170m',
+  'bt470m',
+  'bt470bg',
+  'gamma22',
+  'gamma28',
+  'iec61966-2-1', // sRGB
+  'srgb',
+  'bt2020-10',
+  'bt2020-12',
+  'smpte2084', // PQ (HDR display-referred)
+  'arib-std-b67', // HLG (HDR display-referred)
+]);
+// Explicitly scene-referred / camera-log transfers → hard refuse.
+const LOG_TRANSFERS = new Set(['log100', 'log316']);
+// Known DISPLAY matrices — a fallback display signal when the transfer tag was dropped by the
+// muxer (common: libx264/mp4 keeps color_space but not color_transfer). A Rec.709/601 matrix
+// strongly implies display-referred SDR. NOT bt2020nc (wide-gamut; ambiguous) — stay conservative.
+const DISPLAY_MATRICES = new Set(['bt709', 'smpte170m', 'bt470bg', 'fcc', 'smpte240m']);
+
+/** Probe a media file's video stream: colorspace tags + frame count + fps. */
+export function probeStream(source, { ffprobe = 'ffprobe' } = {}) {
+  const r = spawnSync(
+    ffprobe,
+    [
+      '-v',
+      'error',
+      '-select_streams',
+      'v:0',
+      '-show_entries',
+      'stream=color_transfer,color_space,color_primaries,nb_frames,r_frame_rate,duration:stream_tags=color_transfer',
+      '-of',
+      'json',
+      source,
+    ],
+    { encoding: 'utf8', timeout: 15000 },
+  );
+  if (r.status !== 0) throw new Error(`ffprobe failed on ${source}: ${(r.stderr || '').slice(-300)}`);
+  const j = JSON.parse(r.stdout || '{}');
+  const s = (j.streams && j.streams[0]) || {};
+  const [num, den] = String(s.r_frame_rate || '0/1')
+    .split('/')
+    .map(Number);
+  const fps = den ? num / den : 0;
+  let frameCount = Number(s.nb_frames) || 0;
+  if (!frameCount && s.duration && fps) frameCount = Math.round(Number(s.duration) * fps);
+  return {
+    colorTransfer: s.color_transfer || (s.tags && s.tags.color_transfer) || 'unknown',
+    colorSpace: s.color_space || 'unknown',
+    colorPrimaries: s.color_primaries || 'unknown',
+    fps,
+    frameCount,
+    duration: Number(s.duration) || 0,
+  };
+}
+
+/**
+ * Decide if a source is safe (display-referred) to measure, or must be refused.
+ * @returns {{ok:true, transfer:string, reason:string} | {ok:false, transfer:string, reason:string}}
+ */
+export function assessColorspace(probe, opts = {}) {
+  const t = String(probe.colorTransfer || 'unknown').toLowerCase();
+  if (t.includes('log') || LOG_TRANSFERS.has(t)) {
+    return {
+      ok: false,
+      transfer: t,
+      reason: `source transfer '${t}' is LOG/scene-referred — refuse (no approximation; use a post-ODT display-referred render/proxy)`,
+    };
+  }
+  if (DISPLAY_TRANSFERS.has(t)) return { ok: true, transfer: t, reason: `display-referred transfer '${t}'` };
+  // Transfer tag missing/unknown but a known display MATRIX survived → treat as display-referred SDR.
+  const cs = String(probe.colorSpace || 'unknown').toLowerCase();
+  if (DISPLAY_MATRICES.has(cs))
+    return { ok: true, transfer: t, matrix: cs, reason: `transfer '${t}' unknown but display matrix '${cs}' → display-referred SDR` };
+  // Unknown: camera log commonly probes as 'unknown'. Only proceed if the caller asserts.
+  if (opts.displayReferred) return { ok: true, transfer: t, reason: `transfer '${t}' unknown; caller asserts displayReferred` };
+  return {
+    ok: false,
+    transfer: t,
+    reason: `source transfer '${t}' is UNKNOWN — camera log often probes as unknown. Point at a display-referred proxy/render, or pass displayReferred:true if you KNOW it's Rec.709/sRGB.`,
+  };
+}
+
+/** Resolve an `at` position to a 0-based frame index. */
+export function resolvePosition(at, probe) {
+  if (typeof at === 'number') return Math.max(0, Math.round(at));
+  if (at == null || at === 'midpoint') return Math.max(0, Math.floor((probe.frameCount || 1) / 2));
+  if (typeof at === 'string' && at.includes(':')) {
+    // TC HH:MM:SS:FF → frame index via fps
+    const parts = at.split(':').map(Number);
+    if (parts.length === 4 && probe.fps) {
+      const [h, m, s, f] = parts;
+      return Math.max(0, Math.round((h * 3600 + m * 60 + s) * probe.fps) + f);
+    }
+  }
+  throw new Error(`extract_frames: cannot resolve position '${at}'`);
+}
+
+function runFfmpegToFile(args, ffmpegPath) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(ffmpegPath, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    const err = [];
+    proc.stderr.on('data', (d) => err.push(d));
+    proc.on('error', reject);
+    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`ffmpeg exited ${code}: ${Buffer.concat(err).toString().slice(-300)}`))));
+  });
+}
+
+/**
+ * @param {Array<{id:string|number, source:string, at?:any, proxy?:string, displayReferred?:boolean}>} clips
+ * @param {{outDir:string, ffmpeg?:string, ffprobe?:string, displayReferred?:boolean}} opts
+ * @returns {Promise<{frames:Object, skipped:Array, warnings:string[]}>}  frames = { id → png path }
+ */
+export async function extractFrames(clips, opts = {}) {
+  requireFfmpeg();
+  if (!opts.outDir) throw new Error('opts.outDir required');
+  fs.mkdirSync(opts.outDir, { recursive: true });
+  const ffmpeg = opts.ffmpeg || 'ffmpeg';
+  const ffprobe = opts.ffprobe || 'ffprobe';
+  const frames = {};
+  const skipped = [];
+  const warnings = [];
+
+  for (const c of clips) {
+    const src = c.proxy || opts.proxy || c.source;
+    let probe;
+    try {
+      probe = probeStream(src, { ffprobe });
+    } catch (e) {
+      skipped.push({ id: c.id, reason: `probe failed: ${e.message}` });
+      continue;
+    }
+    const assess = assessColorspace(probe, { displayReferred: c.displayReferred ?? opts.displayReferred });
+    if (!assess.ok) {
+      // HARD refuse — never approximate a log source into a display-referred measurement.
+      skipped.push({ id: c.id, reason: assess.reason, transfer: assess.transfer });
+      continue;
+    }
+    let frameIdx;
+    try {
+      frameIdx = resolvePosition(c.at, probe);
+    } catch (e) {
+      skipped.push({ id: c.id, reason: e.message });
+      continue;
+    }
+    const outPng = path.join(opts.outDir, `${c.id}.png`);
+    const args = ['-v', 'error', '-i', src, '-vf', `select=eq(n\\,${frameIdx})`, '-vframes', '1', '-y', outPng];
+    try {
+      await runFfmpegToFile(args, ffmpeg);
+    } catch (e) {
+      skipped.push({ id: c.id, reason: `extract failed: ${e.message}` });
+      continue;
+    }
+    // Silent-lie guard: assert bytes were actually written.
+    let sz = 0;
+    try {
+      sz = fs.statSync(outPng).size;
+    } catch {
+      sz = 0;
+    }
+    if (!sz) {
+      skipped.push({ id: c.id, reason: `extracted 0 bytes (frame ${frameIdx} out of range?)` });
+      continue;
+    }
+    frames[c.id] = outPng;
+    if (assess.transfer === 'smpte2084' || assess.transfer === 'arib-std-b67')
+      warnings.push(`${c.id}: HDR transfer '${assess.transfer}' — display-referred but the SDR matchers' 16–235 assumptions differ; verify.`);
+  }
+  return { frames, skipped, warnings };
+}

package/resolve-advanced/server/ffprobe-media.mjs

@@ -0,0 +1,88 @@
+/**
+ * ffprobe-media — one normalized media-probe helper the deliverable/media QC tools share.
+ * Wraps `ffprobe -show_streams -show_format` into a compact { video, audio[], format } shape.
+ * Deps: ffprobe on PATH (peer; not bundled — GPL). Deterministic read; no Resolve, no LLM.
+ */
+import { spawnSync } from 'node:child_process';
+import { requireFfmpeg } from './capabilities.mjs';
+
+/** Parse an "a/b" rational string → number (0 on divide-by-zero). */
+export function ratio(s) {
+  const [n, d] = String(s || '0/1')
+    .split('/')
+    .map(Number);
+  return d ? n / d : 0;
+}
+
+/**
+ * Probe a media file. Returns null on failure (skip-not-fake at the caller).
+ * @param {string} file
+ * @param {{ffprobe?:string}} [opts]
+ */
+export function probeMedia(file, opts = {}) {
+  requireFfmpeg();
+  const ffprobe = opts.ffprobe || 'ffprobe';
+  const r = spawnSync(ffprobe, ['-v', 'error', '-show_streams', '-show_format', '-of', 'json', file], {
+    encoding: 'utf8',
+    timeout: 30000,
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  if (r.status !== 0) return null;
+  let j;
+  try {
+    j = JSON.parse(r.stdout || '{}');
+  } catch {
+    return null;
+  }
+  const streams = j.streams || [];
+  const vs = streams.find((s) => s.codec_type === 'video') || null;
+  const as = streams.filter((s) => s.codec_type === 'audio');
+  const fmt = j.format || {};
+  const fps = vs ? ratio(vs.r_frame_rate) : 0;
+  let frameCount = vs ? Number(vs.nb_frames) || 0 : 0;
+  const duration = Number(fmt.duration) || (vs ? Number(vs.duration) : 0) || 0;
+  if (!frameCount && duration && fps) frameCount = Math.round(duration * fps);
+  const video = vs
+    ? {
+        codec: vs.codec_name || 'unknown',
+        profile: vs.profile != null ? String(vs.profile) : null,
+        width: vs.width || 0,
+        height: vs.height || 0,
+        fps: +fps.toFixed(4),
+        fpsExact: vs.r_frame_rate,
+        fieldOrder: vs.field_order || 'progressive',
+        scan: vs.field_order && vs.field_order !== 'progressive' ? 'interlaced' : 'progressive',
+        pixFmt: vs.pix_fmt || 'unknown',
+        colorPrimaries: vs.color_primaries || 'unknown',
+        colorTransfer: vs.color_transfer || 'unknown',
+        colorMatrix: vs.color_space || 'unknown',
+        colorRange: vs.color_range || 'unknown',
+        bitDepth: vs.bits_per_raw_sample ? Number(vs.bits_per_raw_sample) : null,
+        sampleAspect: vs.sample_aspect_ratio || '1:1',
+        displayAspect: vs.display_aspect_ratio || null,
+        frameCount,
+      }
+    : null;
+  const audio = as.map((a) => ({
+    codec: a.codec_name || 'unknown',
+    channels: a.channels || 0,
+    channelLayout: a.channel_layout || 'unknown',
+    sampleRate: Number(a.sample_rate) || 0,
+    bitDepth: a.bits_per_raw_sample ? Number(a.bits_per_raw_sample) : a.bits_per_sample || null,
+  }));
+  // Timecode: format tag, then any stream tag (camera TC usually rides a data/video stream tag).
+  const timecode = (fmt.tags && fmt.tags.timecode) || streams.map((s) => s.tags && s.tags.timecode).find(Boolean) || null;
+  return {
+    video,
+    audio,
+    format: {
+      container: (fmt.format_name || '').split(',')[0] || 'unknown',
+      duration: +duration.toFixed(4),
+      size: Number(fmt.size) || 0,
+      bitRate: Number(fmt.bit_rate) || 0,
+      nbStreams: streams.length,
+      tags: fmt.tags || {},
+      timecode,
+    },
+  };
+}

package/resolve-advanced/server/gamut-legal.mjs

@@ -0,0 +1,112 @@
+/**
+ * Broadcast-legal / clipping QC (C3 `gamut_legal`).
+ *
+ * Pure MEASUREMENT — no grade emitted. On display-referred frames it reports, per
+ * channel, how much of the picture sits outside video-legal range (default 8-bit
+ * 16–235) and how much is HARD-CLIPPED (==0 crushed / ==255 blown), then gives each
+ * clip a pass/fail against a tolerance. The delivery-QC signal before master render
+ * (a common master is Rec.709 Gamma 2.4 — many broadcasters want video-legal).
+ *
+ * Caveat: superwhite/sub-black detail already clipped INTO the PNG can't be recovered
+ * here — this flags what the frame shows. For true scope-legal QC use the timeline
+ * scopes; this is the cheap local pre-check. LOCAL & deterministic; no Resolve.
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+function loadSharp() {
+  try {
+    return require('sharp');
+  } catch {
+    throw new Error("gamut-legal needs the optional dep 'sharp'. Install: npm i sharp");
+  }
+}
+const pct = (n, d) => (d ? +((100 * n) / d).toFixed(3) : 0);
+
+/**
+ * @returns {Promise<{channels:Object, illegalPct:number, clippedPct:number, nTotal:number}|null>}
+ */
+export async function measureLegal(pngPath, opts = {}) {
+  const sharp = loadSharp();
+  const low = opts.low ?? 16,
+    high = opts.high ?? 235,
+    maxSide = opts.maxSide ?? 480;
+  let data, ch;
+  try {
+    const out = await sharp(pngPath).resize(maxSide, maxSide, { fit: 'inside', kernel: 'nearest' }).raw().toBuffer({ resolveWithObject: true });
+    data = out.data;
+    ch = out.info.channels;
+  } catch {
+    return null;
+  }
+  const nTotal = Math.floor(data.length / ch);
+  const names = ['r', 'g', 'b'];
+  const acc = names.map(() => ({ min: 255, max: 0, below: 0, above: 0, at0: 0, at255: 0 }));
+  let illegalPx = 0,
+    clippedPx = 0;
+  for (let i = 0; i < data.length; i += ch) {
+    let illegal = false,
+      clipped = false;
+    for (let c = 0; c < 3; c++) {
+      const v = data[i + c],
+        a = acc[c];
+      if (v < a.min) a.min = v;
+      if (v > a.max) a.max = v;
+      if (v < low) {
+        a.below++;
+        illegal = true;
+      } else if (v > high) {
+        a.above++;
+        illegal = true;
+      }
+      if (v === 0) {
+        a.at0++;
+        clipped = true;
+      } else if (v === 255) {
+        a.at255++;
+        clipped = true;
+      }
+    }
+    if (illegal) illegalPx++;
+    if (clipped) clippedPx++;
+  }
+  const channels = {};
+  names.forEach((n, c) => {
+    const a = acc[c];
+    channels[n] = {
+      min: a.min,
+      max: a.max,
+      belowPct: pct(a.below, nTotal),
+      abovePct: pct(a.above, nTotal),
+      crushedPct: pct(a.at0, nTotal),
+      blownPct: pct(a.at255, nTotal),
+    };
+  });
+  return { channels, illegalPct: pct(illegalPx, nTotal), clippedPct: pct(clippedPx, nTotal), nTotal };
+}
+
+/**
+ * @param {Array<{id:string|number, png:string}>} clips
+ * @param {{low?:number, high?:number, maxIllegalPct?:number}} opts
+ * @returns {Promise<{report:Object, warnings:string[], skipped:Array}>}
+ */
+export async function computeGamutLegal(clips, opts = {}) {
+  const maxIllegalPct = opts.maxIllegalPct ?? 1.0; // tolerate up to 1% out-of-legal by default
+  const report = {};
+  const warnings = [];
+  const skipped = [];
+  for (const c of clips) {
+    const m = await measureLegal(c.png, opts);
+    if (!m) {
+      skipped.push({ id: c.id, reason: 'unreadable frame' });
+      continue;
+    }
+    const pass = m.illegalPct <= maxIllegalPct;
+    report[c.id] = { pass, illegalPct: m.illegalPct, clippedPct: m.clippedPct, channels: m.channels };
+    if (!pass)
+      warnings.push(
+        `${c.id}: ${m.illegalPct}% out-of-legal (>${maxIllegalPct}% tol) [low ${opts.low ?? 16}/high ${opts.high ?? 235}] — review before broadcast-legal delivery.`,
+      );
+  }
+  return { report, warnings, skipped };
+}