davinci-resolve-mcp 2.57.4 → 2.58.0

package/resolve-advanced/vendor/audio/trim.js

@@ -0,0 +1,188 @@
+/**
+ * Audio Trim — 2-pop detection and program trim
+ *
+ * Detects 1kHz sync pops (2-pop) in audio and trims to program length.
+ * Standard: 2-pop is 1 frame of 1kHz tone at exactly -2:00 before FFOA.
+ *
+ * Dependencies: FFmpeg 5+ (v7.1.1 installed)
+ */
+
+const { execFile, spawn } = require('child_process');
+const { promisify } = require('util');
+const path = require('path');
+const os = require('os');
+
+const execFileAsync = promisify(execFile);
+
+let ffmpegPath = 'ffmpeg';
+let ffprobePath = 'ffprobe';
+try {
+  ffmpegPath = require('ffmpeg-static');
+  ffprobePath = require('ffprobe-static').path;
+} catch {}
+
+/**
+ * Detect 2-pops (1kHz sync tones) in audio.
+ *
+ * Uses bandpass filter at 1kHz + envelope follower to find short bursts
+ * of 1kHz tone that match 2-pop characteristics.
+ *
+ * @param {string} inputPath - Path to audio file
+ * @param {Object} [options]
+ * @param {number} [options.frequency=1000] - Expected tone frequency in Hz
+ * @param {number} [options.minDuration=0.02] - Min pop duration in seconds
+ * @param {number} [options.maxDuration=0.1] - Max pop duration in seconds
+ * @param {number} [options.threshold=-30] - Detection threshold in dBFS
+ * @returns {Promise<{pops: Array<{time: number, duration: number, level: number}>, count: number}>}
+ */
+async function detectPops(inputPath, options = {}) {
+  const freq = options.frequency || 1000;
+  const minDur = options.minDuration || 0.02;
+  const maxDur = options.maxDuration || 0.1;
+  const threshold = options.threshold || -30;
+
+  // Bandpass around 1kHz, then detect tone bursts
+  const { stderr } = await execFileAsync(ffmpegPath, [
+    '-i', inputPath,
+    '-af', [
+      `bandpass=f=${freq}:width_type=h:w=200`,
+      `silencedetect=noise=${threshold}dB:d=${minDur}`,
+    ].join(','),
+    '-f', 'null', '-',
+  ], { maxBuffer: 50 * 1024 * 1024, timeout: 120000 });
+
+  // Parse silence boundaries — the NON-silent regions are our pops
+  const starts = [...stderr.matchAll(/silence_end:\s*([\d.]+)/g)].map(m => parseFloat(m[1]));
+  const ends = [...stderr.matchAll(/silence_start:\s*([\d.]+)/g)].map(m => parseFloat(m[1]));
+
+  // Get file duration
+  const { stdout: probeOut } = await execFileAsync(ffprobePath, [
+    '-v', 'quiet', '-show_entries', 'format=duration',
+    '-of', 'csv=p=0', inputPath,
+  ]);
+  const totalDuration = parseFloat(probeOut.trim());
+
+  // Build pop list from non-silent regions
+  const pops = [];
+  // First non-silent region starts at 0 (if no initial silence) or at first silence_end
+  for (let i = 0; i < starts.length; i++) {
+    const popStart = starts[i];
+    const popEnd = i < ends.length ? ends[i + 1] || totalDuration : totalDuration;
+    const popDuration = popEnd - popStart;
+
+    // Filter to likely 2-pops: short bursts within expected duration range
+    if (popDuration >= minDur && popDuration <= maxDur) {
+      pops.push({
+        time: popStart,
+        duration: popDuration,
+        level: 0, // Could measure RMS but not critical
+      });
+    }
+  }
+
+  return { pops, count: pops.length };
+}
+
+/**
+ * Trim audio to program length using 2-pop as reference.
+ *
+ * @param {string} inputPath - Path to input audio
+ * @param {string} outputPath - Path for trimmed output
+ * @param {Object} options
+ * @param {number} [options.startTime] - Start time in seconds (auto-detect from 2-pop if not provided)
+ * @param {number} [options.endTime] - End time in seconds
+ * @param {number} [options.duration] - Duration in seconds (alternative to endTime)
+ * @param {number} [options.fadeIn=0] - Fade-in duration in seconds
+ * @param {number} [options.fadeOut=0] - Fade-out duration in seconds
+ * @param {number} [options.preRoll=2] - Seconds of pre-roll before 2-pop (default 2s per SMPTE)
+ * @param {Function} [options.onProgress] - Progress callback
+ * @returns {Promise<{outputPath: string, startTime: number, endTime: number, duration: number, popsDetected: number}>}
+ */
+async function trim(inputPath, outputPath, options = {}) {
+  const { fadeIn = 0, fadeOut = 0, preRoll = 2, onProgress = () => {} } = options;
+
+  onProgress(10);
+
+  let startTime = options.startTime;
+  let endTime = options.endTime;
+  let popsDetected = 0;
+
+  // Auto-detect from 2-pop if no explicit start/end
+  if (startTime === undefined) {
+    const { pops } = await detectPops(inputPath);
+    popsDetected = pops.length;
+
+    if (pops.length >= 1) {
+      // First pop is head 2-pop — program starts preRoll seconds after it
+      startTime = pops[0].time + preRoll;
+    } else {
+      startTime = 0;
+    }
+
+    if (pops.length >= 2 && endTime === undefined && !options.duration) {
+      // Second pop is tail 2-pop — program ends preRoll seconds before it
+      endTime = pops[pops.length - 1].time - preRoll;
+    }
+  }
+
+  onProgress(40);
+
+  // Build FFmpeg args
+  const args = ['-y', '-i', inputPath];
+
+  if (startTime > 0) {
+    args.push('-ss', String(startTime));
+  }
+
+  if (options.duration) {
+    args.push('-t', String(options.duration));
+  } else if (endTime !== undefined) {
+    args.push('-to', String(endTime));
+  }
+
+  // Build filter chain for fades
+  const filters = [];
+  if (fadeIn > 0) {
+    filters.push(`afade=t=in:st=0:d=${fadeIn}`);
+  }
+  if (fadeOut > 0) {
+    const dur = options.duration || (endTime !== undefined ? endTime - startTime : 0);
+    if (dur > 0) {
+      filters.push(`afade=t=out:st=${dur - fadeOut}:d=${fadeOut}`);
+    }
+  }
+
+  if (filters.length > 0) {
+    args.push('-af', filters.join(','));
+  }
+
+  args.push('-c:a', 'pcm_s24le', outputPath);
+
+  onProgress(50);
+
+  await execFileAsync(ffmpegPath, args, { timeout: 300000, maxBuffer: 10 * 1024 * 1024 });
+
+  onProgress(90);
+
+  // Get output duration
+  const { stdout: durOut } = await execFileAsync(ffprobePath, [
+    '-v', 'quiet', '-show_entries', 'format=duration',
+    '-of', 'csv=p=0', outputPath,
+  ]);
+  const outputDuration = parseFloat(durOut.trim());
+
+  onProgress(100);
+
+  return {
+    outputPath,
+    startTime,
+    endTime: endTime || startTime + outputDuration,
+    duration: outputDuration,
+    popsDetected,
+  };
+}
+
+module.exports = {
+  detectPops,
+  trim,
+};

package/resolve-advanced/vendor/audio-fairlight/index.js

@@ -0,0 +1,391 @@
+/**
+ * Fairlight Audio Intelligence
+ *
+ * Audio track planning, coverage analysis, and loudness validation
+ * for DaVinci Resolve Fairlight workflows.
+ *
+ * Provides content-type-specific audio templates (documentary,
+ * narrative, podcast, social) and tools to analyze clip coverage,
+ * detect gaps/overlaps/silence, and validate loudness targets.
+ *
+ * @module post-tools/audio-fairlight
+ */
+
+/**
+ * Audio track channel types recognized by Resolve.
+ * @type {Object<string, string>}
+ */
+const CHANNEL_TYPES = {
+  MONO: 'mono',
+  STEREO: 'stereo',
+  SURROUND_51: '5.1',
+  SURROUND_71: '7.1',
+  ADAPTIVE: 'adaptive1',
+};
+
+/**
+ * Audio templates for different content types.
+ *
+ * Each template defines tracks with name, channel type, and routing.
+ * Bus assignments reflect standard Fairlight mixing conventions.
+ *
+ * @type {Object}
+ */
+const AUDIO_TEMPLATES = {
+  DOCUMENTARY: {
+    name: 'Documentary',
+    description: 'Interview-driven documentary with natural sound and music',
+    tracks: [
+      { name: 'DX L',   label: 'Dialogue Left',      channelType: 'mono', bus: 'DX',  role: 'dialogue' },
+      { name: 'DX R',   label: 'Dialogue Right',      channelType: 'mono', bus: 'DX',  role: 'dialogue' },
+      { name: 'NAT',    label: 'Natural Sound',        channelType: 'stereo', bus: 'NAT', role: 'nat_sound' },
+      { name: 'MX',     label: 'Music',                channelType: 'stereo', bus: 'MX',  role: 'music' },
+      { name: 'VO',     label: 'Voice Over',           channelType: 'mono',   bus: 'DX',  role: 'voiceover' },
+      { name: 'SFX',    label: 'Sound Effects',        channelType: 'stereo', bus: 'FX',  role: 'sfx' },
+    ],
+    buses: ['DX', 'NAT', 'MX', 'FX', 'MAIN'],
+    outputFormat: 'stereo',
+  },
+
+  NARRATIVE: {
+    name: 'Narrative Feature',
+    description: 'Scripted narrative with full surround sound design',
+    tracks: [
+      { name: 'DX',     label: 'Production Dialogue',  channelType: '5.1',    bus: 'DX',  role: 'dialogue' },
+      { name: 'ADR',    label: 'ADR / Loop Group',      channelType: '5.1',    bus: 'DX',  role: 'dialogue' },
+      { name: 'FX',     label: 'Sound Effects',         channelType: '5.1',    bus: 'FX',  role: 'sfx' },
+      { name: 'BG',     label: 'Backgrounds / Ambience', channelType: '5.1',   bus: 'FX',  role: 'ambience' },
+      { name: 'FLY',    label: 'Foley',                 channelType: '5.1',    bus: 'FX',  role: 'foley' },
+      { name: 'MX',     label: 'Music Score',           channelType: '5.1',    bus: 'MX',  role: 'music' },
+      { name: 'MX2',    label: 'Music Source / Diegetic', channelType: 'stereo', bus: 'MX', role: 'music' },
+      { name: 'FG',     label: 'Full Mix Guide',        channelType: 'stereo', bus: 'REF', role: 'guide' },
+    ],
+    buses: ['DX', 'FX', 'MX', 'REF', 'MAIN'],
+    outputFormat: '5.1',
+  },
+
+  PODCAST: {
+    name: 'Podcast',
+    description: 'Multi-host podcast with music beds',
+    tracks: [
+      { name: 'HOST',   label: 'Host Microphone',      channelType: 'mono',   bus: 'DX',  role: 'dialogue' },
+      { name: 'GUEST',  label: 'Guest Microphone',     channelType: 'mono',   bus: 'DX',  role: 'dialogue' },
+      { name: 'GUEST2', label: 'Guest 2 Microphone',   channelType: 'mono',   bus: 'DX',  role: 'dialogue' },
+      { name: 'MX',     label: 'Music / Beds',         channelType: 'stereo', bus: 'MX',  role: 'music' },
+      { name: 'SFX',    label: 'Stingers / SFX',       channelType: 'stereo', bus: 'FX',  role: 'sfx' },
+      { name: 'PHONE',  label: 'Phone / Remote',       channelType: 'mono',   bus: 'DX',  role: 'dialogue' },
+    ],
+    buses: ['DX', 'MX', 'FX', 'MAIN'],
+    outputFormat: 'stereo',
+  },
+
+  SOCIAL: {
+    name: 'Social Media',
+    description: 'Quick-turnaround social content',
+    tracks: [
+      { name: 'MIX',    label: 'Main Mix',             channelType: 'stereo', bus: 'MAIN', role: 'mix' },
+      { name: 'VO',     label: 'Voice Over',           channelType: 'mono',   bus: 'DX',   role: 'voiceover' },
+      { name: 'MX',     label: 'Music',                channelType: 'stereo', bus: 'MX',   role: 'music' },
+    ],
+    buses: ['DX', 'MX', 'MAIN'],
+    outputFormat: 'stereo',
+  },
+};
+
+/**
+ * Loudness targets for common delivery specs.
+ * @type {Object}
+ */
+const LOUDNESS_TARGETS = {
+  broadcast_us:   { standard: 'ATSC A/85',    targetLUFS: -24, tolerance: 2, truePeakdBTP: -2 },
+  broadcast_eu:   { standard: 'EBU R128',     targetLUFS: -23, tolerance: 1, truePeakdBTP: -1 },
+  streaming:      { standard: 'Streaming',    targetLUFS: -16, tolerance: 2, truePeakdBTP: -1 },
+  cinema:         { standard: 'SMPTE RP 200', targetLUFS: -20, tolerance: 2, truePeakdBTP: -3 },
+  podcast:        { standard: 'Podcast',      targetLUFS: -16, tolerance: 2, truePeakdBTP: -1 },
+};
+
+/**
+ * Select an audio template by content type.
+ *
+ * @param {string} contentType — 'documentary'|'narrative'|'podcast'|'social'
+ * @returns {object} template definition
+ */
+function selectTemplate(contentType) {
+  const key = contentType.toUpperCase().replace(/[\s-]/g, '_');
+  const template = AUDIO_TEMPLATES[key];
+  if (!template) {
+    const available = Object.keys(AUDIO_TEMPLATES).map(k => k.toLowerCase()).join(', ');
+    throw new Error(`Unknown content type "${contentType}". Available: ${available}`);
+  }
+  return JSON.parse(JSON.stringify(template));
+}
+
+/**
+ * Generate a Fairlight track creation plan from a template.
+ *
+ * Returns instructions suitable for Resolve timeline track creation:
+ * AddTrack('audio', subtype) calls and track naming.
+ *
+ * @param {object} template — from selectTemplate or AUDIO_TEMPLATES
+ * @param {object} [opts]
+ * @param {number} [opts.startIndex=1] — first audio track index
+ * @returns {object} { tracks: [...], buses: [...], resolveCommands: [...] }
+ */
+function generateTrackPlan(template, opts = {}) {
+  const { startIndex = 1 } = opts;
+
+  const tracks = template.tracks.map((t, i) => ({
+    index: startIndex + i,
+    name: t.name,
+    label: t.label,
+    channelType: t.channelType,
+    bus: t.bus,
+    role: t.role,
+    resolveSubtype: t.channelType === '5.1' ? '5.1'
+      : t.channelType === '7.1' ? '7.1'
+      : t.channelType === 'stereo' ? 'stereo'
+      : 'mono',
+  }));
+
+  const resolveCommands = tracks.map(t => ({
+    action: 'AddTrack',
+    args: ['audio', t.resolveSubtype],
+    then: { action: 'SetTrackName', args: ['audio', t.index, t.name] },
+  }));
+
+  return {
+    templateName: template.name,
+    outputFormat: template.outputFormat,
+    trackCount: tracks.length,
+    tracks,
+    buses: template.buses,
+    resolveCommands,
+  };
+}
+
+/**
+ * Analyze audio clip coverage on a timeline.
+ *
+ * Detects gaps, overlaps, and silence per track.
+ *
+ * @param {object[]} clips — [{ trackIndex, trackName, startTime, endTime, hasAudio? }]
+ * @param {object} [opts]
+ * @param {number} [opts.minGap=0.5] — minimum gap (seconds) to flag
+ * @param {number} [opts.timelineStart=0]
+ * @param {number} [opts.timelineEnd] — if omitted, derived from last clip
+ * @returns {object} { tracks: { [trackName]: { clips, gaps, overlaps, coveragePercent } }, summary }
+ */
+function analyzeAudioCoverage(clips, opts = {}) {
+  const { minGap = 0.5, timelineStart = 0 } = opts;
+
+  // Group by track
+  const trackGroups = {};
+  for (const clip of clips) {
+    const key = clip.trackName || `Track ${clip.trackIndex}`;
+    if (!trackGroups[key]) trackGroups[key] = [];
+    trackGroups[key].push(clip);
+  }
+
+  // Derive timeline end
+  let timelineEnd = opts.timelineEnd;
+  if (timelineEnd === undefined) {
+    timelineEnd = 0;
+    for (const clip of clips) {
+      if (clip.endTime > timelineEnd) timelineEnd = clip.endTime;
+    }
+  }
+
+  const totalDuration = timelineEnd - timelineStart;
+  const tracks = {};
+  let totalGaps = 0;
+  let totalOverlaps = 0;
+
+  for (const [trackName, trackClips] of Object.entries(trackGroups)) {
+    // Sort by start time
+    const sorted = [...trackClips].sort((a, b) => a.startTime - b.startTime);
+    const gaps = [];
+    const overlaps = [];
+
+    // Check gap before first clip
+    if (sorted.length > 0 && sorted[0].startTime - timelineStart > minGap) {
+      gaps.push({
+        startTime: timelineStart,
+        endTime: sorted[0].startTime,
+        duration: sorted[0].startTime - timelineStart,
+      });
+    }
+
+    // Check between clips
+    for (let i = 1; i < sorted.length; i++) {
+      const prev = sorted[i - 1];
+      const curr = sorted[i];
+
+      if (curr.startTime < prev.endTime) {
+        // Overlap
+        overlaps.push({
+          clipA: i - 1,
+          clipB: i,
+          startTime: curr.startTime,
+          endTime: Math.min(prev.endTime, curr.endTime),
+          duration: Math.min(prev.endTime, curr.endTime) - curr.startTime,
+        });
+      } else if (curr.startTime - prev.endTime > minGap) {
+        // Gap
+        gaps.push({
+          startTime: prev.endTime,
+          endTime: curr.startTime,
+          duration: curr.startTime - prev.endTime,
+        });
+      }
+    }
+
+    // Check gap after last clip
+    if (sorted.length > 0) {
+      const last = sorted[sorted.length - 1];
+      if (timelineEnd - last.endTime > minGap) {
+        gaps.push({
+          startTime: last.endTime,
+          endTime: timelineEnd,
+          duration: timelineEnd - last.endTime,
+        });
+      }
+    }
+
+    // Calculate coverage
+    let coveredTime = 0;
+    const merged = _mergeIntervals(sorted.map(c => [c.startTime, c.endTime]));
+    for (const [s, e] of merged) {
+      coveredTime += Math.min(e, timelineEnd) - Math.max(s, timelineStart);
+    }
+
+    const coveragePercent = totalDuration > 0
+      ? Math.round((coveredTime / totalDuration) * 10000) / 100
+      : 0;
+
+    totalGaps += gaps.length;
+    totalOverlaps += overlaps.length;
+
+    tracks[trackName] = {
+      clipCount: sorted.length,
+      gaps,
+      overlaps,
+      coveragePercent,
+    };
+  }
+
+  return {
+    tracks,
+    summary: {
+      trackCount: Object.keys(tracks).length,
+      totalGaps,
+      totalOverlaps,
+      timelineDuration: totalDuration,
+    },
+  };
+}
+
+/**
+ * Merge overlapping intervals.
+ * @param {number[][]} intervals — [[start, end], ...]
+ * @returns {number[][]}
+ */
+function _mergeIntervals(intervals) {
+  if (intervals.length === 0) return [];
+  const sorted = [...intervals].sort((a, b) => a[0] - b[0]);
+  const merged = [sorted[0]];
+
+  for (let i = 1; i < sorted.length; i++) {
+    const last = merged[merged.length - 1];
+    if (sorted[i][0] <= last[1]) {
+      last[1] = Math.max(last[1], sorted[i][1]);
+    } else {
+      merged.push(sorted[i]);
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Validate loudness measurements against a target.
+ *
+ * @param {object} measurements — { integratedLUFS, truePeakdBTP, shortTermMax?, momentaryMax?, LRA? }
+ * @param {number|string} targetLUFS — target in LUFS or a preset key (e.g. 'broadcast_us')
+ * @returns {object} { pass, results: [{ check, value, target, pass, message }] }
+ */
+function checkLoudness(measurements, targetLUFS) {
+  let target;
+
+  if (typeof targetLUFS === 'string') {
+    const preset = LOUDNESS_TARGETS[targetLUFS.toLowerCase().replace(/[\s-]/g, '_')];
+    if (!preset) throw new Error(`Unknown loudness target "${targetLUFS}"`);
+    target = preset;
+  } else {
+    target = { targetLUFS, tolerance: 2, truePeakdBTP: -1 };
+  }
+
+  const results = [];
+  let allPass = true;
+
+  // Integrated loudness check
+  const intDiff = Math.abs(measurements.integratedLUFS - target.targetLUFS);
+  const intPass = intDiff <= target.tolerance;
+  if (!intPass) allPass = false;
+
+  results.push({
+    check: 'integrated_loudness',
+    value: measurements.integratedLUFS,
+    target: target.targetLUFS,
+    tolerance: target.tolerance,
+    pass: intPass,
+    message: intPass
+      ? `Integrated loudness ${measurements.integratedLUFS} LUFS within tolerance`
+      : `Integrated loudness ${measurements.integratedLUFS} LUFS outside tolerance (target: ${target.targetLUFS} +/- ${target.tolerance})`,
+  });
+
+  // True peak check
+  if (measurements.truePeakdBTP !== undefined && target.truePeakdBTP !== undefined) {
+    const tpPass = measurements.truePeakdBTP <= target.truePeakdBTP;
+    if (!tpPass) allPass = false;
+
+    results.push({
+      check: 'true_peak',
+      value: measurements.truePeakdBTP,
+      target: target.truePeakdBTP,
+      pass: tpPass,
+      message: tpPass
+        ? `True peak ${measurements.truePeakdBTP} dBTP within limit`
+        : `True peak ${measurements.truePeakdBTP} dBTP exceeds limit of ${target.truePeakdBTP} dBTP`,
+    });
+  }
+
+  // LRA check (informational, typical range 5-20 LU)
+  if (measurements.LRA !== undefined) {
+    const lraWarn = measurements.LRA > 20;
+    results.push({
+      check: 'loudness_range',
+      value: measurements.LRA,
+      pass: !lraWarn,
+      message: lraWarn
+        ? `Loudness range ${measurements.LRA} LU is unusually wide (>20 LU)`
+        : `Loudness range ${measurements.LRA} LU is within normal bounds`,
+    });
+    if (lraWarn) allPass = false;
+  }
+
+  return {
+    pass: allPass,
+    standard: target.standard || 'Custom',
+    results,
+  };
+}
+
+module.exports = {
+  AUDIO_TEMPLATES,
+  CHANNEL_TYPES,
+  LOUDNESS_TARGETS,
+  selectTemplate,
+  generateTrackPlan,
+  analyzeAudioCoverage,
+  checkLoudness,
+};

package/resolve-advanced/vendor/conform-qc/adapters/frame-sampler.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * adapters/frame-sampler.js — the FrameSampler adapter interface (spec §3.2).
+ *
+ * Extract a frame from a media reference at a given SOURCE frame and resolution.
+ * The core never touches ffmpeg/Resolve directly — a surface injects a concrete
+ * sampler (render-node ffmpeg in the cloud, local ffmpeg in the post-assistant).
+ * Output matches the comparator's decoded-frame shape ({data,width,height},
+ * grayscale, 0..1) so a sampled frame flows straight into compare/.
+ */
+
+class FrameSampler {
+  /**
+   * @param {string|object} mediaRef  resolved media (path / asset+version / stream)
+   * @param {number} frame            SOURCE frame to extract (the Oracle's derivedSampleFrame)
+   * @param {{width:number,height:number}} size
+   * @returns {Promise<{data:Float64Array,width:number,height:number}>}
+   */
+  // eslint-disable-next-line class-methods-use-this, no-unused-vars
+  async sample(mediaRef, frame, size) {
+    throw new Error('FrameSampler.sample must be implemented by an adapter');
+  }
+}
+
+/** Duck-typed check that an object satisfies the FrameSampler interface. */
+function isFrameSampler(obj) {
+  return !!obj && typeof obj.sample === 'function';
+}
+
+/**
+ * A deterministic in-memory sampler for tests — no media, no ffmpeg. The frame
+ * content is a stable hash of (mediaRef, frame), so the same request always
+ * yields the same pixels and different requests differ.
+ */
+class FakeFrameSampler extends FrameSampler {
+  // eslint-disable-next-line class-methods-use-this
+  async sample(mediaRef, frame, { width, height }) {
+    const n = width * height;
+    const data = new Float64Array(n);
+    let h = 2166136261 >>> 0;
+    const key = `${typeof mediaRef === 'object' ? JSON.stringify(mediaRef) : mediaRef}:${frame}`;
+    for (let i = 0; i < key.length; i++) {
+      h ^= key.charCodeAt(i);
+      h = Math.imul(h, 16777619);
+    }
+    for (let i = 0; i < n; i++) {
+      h ^= i;
+      h = Math.imul(h, 16777619);
+      data[i] = ((h >>> 8) & 0xff) / 255;
+    }
+    return { data, width, height };
+  }
+}
+
+module.exports = { FrameSampler, FakeFrameSampler, isFrameSampler };

package/resolve-advanced/vendor/conform-qc/adapters/local-ffmpeg-sampler.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/**
+ * adapters/local-ffmpeg-sampler.js — the local FrameSampler impl (spec §3.2).
+ *
+ * Extracts a single SOURCE frame from a media file via local ffmpeg and decodes
+ * it to the normalized-grayscale shape the comparator consumes. This is the
+ * post-assistant / local-surface sampler; the render node injects its own
+ * ffmpeg-over-R2 sampler with the same interface.
+ */
+
+const { spawn } = require('child_process');
+const { FrameSampler } = require('./frame-sampler');
+const { decodeGrayNormalized } = require('../compare/decode');
+
+/** Run ffmpeg, capture stdout (the extracted PNG) as a Buffer. */
+function runFfmpeg(args, ffmpegPath) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(ffmpegPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const out = [];
+    const err = [];
+    proc.stdout.on('data', (d) => out.push(d));
+    proc.stderr.on('data', (d) => err.push(d));
+    proc.on('error', reject);
+    proc.on('close', (code) => {
+      if (code === 0) resolve(Buffer.concat(out));
+      else reject(new Error(`ffmpeg exited ${code}: ${Buffer.concat(err).toString().slice(-500)}`));
+    });
+  });
+}
+
+class LocalFfmpegFrameSampler extends FrameSampler {
+  constructor({ ffmpegPath = 'ffmpeg' } = {}) {
+    super();
+    this.ffmpegPath = ffmpegPath;
+  }
+
+  /**
+   * @param {string} mediaRef  local file path
+   * @param {number} frame     0-based source frame index
+   * @param {{width:number,height:number}} size
+   */
+  async sample(mediaRef, frame, size) {
+    if (typeof mediaRef !== 'string') {
+      throw new Error('LocalFfmpegFrameSampler: mediaRef must be a local file path');
+    }
+    // Select exactly the requested frame, emit one PNG to stdout.
+    const args = [
+      '-v', 'error',
+      '-i', mediaRef,
+      '-vf', `select=eq(n\\,${Math.round(frame)})`,
+      '-vframes', '1',
+      '-f', 'image2pipe',
+      '-c:v', 'png',
+      '-',
+    ];
+    const png = await runFfmpeg(args, this.ffmpegPath);
+    if (!png || png.length === 0) {
+      throw new Error(`LocalFfmpegFrameSampler: no frame ${frame} extracted from ${mediaRef}`);
+    }
+    return decodeGrayNormalized(png, size);
+  }
+}
+
+module.exports = { LocalFfmpegFrameSampler };