aivee 0.0.0-stage → 0.1.0-dev.59872e1

package/src/media/probe.mjs

@@ -0,0 +1,149 @@
+import { existsSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { runProcess } from '../render/process.mjs';
+
+export function probeMedia(inputPath, { requireVideo = true, timeoutMs } = {}) {
+  if (timeoutMs !== undefined && (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)) {
+    throw new TypeError('ffprobe timeoutMs must be a positive safe integer.');
+  }
+  const path = resolve(inputPath);
+  if (!existsSync(path) || !statSync(path).isFile()) throw new Error(`Media file not found: ${path}`);
+  const result = spawnSync('ffprobe', [
+    '-v', 'error', '-show_format', '-show_streams', '-of', 'json', path,
+  ], { encoding: 'utf8', windowsHide: true, ...(timeoutMs !== undefined ? { timeout: timeoutMs } : {}) });
+  if (result.error || result.status !== 0) {
+    throw new Error(`ffprobe failed: ${result.error?.message ?? result.stderr.trim()}`);
+  }
+  return parseProbeOutput(result.stdout, path, { requireVideo });
+}
+
+export async function probeMediaAsync(inputPath, { requireVideo = true, signal } = {}) {
+  validateAbortSignal(signal);
+  const path = resolve(inputPath);
+  if (!existsSync(path) || !statSync(path).isFile()) throw new Error(`Media file not found: ${path}`);
+  const result = await runProcess('ffprobe', [
+    '-v', 'error', '-show_format', '-show_streams', '-of', 'json', path,
+  ], { signal, stdio: 'capture' });
+  return parseProbeOutput(result.stdout, path, { requireVideo });
+}
+
+function validateAbortSignal(signal) {
+  if (signal !== undefined && (typeof signal.aborted !== 'boolean' || typeof signal.addEventListener !== 'function')) {
+    throw new TypeError('ffprobe signal must be an AbortSignal.');
+  }
+}
+
+export function parseProbeOutput(output, path = '', { requireVideo = true } = {}) {
+  let info;
+  try {
+    info = JSON.parse(output);
+  } catch (error) {
+    throw new TypeError(`Invalid ffprobe JSON: ${error.message}`);
+  }
+  const streams = Array.isArray(info.streams) ? info.streams : [];
+  const formatDuration = parseOptionalNumber(info.format?.duration);
+  const streamDuration = streams.reduce((duration, stream) =>
+    Math.max(duration, parseStreamDuration(stream)), 0);
+  const durationSeconds = Number.isFinite(formatDuration) && formatDuration > 0
+    ? formatDuration
+    : streamDuration;
+  const videoStreams = streams.filter((stream) => stream.codec_type === 'video').map((stream, index) => ({
+    index,
+    streamIndex: Number.isSafeInteger(stream.index) ? stream.index : index,
+    codec: stream.codec_name ?? null,
+    width: Number(stream.width) || null,
+    height: Number(stream.height) || null,
+    pixelFormat: stream.pix_fmt ?? null,
+    frameRate: parseFrameRate(stream.avg_frame_rate || stream.r_frame_rate),
+    timeBase: stream.time_base ?? null,
+    startSeconds: parseOptionalNumber(stream.start_time),
+    durationSeconds: parseStreamDuration(stream) || null,
+  }));
+  const video = streams.find((stream) => stream.codec_type === 'video');
+  const audioStreams = streams.filter((stream) => stream.codec_type === 'audio').map((stream, index) => ({
+    index,
+    streamIndex: Number.isSafeInteger(stream.index) ? stream.index : index,
+    codec: stream.codec_name ?? null,
+    channels: Number(stream.channels) || null,
+    channelLayout: stream.channel_layout ?? null,
+    sampleRate: Number(stream.sample_rate) || null,
+    startSeconds: parseOptionalNumber(stream.start_time),
+    durationSeconds: parseStreamDuration(stream) || null,
+    timeBase: stream.time_base ?? null,
+    language: typeof stream.tags?.language === 'string' ? stream.tags.language : null,
+    title: typeof stream.tags?.title === 'string' ? stream.tags.title : null,
+  }));
+  const audio = audioStreams[0];
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    throw new TypeError('Media must have a finite positive duration.');
+  }
+  if (requireVideo && !video) throw new TypeError('Media must contain a video stream.');
+  if (!video && !audio) throw new TypeError('Media must contain a video or audio stream.');
+  return {
+    path,
+    durationSeconds,
+    formatName: typeof info.format?.format_name === 'string' ? info.format.format_name : null,
+    videoStreams,
+    width: Number(video?.width) || null,
+    height: Number(video?.height) || null,
+    frameRate: parseFrameRate(video?.avg_frame_rate || video?.r_frame_rate),
+    nominalFrameRate: parseFrameRate(video?.r_frame_rate),
+    hasAudio: Boolean(audio),
+    audioChannels: audio?.channels ?? null,
+    audioChannelLayout: audio?.channelLayout ?? null,
+    audioStreams,
+    videoCodec: video?.codec_name ?? null,
+    pixelFormat: video?.pix_fmt ?? null,
+    audioCodec: audio?.codec ?? null,
+    colorSpace: video?.color_space ?? null,
+    colorTransfer: video?.color_transfer ?? null,
+    colorPrimaries: video?.color_primaries ?? null,
+    colorRange: video?.color_range ?? null,
+    streamTiming: {
+      containerStartSeconds: parseOptionalNumber(info.format?.start_time),
+      videoStartSeconds: parseOptionalNumber(video?.start_time),
+      videoDurationSeconds: parseStreamDuration(video) || null,
+      audioStartSeconds: audio?.startSeconds ?? null,
+      audioDurationSeconds: audio?.durationSeconds ?? null,
+      videoTimeBase: video?.time_base ?? null,
+      audioTimeBase: audio?.timeBase ?? null,
+    },
+  };
+}
+
+/** Normalize stored video metadata to ordinal indexes plus FFmpeg-global indexes. */
+export function normalizeVideoStreamMetadata(streams) {
+  if (!Array.isArray(streams)) return streams;
+  return streams.map((stream, index) => {
+    if (!stream || typeof stream !== 'object' || Array.isArray(stream)) return stream;
+    return { ...stream, index, streamIndex: stream.streamIndex ?? stream.index ?? index };
+  });
+}
+
+function parseOptionalNumber(value) {
+  if (value === undefined || value === null || value === 'N/A') return null;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function parseStreamDuration(stream) {
+  if (!stream || typeof stream !== 'object') return 0;
+  const duration = parseOptionalNumber(stream.duration);
+  if (duration !== null && duration > 0) return duration;
+  const ticks = parseOptionalNumber(stream.duration_ts);
+  const [numerator, denominator] = typeof stream.time_base === 'string'
+    ? stream.time_base.split('/').map(Number)
+    : [];
+  if (!Number.isFinite(ticks) || ticks <= 0 || !Number.isFinite(numerator)
+      || !Number.isFinite(denominator) || numerator <= 0 || denominator <= 0) return 0;
+  return ticks * numerator / denominator;
+}
+
+function parseFrameRate(value) {
+  if (typeof value !== 'string') return null;
+  const [numerator, denominator] = value.split('/').map(Number);
+  return Number.isFinite(numerator) && Number.isFinite(denominator) && denominator !== 0
+    ? numerator / denominator
+    : null;
+}

package/src/media/render-cuts.mjs

@@ -0,0 +1,90 @@
+import { randomUUID } from 'node:crypto';
+import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, extname, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { assertEdlApproved, validateEdl } from '../edits/retime-transcript.mjs';
+import { probeMedia } from './probe.mjs';
+
+export function renderCuts(inputPath, edl, outputPath) {
+  const input = resolve(inputPath);
+  const output = resolve(outputPath);
+  if (input === output) throw new Error('Output path must differ from the source video.');
+  if (existsSync(output)) throw new Error(`Output already exists: ${output}`);
+  if (extname(output).toLowerCase() !== '.mp4') throw new Error('Cut output must use the .mp4 extension.');
+
+  const media = probeMedia(input);
+  validateEdl(edl, media.durationSeconds);
+  assertEdlApproved(edl);
+  const keepRanges = getKeepRanges(media.durationSeconds, edl.cuts);
+  if (!keepRanges.length) throw new Error('EDL removes the entire source video.');
+
+  const outputDir = dirname(output);
+  mkdirSync(outputDir, { recursive: true });
+  const token = randomUUID();
+  const filterPath = resolve(outputDir, `.${basename(output)}.${token}.filter.txt`);
+  const temporaryOutput = resolve(outputDir, `.${basename(output, '.mp4')}.${token}.tmp.mp4`);
+  const filterGraph = createFilterGraph(keepRanges, media.hasAudio);
+  writeFileSync(filterPath, filterGraph, { flag: 'wx' });
+  let outputCreated = false;
+  try {
+    const args = ['-nostdin', '-hide_banner', '-v', 'error', '-n', '-i', input,
+      '-/filter_complex', filterPath, '-map', '[v]'];
+    if (media.hasAudio) args.push('-map', '[a]');
+    else args.push('-an');
+    args.push('-c:v', 'libx264', '-preset', 'medium', '-crf', '18', '-pix_fmt', 'yuv420p');
+    if (media.hasAudio) args.push('-c:a', 'aac', '-b:a', '192k');
+    args.push('-movflags', '+faststart', temporaryOutput);
+    let result = spawnSync('ffmpeg', args, { encoding: 'utf8', windowsHide: true });
+    if (result.status !== 0 && /unrecognized option ['"]?\/?filter_complex|option not found/i.test(result.stderr)) {
+      const optionIndex = args.indexOf('-/filter_complex');
+      args.splice(optionIndex, 2, '-filter_complex', filterGraph);
+      result = spawnSync('ffmpeg', args, { encoding: 'utf8', windowsHide: true });
+    }
+    if (result.error || result.status !== 0) {
+      throw new Error(`ffmpeg failed: ${result.error?.message ?? result.stderr.trim()}`);
+    }
+    closeSync(openSync(output, 'wx'));
+    outputCreated = true;
+    copyFileSync(temporaryOutput, output);
+    const rendered = probeMedia(output);
+    const expectedDuration = keepRanges.reduce((sum, range) => sum + range.end - range.start, 0);
+    if (Math.abs(rendered.durationSeconds - expectedDuration) > Math.max(0.15, 1 / (media.frameRate || 30))) {
+      throw new Error(`Rendered duration ${rendered.durationSeconds.toFixed(3)}s does not match expected ${expectedDuration.toFixed(3)}s.`);
+    }
+    if (media.hasAudio !== rendered.hasAudio) throw new Error('Rendered audio stream does not match the source.');
+    return { input, output, keepRanges, durationSeconds: keepRanges.reduce((sum, range) => sum + range.end - range.start, 0) };
+  } catch (error) {
+    if (outputCreated && existsSync(output)) unlinkSync(output);
+    throw error;
+  } finally {
+    rmSync(filterPath, { force: true });
+    rmSync(temporaryOutput, { force: true });
+  }
+}
+
+export function getKeepRanges(durationSeconds, cuts) {
+  const ranges = [];
+  let cursor = 0;
+  for (const cut of cuts) {
+    if (cut.sourceStart > cursor) ranges.push({ start: cursor, end: cut.sourceStart });
+    cursor = cut.sourceEnd;
+  }
+  if (cursor < durationSeconds) ranges.push({ start: cursor, end: durationSeconds });
+  return ranges;
+}
+
+export function createFilterGraph(ranges, hasAudio) {
+  const lines = [];
+  for (const [index, range] of ranges.entries()) {
+    lines.push(`[0:v]trim=start=${range.start}:end=${range.end},setpts=PTS-STARTPTS[v${index}]`);
+    if (hasAudio) lines.push(`[0:a]atrim=start=${range.start}:end=${range.end},asetpts=PTS-STARTPTS[a${index}]`);
+  }
+  const videoInputs = ranges.map((_, index) => `[v${index}]`).join('');
+  if (hasAudio) {
+    const inputs = ranges.map((_, index) => `[v${index}][a${index}]`).join('');
+    lines.push(`${inputs}concat=n=${ranges.length}:v=1:a=1[v][a]`);
+  } else {
+    lines.push(`${videoInputs}concat=n=${ranges.length}:v=1:a=0[v]`);
+  }
+  return `${lines.join(';\n')}\n`;
+}

package/src/media/scene-detection.mjs

@@ -0,0 +1,107 @@
+import { probeMediaAsync } from './probe.mjs';
+import { runProcess } from '../render/process.mjs';
+
+const DEFAULT_SCENE_THRESHOLD = 0.35;
+const DEFAULT_MINIMUM_SPACING_SECONDS = 0.5;
+const DEFAULT_MAXIMUM_FINDINGS = 2000;
+
+/** Find visually distinct shot boundaries with FFmpeg's scene-change score. */
+export async function detectSceneChangesAsync(inputPath, options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('Scene detection options must be an object.');
+  }
+  const allowedOptions = new Set(['threshold', 'minimumSpacingSeconds', 'maximumFindings', 'signal']);
+  for (const key of Object.keys(options)) {
+    if (!allowedOptions.has(key)) throw new TypeError(`Unsupported scene detection option: ${key}.`);
+  }
+  const media = await probeMediaAsync(inputPath, { signal: options.signal });
+  if (!media.videoStreams.length) throw new TypeError('Scene detection requires a video stream.');
+
+  const threshold = options.threshold ?? DEFAULT_SCENE_THRESHOLD;
+  const minimumSpacingSeconds = options.minimumSpacingSeconds ?? DEFAULT_MINIMUM_SPACING_SECONDS;
+  const maximumFindings = options.maximumFindings ?? DEFAULT_MAXIMUM_FINDINGS;
+  if (!Number.isFinite(threshold) || threshold < 0.05 || threshold > 1) {
+    throw new TypeError('Scene threshold must be between 0.05 and 1.');
+  }
+  if (!Number.isFinite(minimumSpacingSeconds) || minimumSpacingSeconds < 0 || minimumSpacingSeconds > 60) {
+    throw new TypeError('minimumSpacingSeconds must be between 0 and 60.');
+  }
+  if (!Number.isSafeInteger(maximumFindings) || maximumFindings < 1 || maximumFindings > 10000) {
+    throw new TypeError('maximumFindings must be an integer between 1 and 10000.');
+  }
+
+  const filter = `select=gt(scene\\,${threshold}),metadata=mode=print:key=lavfi.scene_score`;
+  let stderrBytes = 0;
+  const result = await runProcess('ffmpeg', [
+    '-nostdin', '-hide_banner', '-loglevel', 'info', '-i', media.path,
+    '-map', '0:v:0', '-vf', filter, '-an', '-sn', '-dn', '-f', 'null', '-',
+  ], {
+    signal: options.signal,
+    stdio: 'capture',
+    onStderr: (chunk) => { stderrBytes += chunk.length; },
+  });
+  if (stderrBytes >= 16 * 1024 * 1024) {
+    throw new RangeError('FFmpeg scene analysis exceeded the safe log size. Raise the threshold or analyze a shorter source range.');
+  }
+
+  const parsed = parseSceneDetectionOutput(result.stderr, media.durationSeconds);
+  const findings = suppressNearbyCuts(parsed, minimumSpacingSeconds);
+  if (findings.length > maximumFindings) {
+    throw new RangeError(`Scene detection found more than ${maximumFindings} cuts; increase maximumFindings or raise the threshold.`);
+  }
+
+  return {
+    providerId: 'ffmpeg-scene-detection',
+    analysis: {
+      schemaVersion: 1,
+      durationSeconds: media.durationSeconds,
+      findings: findings.map((finding, index) => ({
+        id: `finding-${String(index + 1).padStart(3, '0')}`,
+        type: 'scene-cut',
+        startSeconds: finding.startSeconds,
+        confidence: finding.confidence,
+        description: `FFmpeg scene-change score ${finding.confidence.toFixed(3)}. Review this candidate boundary.`,
+      })),
+    },
+    settings: { threshold, minimumSpacingSeconds },
+    reviewRequired: true,
+  };
+}
+
+export function parseSceneDetectionOutput(log, durationSeconds) {
+  if (typeof log !== 'string' || !Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    throw new TypeError('Scene detection output requires a log string and positive duration.');
+  }
+  const frames = [...log.matchAll(/frame:\s*\d+\s+pts:\s*-?\d+\s+pts_time:\s*(-?(?:\d+(?:\.\d*)?|\.\d+))/g)];
+  const findings = [];
+  for (let index = 0; index < frames.length; index++) {
+    const frame = frames[index];
+    const blockStart = frame.index + frame[0].length;
+    const blockEnd = index + 1 < frames.length ? frames[index + 1].index : log.length;
+    const scoreMatch = /lavfi\.scene_score\s*=\s*((?:\d+(?:\.\d*)?|\.\d+))/.exec(log.slice(blockStart, blockEnd));
+    if (!scoreMatch) continue;
+    const startSeconds = Number(frame[1]);
+    const confidence = Number(scoreMatch[1]);
+    if (!Number.isFinite(startSeconds) || startSeconds < 0 || startSeconds >= durationSeconds
+        || !Number.isFinite(confidence) || confidence < 0 || confidence > 1) continue;
+    findings.push({ startSeconds: round(startSeconds), confidence: round(confidence) });
+  }
+  return findings;
+}
+
+function suppressNearbyCuts(findings, minimumSpacingSeconds) {
+  const kept = [];
+  for (const finding of findings) {
+    const previous = kept.at(-1);
+    if (previous && finding.startSeconds - previous.startSeconds < minimumSpacingSeconds) {
+      if (finding.confidence > previous.confidence) kept[kept.length - 1] = finding;
+    } else {
+      kept.push(finding);
+    }
+  }
+  return kept;
+}
+
+function round(value) {
+  return Number(value.toFixed(3));
+}

package/src/media/scene-review.mjs

@@ -0,0 +1,205 @@
+import { copyFile, mkdir, mkdtemp, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { runProcess } from '../render/process.mjs';
+import { detectSceneChangesAsync } from './scene-detection.mjs';
+
+const DEFAULT_THUMBNAIL_SIZE = 320;
+const DEFAULT_CONTACT_SHEET_LIMIT = 60;
+const DEFAULT_MAXIMUM_SHOTS = 300;
+const CONTACT_SHEET_PIXEL_LIMIT = 64_000_000;
+
+/** Create a review-ready shot map with representative frames and a contact sheet. */
+export async function createSceneReviewPackAsync(inputPath, outputDirectory, options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('Scene review options must be an object.');
+  }
+  const allowedOptions = new Set([
+    'threshold', 'minimumSpacingSeconds', 'maximumFindings', 'maximumShots',
+    'thumbnailSize', 'contactSheetLimit', 'columns', 'signal', 'onProgress',
+  ]);
+  for (const key of Object.keys(options)) {
+    if (!allowedOptions.has(key)) throw new TypeError(`Unsupported scene review option: ${key}.`);
+  }
+  if (options.onProgress !== undefined && typeof options.onProgress !== 'function') {
+    throw new TypeError('onProgress must be a function.');
+  }
+
+  const output = resolve(outputDirectory);
+  if (existsSync(output)) throw new Error(`Scene review output already exists: ${output}`);
+  const maximumShots = options.maximumShots ?? DEFAULT_MAXIMUM_SHOTS;
+  const thumbnailSize = options.thumbnailSize ?? DEFAULT_THUMBNAIL_SIZE;
+  const contactSheetLimit = options.contactSheetLimit ?? DEFAULT_CONTACT_SHEET_LIMIT;
+  const columns = options.columns ?? 4;
+  validateIntegerRange(maximumShots, 1, 2000, 'maximumShots');
+  validateIntegerRange(thumbnailSize, 80, 1280, 'thumbnailSize');
+  validateIntegerRange(contactSheetLimit, 1, 120, 'contactSheetLimit');
+  validateIntegerRange(columns, 1, 8, 'columns');
+
+  emitProgress(options.onProgress, { stage: 'scene-source-fingerprint', phase: 'started' });
+  const sourceSha256 = await hashFileAsync(resolve(inputPath), options.signal);
+  emitProgress(options.onProgress, { stage: 'scene-source-fingerprint', phase: 'completed' });
+  emitProgress(options.onProgress, { stage: 'scene-analysis', phase: 'started' });
+  const analysis = await detectSceneChangesAsync(inputPath, {
+    ...(options.threshold !== undefined ? { threshold: options.threshold } : {}),
+    ...(options.minimumSpacingSeconds !== undefined ? { minimumSpacingSeconds: options.minimumSpacingSeconds } : {}),
+    ...(options.maximumFindings !== undefined ? { maximumFindings: options.maximumFindings } : {}),
+    signal: options.signal,
+  });
+  emitProgress(options.onProgress, { stage: 'scene-analysis', phase: 'completed', completed: 1, total: 1 });
+  const shots = buildShotRanges(analysis);
+  if (shots.length > maximumShots) {
+    throw new RangeError(`Scene review found ${shots.length} shots, above maximumShots ${maximumShots}. Raise minimumSpacingSeconds or increase maximumShots.`);
+  }
+
+  const parent = dirname(output);
+  await mkdir(parent, { recursive: true });
+  const staging = await mkdtemp(join(parent, `.${basename(output)}-${randomUUID()}-`));
+  try {
+    const thumbnailDirectory = join(staging, 'thumbnails');
+    await mkdir(thumbnailDirectory);
+    emitProgress(options.onProgress, { stage: 'scene-thumbnails', phase: 'started', completed: 0, total: shots.length });
+    for (const shot of shots) {
+      throwIfAborted(options.signal);
+      const thumbnailName = `shot-${String(shot.index).padStart(4, '0')}.jpg`;
+      const thumbnailPath = join(thumbnailDirectory, thumbnailName);
+      const fit = `scale=${thumbnailSize}:${thumbnailSize}:force_original_aspect_ratio=decrease,pad=${thumbnailSize}:${thumbnailSize}:(ow-iw)/2:(oh-ih)/2:color=black`;
+      await runProcess('ffmpeg', [
+        '-nostdin', '-hide_banner', '-loglevel', 'error', '-ss', String(shot.previewSeconds),
+        '-i', resolve(inputPath), '-map', '0:v:0', '-frames:v', '1', '-vf', fit,
+        '-q:v', '3', thumbnailPath,
+      ], { signal: options.signal });
+      if ((await stat(thumbnailPath)).size === 0) throw new Error(`FFmpeg produced an empty thumbnail for shot ${shot.index}.`);
+      shot.thumbnail = `thumbnails/${thumbnailName}`;
+      emitProgress(options.onProgress, {
+        stage: 'scene-thumbnails',
+        phase: 'progress',
+        completed: shot.index,
+        total: shots.length,
+        percent: shot.index / shots.length * 100,
+      });
+    }
+    emitProgress(options.onProgress, { stage: 'scene-thumbnails', phase: 'completed', completed: shots.length, total: shots.length });
+
+    const sheetShots = sampleShots(shots, contactSheetLimit);
+    const sheetColumns = Math.min(columns, sheetShots.length);
+    const sheetRows = Math.ceil(sheetShots.length / sheetColumns);
+    const sheetWidth = sheetColumns * thumbnailSize + (sheetColumns + 1) * 12;
+    const sheetHeight = sheetRows * thumbnailSize + (sheetRows + 1) * 12;
+    if (sheetWidth * sheetHeight > CONTACT_SHEET_PIXEL_LIMIT) {
+      throw new RangeError(`Contact sheet would exceed ${CONTACT_SHEET_PIXEL_LIMIT} pixels. Reduce thumbnailSize, contactSheetLimit, or columns.`);
+    }
+    const sheetInputDirectory = join(staging, 'contact-input');
+    await mkdir(sheetInputDirectory);
+    for (const [index, shot] of sheetShots.entries()) {
+      throwIfAborted(options.signal);
+      await copyFile(
+        join(staging, shot.thumbnail),
+        join(sheetInputDirectory, `frame-${String(index + 1).padStart(4, '0')}.jpg`),
+      );
+    }
+    const pattern = join(sheetInputDirectory, 'frame-%04d.jpg');
+    const sheetPath = join(staging, 'contact-sheet.jpg');
+    const sheetFilter = `tile=${sheetColumns}x${sheetRows}:padding=12:margin=12:color=white`;
+    emitProgress(options.onProgress, { stage: 'scene-contact-sheet', phase: 'started' });
+    await runProcess('ffmpeg', [
+      '-nostdin', '-hide_banner', '-loglevel', 'error', '-framerate', '1', '-start_number', '1',
+      '-i', pattern, '-vf', sheetFilter, '-frames:v', '1', '-q:v', '3', sheetPath,
+    ], { signal: options.signal });
+    if ((await stat(sheetPath)).size === 0) throw new Error('FFmpeg produced an empty scene contact sheet.');
+    await rm(sheetInputDirectory, { recursive: true, force: true });
+    emitProgress(options.onProgress, { stage: 'scene-contact-sheet', phase: 'completed' });
+
+    const result = {
+      schemaVersion: 2,
+      sourceSha256,
+      providerId: analysis.providerId,
+      durationSeconds: analysis.analysis.durationSeconds,
+      settings: analysis.settings,
+      reviewRequired: true,
+      shotCount: shots.length,
+      contactSheet: 'contact-sheet.jpg',
+      contactSheetShotIndexes: sheetShots.map(({ index }) => index),
+      shots,
+      analysis: analysis.analysis,
+    };
+    await writeFile(join(staging, 'scene-review.json'), `${JSON.stringify(result, null, 2)}\n`, { flag: 'wx' });
+    throwIfAborted(options.signal);
+    emitProgress(options.onProgress, { stage: 'scene-review-publish', phase: 'started' });
+    await rename(staging, output);
+    emitProgress(options.onProgress, { stage: 'scene-review-publish', phase: 'completed' });
+    return { ...result, outputDirectory: output };
+  } catch (error) {
+    emitProgress(options.onProgress, { stage: 'scene-review-pack', phase: 'failed', message: error.message });
+    await rm(staging, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export function buildShotRanges(analysis) {
+  const durationSeconds = analysis?.analysis?.durationSeconds;
+  const findings = analysis?.analysis?.findings;
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0 || !Array.isArray(findings)) {
+    throw new TypeError('Scene analysis must contain a positive duration and findings array.');
+  }
+  const boundaries = [0, ...findings
+    .filter((finding) => finding.type === 'scene-cut')
+    .map((finding) => finding.startSeconds)
+    .filter((time) => Number.isFinite(time) && time > 0 && time < durationSeconds), durationSeconds]
+    .sort((left, right) => left - right)
+    .filter((time, index, all) => index === 0 || time - all[index - 1] > 1e-6);
+
+  return boundaries.slice(0, -1).map((startSeconds, index) => {
+    const endSeconds = boundaries[index + 1];
+    const previewSeconds = startSeconds + Math.min(0.5, (endSeconds - startSeconds) / 2);
+    return {
+      index: index + 1,
+      startSeconds: round(startSeconds),
+      endSeconds: round(endSeconds),
+      durationSeconds: round(endSeconds - startSeconds),
+      previewSeconds: round(previewSeconds),
+    };
+  });
+}
+
+function sampleShots(shots, limit) {
+  if (shots.length <= limit) return shots;
+  if (limit === 1) return [shots[0]];
+  const selected = new Map();
+  for (let index = 0; index < limit; index += 1) {
+    const sourceIndex = Math.round(index * (shots.length - 1) / (limit - 1));
+    selected.set(shots[sourceIndex].index, shots[sourceIndex]);
+  }
+  return [...selected.values()];
+}
+
+function validateIntegerRange(value, minimum, maximum, name) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new TypeError(`${name} must be an integer between ${minimum} and ${maximum}.`);
+  }
+}
+
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    if (signal.reason instanceof Error) throw signal.reason;
+    const error = new Error('Scene review cancelled.');
+    error.name = 'AbortError';
+    throw error;
+  }
+}
+
+function emitProgress(onProgress, event) {
+  try { onProgress?.({ ...event }); } catch { /* Progress observers must not interrupt media processing. */ }
+}
+
+async function hashFileAsync(path, signal) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(path, { signal })) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+function round(value) {
+  return Number(value.toFixed(6));
+}