davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/vendor/conform-qc/parse/xmeml-geometry.js

@@ -0,0 +1,256 @@
+'use strict';
+
+/**
+ * parse/xmeml-geometry.js — the conform-field capture pass (spec §4).
+ *
+ * editorial-core's existing DTO drops every conform-critical field; this is the
+ * sibling extractor (cf. parsers/xmeml-tc.js) that captures the geometry the
+ * Oracle needs, keyed by clip, with FILE-IDS RESOLVED FIRST (non-negotiable #6:
+ * 269 of this reel's 334 <file> references are self-closing `<file id=".."/>`
+ * that only make sense once mapped back to their full definition).
+ *
+ * Output per clip:
+ *   { seqstart, seqend, xml_in, xml_out, pproTicksIn, pproTicksOut,
+ *     is_subclip, subclip_startoffset, scale_premiere, fileId,
+ *     source_basename, srcW, srcH }
+ *
+ * Pure: takes an XML string, returns plain data. No IO.
+ */
+
+const { XMLParser } = require('fast-xml-parser');
+
+const PARSER = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: '@_',
+  parseTagValue: true,
+  trimValues: true,
+});
+
+function asArray(x) {
+  if (x === undefined || x === null) return [];
+  return Array.isArray(x) ? x : [x];
+}
+
+function num(v) {
+  if (v === undefined || v === null || v === '') return null;
+  const n = Number(v);
+  return Number.isNaN(n) ? null : n;
+}
+
+/** Decode a file://… pathurl (or fall back to a name) to a basename. */
+function basenameFromFile(fileDef) {
+  const raw = fileDef.pathurl != null ? String(fileDef.pathurl) : null;
+  if (raw) {
+    let p = raw;
+    try {
+      p = decodeURIComponent(p);
+    } catch (e) {
+      /* leave encoded if malformed */
+    }
+    const idx = p.lastIndexOf('/');
+    return idx >= 0 ? p.slice(idx + 1) : p;
+  }
+  return fileDef.name != null ? String(fileDef.name) : null;
+}
+
+/** Extract the source W/H from a full <file> definition's video samplechars. */
+function sourceDims(fileDef) {
+  const sc =
+    fileDef &&
+    fileDef.media &&
+    fileDef.media.video &&
+    fileDef.media.video.samplecharacteristics;
+  if (!sc) return { srcW: null, srcH: null };
+  return { srcW: num(sc.width), srcH: num(sc.height) };
+}
+
+/**
+ * Walk the whole tree collecting FULL <file> definitions (those carrying media
+ * or a pathurl) into an id -> def map, so self-closing references resolve.
+ */
+function collectFileDefs(node, map) {
+  if (node === null || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    for (const n of node) collectFileDefs(n, map);
+    return;
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'file') {
+      for (const f of asArray(node[key])) {
+        if (f && typeof f === 'object' && f['@_id'] != null) {
+          const id = String(f['@_id']);
+          const isFullDef = f.media !== undefined || f.pathurl !== undefined;
+          if (isFullDef && !map[id]) {
+            const { srcW, srcH } = sourceDims(f);
+            map[id] = { basename: basenameFromFile(f), srcW, srcH };
+          }
+        }
+      }
+    }
+    collectFileDefs(node[key], map);
+  }
+}
+
+/** Find a filter parameter object by parameterid (case-insensitive), or null. */
+function findParam(clipitem, parameterid) {
+  const want = String(parameterid).toLowerCase();
+  for (const filter of asArray(clipitem.filter)) {
+    const effect = filter && filter.effect;
+    if (!effect) continue;
+    for (const p of asArray(effect.parameter)) {
+      if (p && String(p.parameterid).toLowerCase() === want) return p;
+    }
+  }
+  return null;
+}
+
+/** Scalar value of a parameter, or null. */
+function scalarParam(clipitem, parameterid) {
+  const p = findParam(clipitem, parameterid);
+  return p ? num(p.value) : null;
+}
+
+/**
+ * Capture the Time-Remap speed. A clip with no Time Remap is un-retimed; we
+ * report 100 (%) so downstream code has a number, and null only when truly
+ * absent and we cannot assume. Premiere encodes 50% slow-mo as a non-100 speed
+ * here AND as ticks/tpf != <in> in the Oracle — the two must agree.
+ */
+function captureSpeed(clipitem) {
+  const p = findParam(clipitem, 'speed');
+  if (!p) return 100; // no Time Remap => normal speed
+  const v = num(p.value);
+  return v == null ? 100 : v;
+}
+
+/** A reversed clip carries a Time Remap with parameter `reverse` = TRUE. */
+function captureReverse(clipitem) {
+  const p = findParam(clipitem, 'reverse');
+  if (!p) return false;
+  return String(p.value).toUpperCase() === 'TRUE';
+}
+
+/** Capture Basic-Motion center/rotation/crop (reframes + online/offline Y residual). */
+function captureTransform(clipitem) {
+  const center = findParam(clipitem, 'center');
+  const c = center && center.value ? center.value : null;
+  return {
+    center: c ? { h: num(c.horiz), v: num(c.vert) } : null,
+    rotation: scalarParam(clipitem, 'rotation'),
+    crop: {
+      left: scalarParam(clipitem, 'leftcrop'),
+      top: scalarParam(clipitem, 'topcrop'),
+      right: scalarParam(clipitem, 'rightcrop'),
+      bottom: scalarParam(clipitem, 'bottomcrop'),
+    },
+  };
+}
+
+/** The video-track clipitems, in order. */
+function videoClipitems(sequence) {
+  const tracks = asArray(
+    sequence && sequence.media && sequence.media.video && sequence.media.video.track,
+  );
+  const out = [];
+  for (const track of tracks) {
+    for (const ci of asArray(track.clipitem)) {
+      // A real clip has a record position + a source in-point.
+      if (ci && ci.start !== undefined && ci.in !== undefined) out.push(ci);
+    }
+  }
+  return out;
+}
+
+/** Capture video transitions (dissolves/wipes) across the sequence's video tracks. */
+function videoTransitions(sequence) {
+  const tracks = asArray(
+    sequence && sequence.media && sequence.media.video && sequence.media.video.track,
+  );
+  const out = [];
+  tracks.forEach((track, ti) => {
+    for (const tr of asArray(track.transitionitem)) {
+      if (!tr) continue;
+      const effect = tr.effect || {};
+      out.push({
+        track: ti + 1,
+        start: num(tr.start),
+        end: num(tr.end),
+        duration: num(tr.end) != null && num(tr.start) != null ? num(tr.end) - num(tr.start) : null,
+        alignment: tr.alignment != null ? String(tr.alignment) : null,
+        effectid: effect.effectid != null ? String(effect.effectid) : null,
+        category: effect.effectcategory != null ? String(effect.effectcategory) : null,
+        mediatype: effect.mediatype != null ? String(effect.mediatype) : null,
+        reverse: effect.reverse != null ? String(effect.reverse).toUpperCase() === 'TRUE' : false,
+      });
+    }
+  });
+  return out;
+}
+
+function sequenceInfo(sequence) {
+  const sc =
+    sequence &&
+    sequence.media &&
+    sequence.media.video &&
+    sequence.media.video.format &&
+    sequence.media.video.format.samplecharacteristics;
+  const rate = sc && sc.rate;
+  return {
+    name: sequence && sequence.name != null ? String(sequence.name) : null,
+    width: sc ? num(sc.width) : null,
+    height: sc ? num(sc.height) : null,
+    fps: rate ? num(rate.timebase) : null,
+  };
+}
+
+/**
+ * Parse an XMEML string into captured conform geometry.
+ * @param {string} xml
+ * @returns {{ sequence: object, fileDefs: object, clips: object[] }}
+ */
+function parseGeometry(xml) {
+  const doc = PARSER.parse(xml);
+  const sequence = doc && doc.xmeml && doc.xmeml.sequence;
+  if (!sequence) throw new Error('xmeml-geometry: no <xmeml><sequence> found');
+
+  // Pass 1 — resolve file-ids (non-negotiable #6) BEFORE reading clip fields.
+  const fileDefs = {};
+  collectFileDefs(doc, fileDefs);
+
+  // Pass 2 — capture per-clip geometry.
+  const clips = [];
+  for (const ci of videoClipitems(sequence)) {
+    const fileNode = ci.file;
+    const fileId = fileNode && fileNode['@_id'] != null ? String(fileNode['@_id']) : null;
+    const def = fileId ? fileDefs[fileId] : null;
+    const sub = ci.subclipinfo;
+    const startoffset = sub ? num(sub.startoffset) : null;
+    const endoffset = sub ? num(sub.endoffset) : null;
+    const transform = captureTransform(ci);
+    clips.push({
+      seqstart: num(ci.start),
+      seqend: num(ci.end),
+      xml_in: num(ci.in),
+      xml_out: num(ci.out),
+      pproTicksIn: num(ci.pproTicksIn),
+      pproTicksOut: num(ci.pproTicksOut),
+      is_subclip: startoffset != null,
+      subclip_startoffset: startoffset != null ? startoffset : 0,
+      subclip_endoffset: endoffset != null ? endoffset : 0,
+      scale_premiere: scalarParam(ci, 'scale'),
+      speed: captureSpeed(ci),
+      reverse: captureReverse(ci),
+      center: transform.center,
+      rotation: transform.rotation,
+      crop: transform.crop,
+      fileId,
+      source_basename: def ? def.basename : null,
+      srcW: def ? def.srcW : null,
+      srcH: def ? def.srcH : null,
+    });
+  }
+
+  return { sequence: sequenceInfo(sequence), fileDefs, clips, transitions: videoTransitions(sequence) };
+}
+
+module.exports = { parseGeometry, basenameFromFile };

package/resolve-advanced/vendor/conform-qc/reference/burnin-ocr.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * reference/burnin-ocr.js — Tier A ground truth (spec §7): read the source
+ * timecode + filename BURNED INTO a review render, so a cut is verified as
+ * "content matches AND came from the named source." This is the mechanism that
+ * recovers the true source of a mismatched cut (e.g. a reversed/subclip whose
+ * frame can't be trusted from the editorial offsets alone).
+ *
+ * Uses tesseract (system dep) with a dark-lift pre-pass (review renders are
+ * often temped dark) and optional MULTI-FRAME CONSENSUS (vote across frames) per
+ * the spec. OCR is noisy, so identity matching is FUZZY (token overlap), not
+ * exact — a misread camera/roll word still resolves because the distinctive
+ * tokens (roll/date) pin the source.
+ *
+ * tesseract is invoked as a subprocess; callers should skip-if-absent.
+ */
+
+const sharp = require('sharp');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Default burn-in regions (fractions of W/H) for a common review-render template.
+const DEFAULT_REGIONS = Object.freeze({
+  bottom: { x0: 0.0, y0: 0.93, x1: 1.0, y1: 1.0 }, // filename (left) + record TC (right)
+  topTc: { x0: 0.34, y0: 0.06, x1: 0.66, y1: 0.18 }, // centered source TC
+});
+
+const TC_RE = /\b(\d{2}:\d{2}:\d{2}[:;]\d{2})\b/;
+
+function tokenize(text) {
+  return String(text || '')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 2);
+}
+
+/** Fraction of the expected source-name tokens that appear in the OCR tokens. */
+function identityOverlap(ocrText, expectedName) {
+  const want = new Set(tokenize(expectedName));
+  if (want.size === 0) return 0;
+  const got = new Set(tokenize(ocrText));
+  let hit = 0;
+  for (const t of want) if (got.has(t)) hit += 1;
+  return hit / want.size;
+}
+
+async function ocrRegion(framePath, region, lift) {
+  const meta = await sharp(framePath).metadata();
+  const W = meta.width;
+  const H = meta.height;
+  const left = Math.max(0, Math.round(region.x0 * W));
+  const top = Math.max(0, Math.round(region.y0 * H));
+  const width = Math.min(W - left, Math.round((region.x1 - region.x0) * W));
+  const height = Math.min(H - top, Math.round((region.y1 - region.y0) * H));
+  let img = sharp(framePath).extract({ left, top, width, height }).greyscale().normalise();
+  if (lift && lift !== 1) img = img.linear(lift, 0).normalise();
+  const buf = await img.resize({ width: width * 2 }).png().toBuffer();
+  const tmp = path.join(os.tmpdir(), `cqc-ocr-${process.pid}-${left}-${top}.png`);
+  fs.writeFileSync(tmp, buf);
+  try {
+    return execFileSync('tesseract', [tmp, 'stdout', '--psm', '7'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+/**
+ * Read the burn-in from one frame (or several, for consensus).
+ * @param {string|string[]} frames  frame path(s)
+ * @param {object} opts { regions?, lift? }
+ * @returns {Promise<{ sourceTc: string|null, ocrText: string, perFrame: object[] }>}
+ */
+async function readBurnIn(frames, opts = {}) {
+  const list = Array.isArray(frames) ? frames : [frames];
+  const regions = { ...DEFAULT_REGIONS, ...(opts.regions || {}) };
+  const lift = opts.lift || 1;
+  const perFrame = [];
+  for (const f of list) {
+    const bottom = await ocrRegion(f, regions.bottom, lift);
+    let topTc = '';
+    try {
+      topTc = await ocrRegion(f, regions.topTc, lift);
+    } catch (e) {
+      /* top TC optional */
+    }
+    const tcMatch = (topTc.match(TC_RE) || bottom.match(TC_RE) || [])[1] || null;
+    perFrame.push({ frame: f, bottom, topTc, tc: tcMatch });
+  }
+  // Consensus: the most common non-null TC across frames; concatenated bottom text.
+  const tcVotes = {};
+  for (const r of perFrame) if (r.tc) tcVotes[r.tc] = (tcVotes[r.tc] || 0) + 1;
+  const sourceTc = Object.keys(tcVotes).sort((a, b) => tcVotes[b] - tcVotes[a])[0] || null;
+  const ocrText = perFrame.map((r) => r.bottom).join(' ');
+  return { sourceTc, ocrText, perFrame };
+}
+
+module.exports = { readBurnIn, identityOverlap, tokenize, DEFAULT_REGIONS, TC_RE };

package/resolve-advanced/vendor/conform-qc/reference/sidecar.js

@@ -0,0 +1,37 @@
+'use strict';
+
+/**
+ * reference/sidecar.js — Tier B ground truth (spec §7): a clean review render
+ * keyed by a TC sidecar (EDL / ALE / source-TC). Content is verified by frame;
+ * IDENTITY comes from the sidecar (no OCR). Lower-friction than Tier A when a
+ * burn-in isn't available but a sidecar is.
+ *
+ * Produces a referenceProvider(clip) for ops/verify — pure (takes the sidecar +
+ * a frame-path resolver; no IO of its own).
+ */
+
+/**
+ * @param {object[]|object} sidecar  entries { seqstart, sourceTc, sourceName, referenceFrame, derivedFrame?, label? }
+ *                                    (array, or an object keyed by seqstart)
+ * @param {(p:string)=>string} [resolveFramePath]  map a sidecar frame ref to a real path
+ * @returns {(clip:object)=>object|null} a verify referenceProvider
+ */
+function tcSidecarProvider(sidecar, resolveFramePath) {
+  const map = Array.isArray(sidecar)
+    ? Object.fromEntries(sidecar.map((e) => [e.seqstart, e]))
+    : sidecar || {};
+  const resolve = resolveFramePath || ((p) => p);
+  return function referenceProvider(clip) {
+    const e = map[clip.seqstart];
+    if (!e) return null; // no sidecar entry => Tier C for this cut
+    return {
+      referencePath: resolve(e.referenceFrame),
+      derivedPath: e.derivedFrame ? resolve(e.derivedFrame) : null,
+      tier: 'B',
+      label: e.label,
+      identity: { sourceTc: e.sourceTc || null, sourceName: e.sourceName || null },
+    };
+  };
+}
+
+module.exports = { tcSidecarProvider };

package/resolve-advanced/vendor/conform-qc/repair/analysis.js

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * repair/analysis.js — correctness checks + the proposed-timeline / V2-flag-track
+ * assembler (spec §9). Pure functions.
+ */
+
+/**
+ * Dupes / repeated source (§9): a correctness check, not a repair. Group clips
+ * by resolved source; report clusters where one source feeds many cuts.
+ * Returns [{ source, count, cutIds }] for sources used more than once.
+ */
+function detectDupes(clips, keyOf = (c) => c.source_basename) {
+  const groups = new Map();
+  for (const c of clips) {
+    const k = keyOf(c);
+    if (k == null) continue;
+    if (!groups.has(k)) groups.set(k, []);
+    groups.get(k).push(c.cutId != null ? c.cutId : c.seqstart);
+  }
+  return [...groups.entries()]
+    .filter(([, ids]) => ids.length > 1)
+    .map(([source, cutIds]) => ({ source, count: cutIds.length, cutIds }));
+}
+
+/**
+ * Build a PROPOSED corrected timeline + a V2 flag track from repair results
+ * (§9). Auto-applied deterministic fixes land in the corrected timeline;
+ * everything else (propose-only, auto-rejected, flag-v2, unrepairable) becomes
+ * ONE annotated V2 clip with a V1 gap — nothing is auto-applied silently.
+ *
+ * @param {object[]} results  [{ cutId, seqstart, repair: <ladder result> }]
+ * @returns {{ correctedTimeline: object[], v2Flags: object[], summary: object }}
+ */
+function proposeTimeline(results) {
+  const correctedTimeline = [];
+  const v2Flags = [];
+  for (const r of results) {
+    const rep = r.repair || {};
+    if (rep.mode === 'auto-apply' && rep.proposal && rep.proposal.fix) {
+      correctedTimeline.push({ cutId: r.cutId, seqstart: r.seqstart, applied: rep.proposal.fix, strategy: rep.strategy, v1Gap: false });
+    } else {
+      // Irreducible / needs review: keep a V1 gap and annotate one V2 clip.
+      correctedTimeline.push({ cutId: r.cutId, seqstart: r.seqstart, applied: null, v1Gap: true });
+      v2Flags.push({
+        cutId: r.cutId,
+        seqstart: r.seqstart,
+        mode: rep.mode || 'flag-v2',
+        klass: rep.klass || 'unrepairable',
+        note: rep.diagnosis || 'flagged for review',
+        proposedFix: rep.proposal ? rep.proposal.fix : null,
+      });
+    }
+  }
+  return {
+    correctedTimeline,
+    v2Flags,
+    summary: { cuts: results.length, autoApplied: correctedTimeline.filter((c) => !c.v1Gap).length, flagged: v2Flags.length },
+  };
+}
+
+module.exports = { detectDupes, proposeTimeline };

package/resolve-advanced/vendor/conform-qc/repair/index.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * repair/ — the repair strategy LADDER (spec §9).
+ *
+ * For a cut that failed verification, try strategies in order; the first that
+ * detects proposes a fix. The fix is RE-VERIFIED (re-sample + compare) before
+ * acceptance; deterministic strategies that re-verify clean ≥ gate auto-apply
+ * (§15), everything else is propose-only (human approves). The diagnosis class +
+ * outcome are recorded to ConformKnowledge so confidence improves with use.
+ *
+ * Unrepairable / low-confidence → flag to the V2 track (one annotated clip).
+ */
+
+const { ConformKnowledge } = require('../knowledge');
+const strategies = require('./strategies');
+
+const DEFAULT_ORDER = [
+  strategies.scaleDoubleCount,
+  strategies.subclipOffset,
+  strategies.ticksRetime,
+  strategies.staleRelink,
+];
+
+/**
+ * @param {object} opts {
+ *   order?            strategy list (default DEFAULT_ORDER)
+ *   knowledge?        a ConformKnowledge store (created if absent)
+ *   confidenceGate?   default 0.90 (§15 SSIM threshold)
+ *   reverify?(cut, proposal, ctx) -> Promise<{ ok:boolean, confidence:number }>  optional re-sample+compare
+ * }
+ */
+function makeRepairLadder(opts = {}) {
+  const order = opts.order || DEFAULT_ORDER;
+  const knowledge = opts.knowledge || new ConformKnowledge();
+  const gate = opts.confidenceGate != null ? opts.confidenceGate : 0.9;
+
+  async function repair(cut, ctx = {}) {
+    for (const s of order) {
+      if (!s.detect(cut, ctx)) continue;
+      const proposal = s.propose(cut, ctx);
+      const hasFix = proposal && proposal.fix != null;
+
+      // Re-verify the proposed fix if a verifier is injected; else trust the
+      // strategy's own confidence (deterministic strategies derive exact values).
+      let reverified = null;
+      let confidence = proposal && proposal.confidence != null ? proposal.confidence : null;
+      if (opts.reverify && hasFix) {
+        reverified = await opts.reverify(cut, proposal, ctx);
+        confidence = reverified.confidence;
+      }
+
+      const reverifyOk = reverified ? reverified.ok : true;
+      const accepted = hasFix && s.deterministic && reverifyOk && (confidence == null || confidence >= gate);
+      const mode = accepted ? 'auto-apply' : (hasFix ? (s.deterministic ? 'auto-rejected' : 'propose-only') : 'flag-v2');
+      const outcome = hasFix && reverifyOk ? 'success' : 'failure';
+      knowledge.record({ class: s.klass, scope: proposal.scope }, { strategy: s.id, outcome });
+
+      return {
+        strategy: s.id,
+        klass: s.klass,
+        deterministic: !!s.deterministic,
+        proposal,
+        accepted,
+        mode,
+        confidence,
+        diagnosis: proposal.diagnosis,
+      };
+    }
+    // Nothing matched — irreducible, goes to V2.
+    knowledge.record({ class: 'unrepairable', scope: cut.cutId }, { strategy: 'flag-v2', outcome: 'failure' });
+    return { strategy: null, klass: 'unrepairable', accepted: false, mode: 'flag-v2', diagnosis: 'no repair strategy matched — flag to V2' };
+  }
+
+  return { knowledge, repair, order };
+}
+
+module.exports = { makeRepairLadder, DEFAULT_ORDER, strategies };

package/resolve-advanced/vendor/conform-qc/repair/media-analysis.js

@@ -0,0 +1,139 @@
+'use strict';
+
+/**
+ * repair/media-analysis.js — analyze target media so the conform emulator knows
+ * the real qualities/options on the volume (stage 1).
+ *
+ * Resolve frames a clip from the RELINKED media's real geometry, not the proxy
+ * dims in the turnover (a scaleToFit bug arises when a highres relink has different
+ * dims/aspect than the proxy the editor framed against). So before emulating we
+ * probe each candidate: resolution,
+ * pixel aspect (SAR/DAR), codec, fps, bit-depth, colour — and rank quality tiers
+ * so the relink can choose the intended original over a proxy/test.
+ *
+ * Split for testability: `parseFfprobe` is PURE (ffprobe JSON -> normalized info);
+ * `probeMedia` shells out to ffprobe and calls it.
+ */
+
+const { spawnSync } = require('child_process');
+
+/** Parse an `r_frame_rate`/`avg_frame_rate` "24000/1001" string to a number. */
+function parseRate(r) {
+  if (!r || typeof r !== 'string') return null;
+  const [n, d] = r.split('/').map(Number);
+  if (!n || !d) return n || null;
+  return +(n / d).toFixed(6);
+}
+
+/** Bit depth from bits_per_raw_sample, else inferred from pix_fmt (…p10/12/16…). */
+function bitDepth(stream) {
+  const b = Number(stream.bits_per_raw_sample);
+  if (Number.isFinite(b) && b > 0) return b;
+  const pf = String(stream.pix_fmt || '');
+  const m = pf.match(/p(\d{1,2})(le|be)?$/);
+  if (m) return Number(m[1]);
+  return pf ? 8 : null;
+}
+
+/** Effective display aspect = (W/H) * (SAR), so anamorphic media reports its true shape. */
+function aspectOf(w, h, sar) {
+  if (!w || !h) return null;
+  let par = 1;
+  if (sar && typeof sar === 'string' && sar.includes(':')) {
+    const [sn, sd] = sar.split(':').map(Number);
+    if (sn > 0 && sd > 0) par = sn / sd;
+  }
+  return +((w / h) * par).toFixed(4);
+}
+
+/**
+ * Normalize an ffprobe `-of json` result (first video stream + format) into a
+ * compact media-info record. Pure.
+ */
+function parseFfprobe(jsonStr, path) {
+  let doc;
+  try {
+    doc = typeof jsonStr === 'string' ? JSON.parse(jsonStr) : jsonStr;
+  } catch (e) {
+    return { path: path || null, ok: false, error: 'ffprobe JSON parse failed' };
+  }
+  // We pass -select_streams v:0, so streams[0] is the video stream even when
+  // codec_type isn't among the requested entries; prefer an explicit match.
+  const streams = doc.streams || [];
+  const v = streams.find((s) => s.codec_type === 'video') || streams[0] || null;
+  if (!v || v.width == null) return { path: path || null, ok: false, error: 'no video stream' };
+  const w = Number(v.width) || null;
+  const h = Number(v.height) || null;
+  const fpsVal = parseRate(v.r_frame_rate) || parseRate(v.avg_frame_rate);
+  const durVal = doc.format && doc.format.duration ? Number(doc.format.duration) : null;
+  // Exact container frame count when present; else derive from duration*fps.
+  // Used to end-anchor reversed clips (no reference render required).
+  let frames = Number(v.nb_frames);
+  if (!Number.isFinite(frames) || frames <= 0) {
+    frames = fpsVal && durVal ? Math.round(durVal * fpsVal) : null;
+  }
+  return {
+    path: path || null,
+    ok: true,
+    width: w,
+    height: h,
+    frames: frames || null,
+    sar: v.sample_aspect_ratio || null,
+    dar: v.display_aspect_ratio || null,
+    aspect: aspectOf(w, h, v.sample_aspect_ratio),
+    codec: v.codec_name || null,
+    profile: v.profile || null,
+    pixFmt: v.pix_fmt || null,
+    bitDepth: bitDepth(v),
+    fps: fpsVal,
+    colorPrimaries: v.color_primaries || null,
+    colorTransfer: v.color_transfer || null,
+    durationSec: durVal != null ? +durVal.toFixed(3) : null,
+  };
+}
+
+const FFPROBE_ARGS = [
+  '-v', 'error', '-select_streams', 'v:0',
+  '-show_entries',
+  'stream=width,height,codec_name,profile,pix_fmt,r_frame_rate,avg_frame_rate,sample_aspect_ratio,display_aspect_ratio,color_primaries,color_transfer,bits_per_raw_sample,nb_frames:format=duration',
+  '-of', 'json',
+];
+
+/** Probe one file via ffprobe. Returns the normalized record (ok:false on failure). */
+function probeMedia(path, { ffprobePath = 'ffprobe' } = {}) {
+  const r = spawnSync(ffprobePath, [...FFPROBE_ARGS, path], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+  if (r.status !== 0) return { path, ok: false, error: (r.stderr || 'ffprobe failed').slice(-200) };
+  return parseFfprobe(r.stdout, path);
+}
+
+/**
+ * Quality rank for choosing among options for the same shot (higher = better
+ * original). ProRes 4444/XQ and higher resolution/bit-depth win; h264/proxy and a
+ * "proxy"/"test" path lose. Used by the relink to pick the intended source.
+ */
+const CODEC_RANK = { prores: 50, dnxhd: 45, dnxhr: 45, h264: 10, hevc: 12, mjpeg: 8 };
+function qualityRank(info) {
+  if (!info || !info.ok) return -1;
+  let s = 0;
+  const codec = String(info.codec || '').toLowerCase();
+  for (const k of Object.keys(CODEC_RANK)) if (codec.includes(k)) s += CODEC_RANK[k];
+  if (/4444|xq|hq/.test(String(info.profile || '').toLowerCase())) s += 20;
+  s += (info.width || 0) / 100; // resolution
+  s += (info.bitDepth || 8) * 2;
+  const p = String(info.path || '').toLowerCase();
+  if (/\bproxy\b/.test(p) || /\.mp4$/.test(p)) s -= 40;
+  if (/\btest(s)?\b/.test(p)) s -= 25;
+  return +s.toFixed(2);
+}
+
+/** Probe a list of paths; returns records sorted by quality (best first). */
+function analyzeMediaList(paths, opts = {}) {
+  const out = (paths || []).map((p) => {
+    const info = probeMedia(p, opts);
+    return { ...info, qualityRank: qualityRank(info) };
+  });
+  out.sort((a, b) => b.qualityRank - a.qualityRank);
+  return out;
+}
+
+module.exports = { parseFfprobe, probeMedia, analyzeMediaList, qualityRank, aspectOf, bitDepth, parseRate };