aivee 0.0.0-stage → 0.1.0-dev.7025438

package/src/doctor.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { listFfmpegEncoders, listFfmpegFilters } from './media/ffmpeg-capabilities.mjs';
+import { doctorHyperframes } from './render/hyperframes.mjs';
+
+const nodeVersion = process.versions.node.split('.').map(Number);
+const require = createRequire(import.meta.url);
+const results = [
+  {
+    name: 'Node.js',
+    ok: nodeVersion[0] >= 22,
+    detail: `found ${process.versions.node}; requires 22 or newer`,
+  },
+  checkCommand('FFmpeg', 'ffmpeg'),
+  checkCommand('ffprobe', 'ffprobe'),
+  checkPackage('HyperFrames', 'hyperframes'),
+  checkPackage('GSAP', 'gsap'),
+];
+
+for (const result of results) {
+  console.log(`${result.ok ? '✓' : '✗'} ${result.name}: ${result.detail}`);
+  if (!result.ok && result.name !== 'Node.js') {
+    if (result.name === 'FFmpeg' || result.name === 'ffprobe') {
+      console.log('  Install FFmpeg with ffprobe and make both commands available on PATH.');
+      console.log('  Guide: https://ffmpeg.org/download.html');
+    } else if (result.name === 'HyperFrames' || result.name === 'GSAP') {
+      console.log('  Run npm install in the engine repository.');
+    }
+  } else if (!result.ok && result.name === 'Node.js') {
+    console.log('  Install Node.js 22 or newer: https://nodejs.org/en/download');
+  }
+}
+
+const ready = results.every((result) => result.ok);
+const otioPython = process.env.AIVE_OTIO_PYTHON || process.env.PYTHON || 'python';
+const openTimelineIO = checkPythonModule('OpenTimelineIO', otioPython);
+console.log(`${openTimelineIO.ok ? '✓' : '⚠'} Optional ${openTimelineIO.name}: ${openTimelineIO.detail}`);
+if (!openTimelineIO.ok) {
+  console.log('  Install with `python -m pip install -r requirements-otio.txt` or set `AIVE_OTIO_PYTHON` to a Python command with OpenTimelineIO installed.');
+}
+if (results.find((result) => result.name === 'HyperFrames')?.ok) {
+  console.log('\nChecking HyperFrames renderer requirements:');
+  try {
+    doctorHyperframes(process.cwd());
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+console.log(ready
+  ? 'Core Engine requirements are available; optional and feature-specific tools are reported above.'
+  : 'Some required Engine tools are missing.');
+try {
+  const filters = listFfmpegFilters();
+  for (const [filter, requirement] of [
+    ['rubberband', 'pitch-preserving audio speed ramps'],
+    ['equalizer', 'audio equalization and mastering bands'],
+    ['highpass', 'audio high-pass filtering'],
+    ['lowpass', 'audio low-pass filtering'],
+    ['acompressor', 'audio compression effects'],
+    ['afftdn', 'per-clip spectral denoise'],
+    ['stereotools', 'per-clip stereo balance'],
+    ['sidechaincompress', 'signal-aware sidechain compression'],
+    ['loudnorm', 'audio loudness mastering'],
+    ['alimiter', 'audio peak limiting'],
+    ['aresample', 'mastered output channel mapping'],
+    ['reverse', 'video reverse playback'],
+    ['areverse', 'audio reverse playback'],
+    ['colorspace', 'Rec.709 and Rec.2020 SDR output profiles'],
+    ['zscale', 'HDR10 output'],
+  ]) {
+    const available = filters.has(filter);
+    console.log(`${available ? '✓' : '⚠'} FFmpeg ${filter} filter: ${available ? 'available' : `not available; required for ${requirement}`}`);
+  }
+} catch (error) {
+  console.log(`⚠ FFmpeg filters: could not verify (${error.message})`);
+}
+if (results.find((result) => result.name === 'FFmpeg')?.ok) {
+  try {
+    const encoders = listFfmpegEncoders();
+    for (const [name, encoder] of [['H.264', 'libx264'], ['H.265', 'libx265'], ['VP9', 'libvpx-vp9'], ['ProRes', 'prores_ks']]) {
+      const available = encoders.has(encoder);
+      console.log(`${available ? '✓' : '⚠'} FFmpeg ${name} encoder: ${available ? 'available' : `not available (${encoder})`}`);
+    }
+  } catch (error) {
+    console.log(`⚠ FFmpeg encoders: could not verify (${error.message})`);
+  }
+}
+if (!ready) process.exitCode = 1;
+
+function checkCommand(label, command, args = ['-version']) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    return { name: label, ok: false, detail: 'not found or failed to run' };
+  }
+  const firstLine = result.stdout.trim().split(/\r?\n/, 1)[0];
+  return { name: label, ok: true, detail: firstLine };
+}
+
+function checkPackage(label, packageName) {
+  try {
+    require.resolve(`${packageName}/package.json`);
+    return { name: label, ok: true, detail: 'installed' };
+  } catch {
+    return { name: label, ok: false, detail: 'not installed' };
+  }
+}
+
+function checkPythonModule(label, command) {
+  const result = spawnSync(command, ['-c', "import opentimelineio as otio; assert 'otio_json' in otio.adapters.available_adapter_names(), 'otio_json adapter unavailable'; print(getattr(otio, '__version__', 'installed'))"], {
+    encoding: 'utf8',
+    windowsHide: true,
+    maxBuffer: 1024 * 1024,
+  });
+  if (result.error) return { name: label, ok: false, detail: `Python command unavailable (${command})` };
+  if (result.status !== 0) {
+    const details = `${result.stderr}\n${result.stdout}`;
+    return {
+      name: label,
+      ok: false,
+      detail: /No module named ['"]?opentimelineio/.test(details)
+        ? 'Python package not installed'
+        : /otio_json adapter unavailable/.test(details)
+          ? 'JSON adapter not available'
+          : 'Python package failed to import',
+    };
+  }
+  return { name: label, ok: true, detail: `Python package ${result.stdout.trim().split(/\r?\n/, 1)[0]}` };
+}

package/src/edits/analysis-to-edl.mjs

@@ -0,0 +1,43 @@
+import { validateEdl } from './retime-transcript.mjs';
+import { normalizeMediaFindings } from '../media/analysis-provider.mjs';
+
+/** Convert explicit provider cut suggestions into an EDL that requires review. */
+export function mediaAnalysisToEdl(analysis, { minConfidence = 0 } = {}) {
+  if (!analysis || typeof analysis !== 'object' || analysis.schemaVersion !== 1
+      || !Number.isFinite(analysis.durationSeconds) || analysis.durationSeconds <= 0
+      || !Array.isArray(analysis.findings)) {
+    throw new TypeError('Media analysis must be a normalized schemaVersion 1 result.');
+  }
+  if (!Number.isFinite(minConfidence) || minConfidence < 0 || minConfidence > 1) {
+    throw new TypeError('minConfidence must be between 0 and 1.');
+  }
+  const normalizedFindings = normalizeMediaFindings({ findings: analysis.findings }, analysis.durationSeconds).findings;
+
+  const cuts = normalizedFindings
+    .filter((finding) => finding.suggestion && (finding.confidence ?? 0) >= minConfidence)
+    .map((finding) => ({
+      sourceStart: finding.suggestion.sourceStart,
+      sourceEnd: finding.suggestion.sourceEnd,
+      reason: `${finding.id}: ${finding.suggestion.reason}`,
+    }))
+    .sort((left, right) => left.sourceStart - right.sourceStart || left.sourceEnd - right.sourceEnd)
+    .reduce((result, cut) => {
+      const previous = result.at(-1);
+      if (previous && cut.sourceStart < previous.sourceEnd) {
+        previous.sourceEnd = Math.max(previous.sourceEnd, cut.sourceEnd);
+        previous.reason = `${previous.reason}; ${cut.reason}`;
+      } else {
+        result.push(cut);
+      }
+      return result;
+    }, []);
+
+  const edl = {
+    schemaVersion: 1,
+    sourceDurationSeconds: analysis.durationSeconds,
+    reviewStatus: 'needs-review',
+    cuts,
+  };
+  validateEdl(edl, analysis.durationSeconds);
+  return edl;
+}

package/src/edits/detect-silence.mjs

@@ -0,0 +1,51 @@
+import { spawnSync } from 'node:child_process';
+import { probeMedia } from '../media/probe.mjs';
+import { validateEdl } from './retime-transcript.mjs';
+
+export function detectAcousticSilence(inputPath, options = {}) {
+  const media = probeMedia(inputPath, { requireVideo: false });
+  if (!media.hasAudio) throw new TypeError('Acoustic silence detection requires an audio stream.');
+  const noiseDb = options.noiseDb ?? -35;
+  const minSilenceSeconds = options.minSilenceSeconds ?? 0.5;
+  const paddingSeconds = options.paddingSeconds ?? 0.12;
+  if (!Number.isFinite(noiseDb) || noiseDb < -90 || noiseDb > 0) throw new TypeError('noiseDb must be between -90 and 0.');
+  if (!Number.isFinite(minSilenceSeconds) || minSilenceSeconds <= 0) throw new TypeError('minSilenceSeconds must be positive.');
+  if (!Number.isFinite(paddingSeconds) || paddingSeconds < 0) throw new TypeError('paddingSeconds must be non-negative.');
+
+  const result = spawnSync('ffmpeg', [
+    '-nostdin', '-hide_banner', '-i', media.path,
+    '-af', `silencedetect=noise=${noiseDb}dB:d=${minSilenceSeconds}`,
+    '-f', 'null', '-',
+  ], { encoding: 'utf8', windowsHide: true });
+  if (result.error || result.status !== 0) throw new Error(`FFmpeg silence detection failed: ${result.error?.message ?? result.stderr.trim()}`);
+
+  const intervals = parseSilenceIntervals(result.stderr, media.durationSeconds);
+  const cuts = intervals.flatMap(({ start, end }) => {
+    const sourceStart = round(start + paddingSeconds);
+    const sourceEnd = round(end - paddingSeconds);
+    return sourceEnd > sourceStart ? [{ sourceStart, sourceEnd, reason: `acoustic silence (${round(end - start)}s)` }] : [];
+  });
+  const edl = { schemaVersion: 1, sourceDurationSeconds: media.durationSeconds, cuts };
+  validateEdl(edl, media.durationSeconds);
+  return edl;
+}
+
+export function parseSilenceIntervals(log, durationSeconds) {
+  const intervals = [];
+  const events = /silence_(start|end):\s*(-?(?:\d+(?:\.\d*)?|\.\d+))/g;
+  let silenceStart;
+  for (const match of log.matchAll(events)) {
+    const time = Number(match[2]);
+    if (match[1] === 'start') silenceStart = Math.max(0, time);
+    else if (silenceStart !== undefined && time > silenceStart) {
+      intervals.push({ start: silenceStart, end: Math.min(time, durationSeconds) });
+      silenceStart = undefined;
+    }
+  }
+  if (silenceStart !== undefined && durationSeconds > silenceStart) intervals.push({ start: silenceStart, end: durationSeconds });
+  return intervals;
+}
+
+function round(value) {
+  return Number(value.toFixed(3));
+}

package/src/edits/find-mistake-candidates.mjs

@@ -0,0 +1,42 @@
+import { validateTranscript } from '../transcript/validate.mjs';
+
+export function findMistakeCandidates(transcript, { maxRepeatGap = 0.5 } = {}) {
+  validateTranscript(transcript);
+  if (transcript.granularity === 'cue') {
+    throw new TypeError('Mistake candidates require a word-level transcript.');
+  }
+  if (!Number.isFinite(maxRepeatGap) || maxRepeatGap < 0) {
+    throw new TypeError('maxRepeatGap must be a non-negative number.');
+  }
+
+  const candidates = [];
+  for (let index = 1; index < transcript.words.length; index++) {
+    const first = transcript.words[index - 1];
+    const second = transcript.words[index];
+    const firstToken = normalize(first.text);
+    const secondToken = normalize(second.text);
+    const gap = second.start - first.end;
+    if (!firstToken || firstToken !== secondToken || gap < 0 || gap > maxRepeatGap) continue;
+
+    candidates.push({
+      id: `repeat-${String(candidates.length + 1).padStart(3, '0')}`,
+      type: 'repeated-word',
+      confidence: 'review',
+      cut: {
+        sourceStart: first.start,
+        sourceEnd: second.start,
+        reason: `possible repeated word: ${first.text}`,
+      },
+      removes: first.text,
+      keeps: second.text,
+      context: transcript.words.slice(Math.max(0, index - 4), Math.min(transcript.words.length, index + 4))
+        .map((word) => word.text)
+        .join(' '),
+    });
+  }
+  return candidates;
+}
+
+function normalize(text) {
+  return text.toLowerCase().normalize('NFKC').replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '');
+}

package/src/edits/plan-shot-placements.mjs

@@ -0,0 +1,105 @@
+import { previewTimelineEdit } from '../timeline/edit.mjs';
+import { timelineFingerprint } from '../timeline/fingerprint.mjs';
+
+const MAXIMUM_PLACEMENTS = 500;
+
+/** Build a review-only clip insertion plan from explicit scene-review selections. */
+export function planSceneReviewPlacements(timeline, sceneReview, assetId, trackId, placements) {
+  if (!sceneReview || typeof sceneReview !== 'object' || Array.isArray(sceneReview)
+      || sceneReview.schemaVersion !== 2 || sceneReview.reviewRequired !== true
+      || !/^[a-f0-9]{64}$/.test(sceneReview.sourceSha256 ?? '')
+      || !Array.isArray(sceneReview.shots) || !Number.isFinite(sceneReview.durationSeconds)
+      || sceneReview.durationSeconds <= 0) {
+    throw new TypeError('Scene review must be a schemaVersion 2 review-required pack with a SHA-256 source identity, positive duration, and shots array. Regenerate older packs.');
+  }
+  if (!Array.isArray(placements) || placements.length === 0 || placements.length > MAXIMUM_PLACEMENTS) {
+    throw new TypeError(`placements must contain between 1 and ${MAXIMUM_PLACEMENTS} shot selections.`);
+  }
+  if (typeof assetId !== 'string' || !assetId.trim()) throw new TypeError('assetId must be a non-empty string.');
+  if (typeof trackId !== 'string' || !trackId.trim()) throw new TypeError('trackId must be a non-empty string.');
+
+  const asset = timeline?.assets?.find((candidate) => candidate.id === assetId);
+  if (!asset || asset.type !== 'video' || !Number.isFinite(asset.durationSeconds) || asset.durationSeconds <= 0) {
+    throw new TypeError(`B-roll asset ${assetId} must be a registered video asset with a known duration.`);
+  }
+  if (asset.sha256 !== sceneReview.sourceSha256) {
+    throw new TypeError(`B-roll asset ${assetId} does not match the source media used by this scene-review pack.`);
+  }
+  const track = timeline?.tracks?.find((candidate) => candidate.id === trackId);
+  if (!track || track.kind !== 'video') throw new TypeError(`B-roll destination ${trackId} must be an existing video track.`);
+  if (track.locked === true) throw new TypeError(`B-roll destination track ${trackId} is locked.`);
+
+  const shots = new Map();
+  for (const shot of sceneReview.shots) {
+    if (!shot || !Number.isSafeInteger(shot.index) || shot.index < 1
+        || !Number.isFinite(shot.startSeconds) || !Number.isFinite(shot.endSeconds)
+        || shot.startSeconds < 0 || shot.endSeconds <= shot.startSeconds
+        || shot.endSeconds > sceneReview.durationSeconds + 1e-6
+        || shots.has(shot.index)) {
+      throw new TypeError('Scene review contains an invalid or duplicate shot range.');
+    }
+    shots.set(shot.index, shot);
+  }
+
+  const usedClipIds = new Set();
+  const operations = placements.map((placement, index) => {
+    if (!placement || typeof placement !== 'object' || Array.isArray(placement)) {
+      throw new TypeError(`Placement ${index + 1} must be an object.`);
+    }
+    const allowedFields = new Set(['shotIndex', 'timelineStartSeconds', 'sourceOffsetSeconds', 'durationSeconds', 'clipId']);
+    if (Object.keys(placement).some((field) => !allowedFields.has(field))) {
+      throw new TypeError(`Placement ${index + 1} contains an unsupported field.`);
+    }
+    if (Object.values(placement).some((value) => value === undefined)) {
+      throw new TypeError(`Placement ${index + 1} fields must not be undefined.`);
+    }
+    const shot = shots.get(placement.shotIndex);
+    if (!shot) throw new TypeError(`Placement ${index + 1} references unknown shot ${placement.shotIndex}.`);
+    const timelineStart = placement.timelineStartSeconds;
+    const sourceOffset = placement.sourceOffsetSeconds ?? 0;
+    if (!Number.isFinite(timelineStart) || timelineStart < 0) {
+      throw new TypeError(`Placement ${index + 1} timelineStartSeconds must be non-negative.`);
+    }
+    if (!Number.isFinite(sourceOffset) || sourceOffset < 0 || sourceOffset >= shot.endSeconds - shot.startSeconds) {
+      throw new TypeError(`Placement ${index + 1} sourceOffsetSeconds must fall within shot ${shot.index}.`);
+    }
+    const sourceIn = shot.startSeconds + sourceOffset;
+    const durationSeconds = placement.durationSeconds ?? shot.endSeconds - sourceIn;
+    if (!Number.isFinite(durationSeconds) || durationSeconds <= 0
+        || sourceIn + durationSeconds > shot.endSeconds + 1e-6) {
+      throw new TypeError(`Placement ${index + 1} durationSeconds must fit within shot ${shot.index}.`);
+    }
+    if (sourceIn + durationSeconds > asset.durationSeconds + 1e-6) {
+      throw new TypeError(`Placement ${index + 1} source range exceeds B-roll asset ${assetId}.`);
+    }
+    const clipId = placement.clipId ?? `broll-shot-${String(index + 1).padStart(4, '0')}`;
+    if (!/^[a-z][a-z0-9-]*$/.test(clipId) || usedClipIds.has(clipId)) {
+      throw new TypeError(`Placement ${index + 1} clipId must be a unique kebab-case id.`);
+    }
+    usedClipIds.add(clipId);
+    return {
+      type: 'add-clip',
+      trackId,
+      clip: {
+        id: clipId,
+        assetId,
+        timelineStart,
+        sourceIn,
+        sourceOut: sourceIn + durationSeconds,
+        durationSeconds,
+      },
+    };
+  });
+
+  return {
+    schemaVersion: 1,
+    type: 'scene-review-placement-plan',
+    reviewRequired: true,
+    baseTimelineSha256: timelineFingerprint(timeline),
+    sourceSha256: sceneReview.sourceSha256,
+    assetId,
+    trackId,
+    operations,
+    preview: previewTimelineEdit(timeline, operations),
+  };
+}

package/src/edits/plan-silence-cuts.mjs

@@ -0,0 +1,49 @@
+import { validateTranscript } from '../transcript/validate.mjs';
+import { validateEdl } from './retime-transcript.mjs';
+
+export function planSilenceCuts(transcript, options = {}) {
+  validateTranscript(transcript);
+  const { minGap = 0.55, headPad = 0.22, tailPad = 0.34 } = options;
+  for (const [name, value] of Object.entries({ minGap, headPad, tailPad })) {
+    if (!Number.isFinite(value) || value < 0 || (name === 'minGap' && value === 0)) {
+      throw new TypeError(`${name} must be ${name === 'minGap' ? 'positive' : 'non-negative'}.`);
+    }
+  }
+  if (transcript.words.length === 0) throw new TypeError('Cannot plan silence cuts without timed words.');
+
+  const words = transcript.words;
+  const cuts = [];
+  const headEnd = words[0].start - headPad;
+  if (headEnd > 0) cuts.push({ sourceStart: 0, sourceEnd: headEnd, reason: 'head silence' });
+
+  for (let index = 1; index < words.length; index++) {
+    const previous = words[index - 1];
+    const next = words[index];
+    const gap = next.start - previous.end;
+    if (gap < minGap) continue;
+
+    const keep = gap >= 2 ? 0.24 : /[.!?]$/.test(previous.text) ? 0.2 : 0.14;
+    const sourceStart = previous.end + keep * 0.55;
+    const sourceEnd = next.start - keep * 0.45;
+    if (sourceEnd > sourceStart) {
+      cuts.push({
+        sourceStart: round(sourceStart),
+        sourceEnd: round(sourceEnd),
+        reason: `pause ${gap.toFixed(2)}s shortened to ${keep.toFixed(2)}s`,
+      });
+    }
+  }
+
+  const tailStart = words.at(-1).end + tailPad;
+  if (tailStart < transcript.durationSeconds) {
+    cuts.push({ sourceStart: tailStart, sourceEnd: transcript.durationSeconds, reason: 'tail silence' });
+  }
+
+  const edl = { schemaVersion: 1, sourceDurationSeconds: transcript.durationSeconds, cuts };
+  validateEdl(edl, transcript.durationSeconds);
+  return edl;
+}
+
+function round(value) {
+  return Number(value.toFixed(3));
+}

package/src/edits/retime-transcript.mjs

@@ -0,0 +1,105 @@
+import { validateTranscript } from '../transcript/validate.mjs';
+
+export function retimeTranscript(transcript, edl) {
+  validateTranscript(transcript);
+  validateEdl(edl, transcript.durationSeconds);
+  assertEdlApproved(edl);
+
+  const words = transcript.words.flatMap((word) => {
+    const containingCut = edl.cuts.find(
+      (cut) => cut.sourceStart <= word.start && cut.sourceEnd >= word.end
+    );
+    if (containingCut) return [];
+
+    const partialCut = edl.cuts.find(
+      (cut) => cut.sourceStart < word.end && cut.sourceEnd > word.start
+    );
+    if (partialCut) {
+      throw new TypeError(`EDL cut ${partialCut.sourceStart}-${partialCut.sourceEnd} splits transcript word "${word.text}".`);
+    }
+
+    const removedBefore = edl.cuts
+      .filter((cut) => cut.sourceEnd <= word.start)
+      .reduce((total, cut) => total + cut.sourceEnd - cut.sourceStart, 0);
+    return [{ ...word, start: word.start - removedBefore, end: word.end - removedBefore }];
+  });
+
+  const removedDuration = edl.cuts.reduce(
+    (total, cut) => total + cut.sourceEnd - cut.sourceStart,
+    0
+  );
+  if (removedDuration >= transcript.durationSeconds) {
+    throw new TypeError('EDL must leave a positive output duration.');
+  }
+  return {
+    schemaVersion: 1,
+    durationSeconds: transcript.durationSeconds - removedDuration,
+    ...(transcript.granularity ? { granularity: transcript.granularity } : {}),
+    words,
+  };
+}
+
+export function validateEdl(edl, sourceDurationSeconds) {
+  if (!edl || typeof edl !== 'object' || Array.isArray(edl)) {
+    throw new TypeError('EDL must be a JSON object.');
+  }
+  if (edl.schemaVersion !== 1) {
+    throw new TypeError('EDL schemaVersion must be 1.');
+  }
+  if (!Number.isFinite(edl.sourceDurationSeconds) || edl.sourceDurationSeconds <= 0) {
+    throw new TypeError('EDL sourceDurationSeconds must be a positive number.');
+  }
+  if (Math.abs(edl.sourceDurationSeconds - sourceDurationSeconds) > 1e-6) {
+    throw new TypeError('EDL sourceDurationSeconds must match the transcript duration.');
+  }
+  if (edl.reviewStatus !== undefined && !['needs-review', 'approved'].includes(edl.reviewStatus)) {
+    throw new TypeError('EDL reviewStatus must be needs-review or approved.');
+  }
+  if (!Array.isArray(edl.cuts)) {
+    throw new TypeError('EDL cuts must be an array.');
+  }
+
+  let previousEnd = 0;
+  for (const [index, cut] of edl.cuts.entries()) {
+    const label = `EDL cut ${index + 1}`;
+    if (!cut || typeof cut !== 'object' || Array.isArray(cut)) {
+      throw new TypeError(`${label} must be an object.`);
+    }
+    if (!Number.isFinite(cut.sourceStart) || !Number.isFinite(cut.sourceEnd) || cut.sourceStart < 0 || cut.sourceEnd <= cut.sourceStart) {
+      throw new TypeError(`${label} must have finite times with 0 <= sourceStart < sourceEnd.`);
+    }
+    if (cut.sourceEnd > sourceDurationSeconds) {
+      throw new TypeError(`${label} ends after the source duration.`);
+    }
+    if (cut.sourceStart < previousEnd) {
+      throw new TypeError(`${label} overlaps or is out of order.`);
+    }
+    if (typeof cut.reason !== 'string' || !cut.reason.trim()) {
+      throw new TypeError(`${label} reason must be a non-empty string.`);
+    }
+    previousEnd = cut.sourceEnd;
+  }
+  const removedDuration = edl.cuts.reduce(
+    (total, cut) => total + cut.sourceEnd - cut.sourceStart,
+    0
+  );
+  if (removedDuration >= sourceDurationSeconds) {
+    throw new TypeError('EDL must leave a positive output duration.');
+  }
+  return edl;
+}
+
+export function approveEdl(edl) {
+  validateEdl(edl, edl?.sourceDurationSeconds);
+  if (edl.reviewStatus !== 'needs-review') throw new TypeError('Only an EDL marked needs-review can be approved.');
+  const approved = structuredClone(edl);
+  approved.reviewStatus = 'approved';
+  return approved;
+}
+
+export function assertEdlApproved(edl) {
+  if (edl?.reviewStatus === 'needs-review') {
+    throw new TypeError('EDL contains unapproved edit suggestions; review and approve it before editing.');
+  }
+  return edl;
+}

package/src/files.mjs

@@ -0,0 +1,80 @@
+import { closeSync, createReadStream, linkSync, openSync, readSync, rmSync, statSync, writeSync } from 'node:fs';
+import { link, open, rm } from 'node:fs/promises';
+import { Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+/** Publish a staged file without overwriting an existing destination. */
+export function linkOrCopySync(source, destination) {
+  try {
+    linkSync(source, destination);
+  } catch (error) {
+    if (!isUnsupportedHardLinkError(error)) throw error;
+    copyFileExclusiveSync(source, destination);
+  }
+}
+
+/** Publish a staged file asynchronously and report bytes only when copied. */
+export async function linkOrCopyAsync(source, destination, { signal, onCopyProgress } = {}) {
+  try {
+    await link(source, destination);
+  } catch (error) {
+    if (!isUnsupportedHardLinkError(error)) throw error;
+    const destinationHandle = await open(destination, 'wx');
+    try {
+      const progress = onCopyProgress ? createCopyProgress(source, onCopyProgress) : undefined;
+      const streams = [createReadStream(source, { signal }), ...(progress ? [progress] : []), destinationHandle.createWriteStream()];
+      await pipeline(...streams, { signal });
+    } catch (copyError) {
+      await destinationHandle.close().catch(() => {});
+      await rm(destination, { force: true }).catch(() => {});
+      throw copyError;
+    }
+  }
+}
+
+function isUnsupportedHardLinkError(error) {
+  return ['EPERM', 'EXDEV', 'ENOSYS', 'ENOTSUP', 'EOPNOTSUPP'].includes(error?.code);
+}
+
+function copyFileExclusiveSync(source, destination) {
+  let sourceDescriptor;
+  let destinationDescriptor;
+  try {
+    sourceDescriptor = openSync(source, 'r');
+    destinationDescriptor = openSync(destination, 'wx');
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let bytesRead;
+    while ((bytesRead = readSync(sourceDescriptor, buffer, 0, buffer.length, null)) > 0) {
+      let offset = 0;
+      while (offset < bytesRead) offset += writeSync(destinationDescriptor, buffer, offset, bytesRead - offset);
+    }
+    closeSync(destinationDescriptor);
+    destinationDescriptor = undefined;
+  } catch (error) {
+    if (destinationDescriptor !== undefined) {
+      try { closeSync(destinationDescriptor); } catch { /* Preserve the original copy error. */ }
+      destinationDescriptor = undefined;
+      try { rmSync(destination, { force: true }); } catch { /* Preserve the original copy error. */ }
+    }
+    throw error;
+  } finally {
+    if (sourceDescriptor !== undefined) closeSync(sourceDescriptor);
+  }
+}
+
+function createCopyProgress(source, onCopyProgress) {
+  const totalBytes = statSync(source).size;
+  let completedBytes = 0;
+  let lastPercent = -1;
+  return new Transform({
+    transform(chunk, encoding, callback) {
+      completedBytes += chunk.length;
+      const percent = totalBytes > 0 ? Math.floor(completedBytes / totalBytes * 100) : 100;
+      if (percent > lastPercent || completedBytes >= totalBytes) {
+        lastPercent = percent;
+        onCopyProgress(completedBytes, totalBytes);
+      }
+      callback(null, chunk);
+    },
+  });
+}

package/src/index.mjs

@@ -0,0 +1,44 @@
+export { validateTranscript } from './transcript/validate.mjs';
+export { getEngineCapabilities } from './capabilities.mjs';
+export { validateTimeline } from './timeline/validate.mjs';
+export { inspectTimeline } from './timeline/inspect.mjs';
+export { blendModeStyle, validateBlendMode } from './timeline/blend-mode.mjs';
+export { timelineForRender } from './timeline/track-state.mjs';
+export { SPEED_RAMP_EASES, speedRampDuration } from './timeline/speed-ramp.mjs';
+export { timelineFromEdl } from './timeline/from-edl.mjs';
+export { renderTimeline, renderTimelineAsync, renderTimelineRange, renderTimelineRangeAsync } from './timeline/render.mjs';
+export { DEFAULT_SOURCE_FIT, SOURCE_FIT_MODES, resolveSourceFit, validateSourceFit } from './timeline/source-fit.mjs';
+export { addTimelineClip, addTimelineTrack, crossfadeTimelineClips, detachAudioFromTimelineClip, duplicateTimelineClip, editTimeline, editTimelineBatch, extractTimelineRange, insertTimelineGap, moveTimelineClip, moveTimelineClipToTrack, previewTimelineEdit, removeTimelineClip, removeTimelineMarker, removeTimelineTrack, reorderTimelineTrack, replaceTimelineClipAsset, rippleDeleteTimelineClip, rippleDeleteTimelineRange, setTimelineAudioMastering, setTimelineAudioMix, setTimelineClipAudioEffects, setTimelineClipAudioState, setTimelineClipState, setTimelineClipVideoState, setTimelineClipFraming, setTimelineClipKeyframes, setTimelineClipReverse, setTimelineClipSpeed, setTimelineClipVolumeKeyframes, setTimelineMarker, setTimelineOverlay, setTimelineProjectState, setTimelineTrackAudioEffects, setTimelineTrackState, setTimelineTransition, slipTimelineClip, splitTimelineClip, trimTimelineClip } from './timeline/edit.mjs';
+export { createTimelineHistory } from './timeline/history.mjs';
+export { applyTimelineReviewPlan, editTimelineFile, undoTimelineFile, redoTimelineFile, getTimelineFileHistory, resetTimelineFileHistory } from './timeline/history-store.mjs';
+export { timelineFingerprint } from './timeline/fingerprint.mjs';
+export { createProjectTimeline } from './timeline/project.mjs';
+export { createCaptionTrack } from './timeline/captions.mjs';
+export { CAPTION_LAYOUT_PRESETS, listCaptionLayoutPresets, resolveCaptionLayoutPreset } from './timeline/caption-layouts.mjs';
+export { assembleEditedTimeline, renderEditedProject, renderEditedProjectAsync } from './timeline/assemble.mjs';
+export { normalizeTranscript } from './transcript/normalize.mjs';
+export { formatSubtitleText, parseSubtitleText } from './transcript/subtitles.mjs';
+export { transcribeWithProvider } from './transcript/provider.mjs';
+export { approveEdl, assertEdlApproved, retimeTranscript, validateEdl } from './edits/retime-transcript.mjs';
+export { mediaAnalysisToEdl } from './edits/analysis-to-edl.mjs';
+export { planSilenceCuts } from './edits/plan-silence-cuts.mjs';
+export { detectAcousticSilence, parseSilenceIntervals } from './edits/detect-silence.mjs';
+export { findMistakeCandidates } from './edits/find-mistake-candidates.mjs';
+export { planSceneReviewPlacements } from './edits/plan-shot-placements.mjs';
+export { applyTranscriptCorrections } from './transcript/corrections.mjs';
+export { parseProbeOutput, probeMedia, probeMediaAsync } from './media/probe.mjs';
+export { inspectMediaCompatibility } from './media/compatibility.mjs';
+export { analyzeMediaWithProvider, normalizeMediaFindings } from './media/analysis-provider.mjs';
+export { detectSceneChangesAsync, parseSceneDetectionOutput } from './media/scene-detection.mjs';
+export { buildShotRanges, createSceneReviewPackAsync } from './media/scene-review.mjs';
+export { generateAssetPreview } from './media/preview-assets.mjs';
+export { normalizeFrameRate, frameRateNumber } from './media/frame-rate.mjs';
+export { assertFfmpegDecoder, assertFfmpegDemuxer, assertFfmpegEncoder, hasFfmpegDecoder, hasFfmpegDemuxer, hasFfmpegEncoder, hasFfmpegFilter, listFfmpegDecoders, listFfmpegDemuxers, listFfmpegEncoders, listFfmpegFilters, parseFfmpegDecoders, parseFfmpegDemuxers, parseFfmpegEncoders, parseFfmpegFilters } from './media/ffmpeg-capabilities.mjs';
+export { secondsToFrame, frameToSeconds, snapTimeToFrame } from './media/frame-time.mjs';
+export { createFilterGraph, getKeepRanges, renderCuts } from './media/render-cuts.mjs';
+export { createVideoProject } from './project/create.mjs';
+export { createAssetProxy, createAssetProxyAsync, listProjectAssets, registerMediaAsset, registerMediaAssetAsync, registerMediaAssetsAsync, relinkProjectAsset, relinkProjectAssetAsync, resolveAssetProxies, resolveAssetProxiesAsync, unregisterProjectAsset, verifyProjectAssets, verifyProjectAssetsAsync } from './project/assets.mjs';
+export { CANVAS_PRESETS, listCanvasPresets, resolveCanvasPreset } from './project/presets.mjs';
+export { doctorHyperframes, importProjectTranscript, lintProject, previewProject, renderProject, renderProjectAsync, transcribeProject } from './render/hyperframes.mjs';
+export { resolveColorProfile, resolveEncoderArgs, resolveProfileEncoder, resolveRenderControlArgs, resolveRenderFormat, resolveVideoEncoder } from './render/formats.mjs';
+export { exportTimelineToOtio, importTimelineFromOtio, isOtioPath } from './interchange/otio.mjs';