aivee 0.0.0-stage → 0.1.0-dev.7025438

package/src/render/process.mjs

@@ -0,0 +1,111 @@
+import { spawn } from 'node:child_process';
+
+export function runProcess(command, args, { cwd, signal, stdio = 'inherit', windowsHide = true, onStdout, onStderr } = {}) {
+  if (signal?.aborted) return Promise.reject(abortReason(signal));
+  return new Promise((resolve, reject) => {
+    const capture = stdio === 'capture';
+    const child = spawn(command, args, {
+      cwd,
+      stdio: capture ? ['ignore', 'pipe', 'pipe'] : stdio,
+      windowsHide,
+      detached: process.platform !== 'win32',
+    });
+    let settled = false;
+    let killPromise;
+    let forceTimer;
+    const outputLimit = 16 * 1024 * 1024;
+    const output = { stdout: [], stderr: [], stdoutBytes: 0, stderrBytes: 0 };
+    const captureOutput = (stream, key, byteKey, onChunk) => {
+      stream?.on('data', (chunk) => {
+        onChunk?.(chunk);
+        if (output[byteKey] >= outputLimit) return;
+        const retained = chunk.subarray(0, outputLimit - output[byteKey]);
+        output[key].push(retained);
+        output[byteKey] += retained.length;
+      });
+    };
+    if (capture) {
+      captureOutput(child.stdout, 'stdout', 'stdoutBytes', onStdout);
+      captureOutput(child.stderr, 'stderr', 'stderrBytes', onStderr);
+    }
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      if (forceTimer) clearTimeout(forceTimer);
+      signal?.removeEventListener('abort', abort);
+      callback(value);
+    };
+    const abort = () => {
+      if (killPromise) return;
+      killPromise = terminateProcessTree(child, (timer) => { forceTimer = timer; });
+    };
+    signal?.addEventListener('abort', abort, { once: true });
+    child.once('error', (error) => {
+      finish(reject, signal?.aborted ? abortReason(signal) : error);
+    });
+    child.once('close', async (code, signalName) => {
+      if (killPromise) await killPromise;
+      if (signal?.aborted) {
+        finish(reject, abortReason(signal));
+      } else if (code === 0) {
+        finish(resolve, capture ? { stdout: Buffer.concat(output.stdout).toString('utf8'), stderr: Buffer.concat(output.stderr).toString('utf8') } : true);
+      } else {
+        const stderr = capture ? Buffer.concat(output.stderr).toString('utf8').trim() : '';
+        finish(reject, new Error(`${command} exited with ${signalName ? `signal ${signalName}` : `code ${code}`}.${stderr ? ` ${stderr}` : ''}`));
+      }
+    });
+    if (signal?.aborted) abort();
+  });
+}
+
+function terminateProcessTree(child, setForceTimer) {
+  if (!child.pid) {
+    child.kill('SIGTERM');
+    return Promise.resolve();
+  }
+  if (process.platform === 'win32') {
+    return new Promise((resolve) => {
+      const killer = spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], {
+        stdio: 'ignore',
+        windowsHide: true,
+      });
+      let settled = false;
+      const fallbackTimer = setTimeout(() => {
+        if (child.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
+      }, 2000);
+      setForceTimer(fallbackTimer);
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+      killer.once('error', () => {
+        child.kill('SIGTERM');
+        finish();
+      });
+      killer.once('close', (code) => {
+        if (code !== 0 && child.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
+        finish();
+      });
+    });
+  }
+
+  try {
+    process.kill(-child.pid, 'SIGTERM');
+  } catch {
+    child.kill('SIGTERM');
+  }
+  const forceTimer = setTimeout(() => {
+    try { process.kill(-child.pid, 'SIGKILL'); } catch { /* process tree already exited */ }
+  }, 1500);
+  forceTimer.unref();
+  setForceTimer(forceTimer);
+  return Promise.resolve();
+}
+
+function abortReason(signal) {
+  if (signal.reason instanceof Error) return signal.reason;
+  const error = new Error('Render cancelled.');
+  error.name = 'AbortError';
+  return error;
+}

package/src/render/progress.mjs

@@ -0,0 +1,46 @@
+export function emitRenderProgress(onProgress, stage, phase, details = {}) {
+  if (!onProgress) return;
+  try {
+    const percent = phase === 'completed' ? 100 : phase === 'started' ? 0 : undefined;
+    const result = onProgress({ stage, phase, ...(percent !== undefined ? { percent } : {}), ...details });
+    if (result && typeof result.then === 'function') Promise.resolve(result).catch(warnProgressCallback);
+  } catch (error) {
+    warnProgressCallback(error);
+  }
+}
+
+export function createFfmpegProgressParser(onProgress, stage, durationSeconds, details = {}) {
+  let pending = '';
+  let currentTimeUs;
+  const parseLine = (line) => {
+    const separator = line.indexOf('=');
+    if (separator < 0) return;
+    const key = line.slice(0, separator);
+    const value = line.slice(separator + 1);
+    if (key === 'out_time_us') currentTimeUs = Number(value);
+    if (key !== 'progress' || !Number.isFinite(currentTimeUs)) return;
+    const completed = Math.max(0, currentTimeUs / 1_000_000);
+    const percent = Math.max(0, Math.min(99, completed / durationSeconds * 100));
+    emitRenderProgress(onProgress, stage, 'progress', { percent, completed, total: durationSeconds, ...details });
+  };
+  return {
+    push(chunk) {
+      pending += chunk.toString('utf8');
+      let newline;
+      while ((newline = pending.indexOf('\n')) >= 0) {
+        parseLine(pending.slice(0, newline).replace(/\r$/, ''));
+        pending = pending.slice(newline + 1);
+      }
+      if (pending.length > 4096) pending = pending.slice(-4096);
+    },
+    flush() {
+      if (pending) parseLine(pending);
+      pending = '';
+    },
+  };
+}
+
+function warnProgressCallback(error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  process.emitWarning(`Progress callback failed: ${detail}`);
+}

package/src/render/timeline-control.mjs

@@ -0,0 +1,53 @@
+export function createTimelineRenderControl(signal, timeoutSeconds) {
+  if (signal !== undefined && (typeof signal.aborted !== 'boolean' || typeof signal.addEventListener !== 'function')) {
+    throw new TypeError('Render signal must be an AbortSignal.');
+  }
+  if (timeoutSeconds !== undefined
+      && (!Number.isSafeInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 86_400)) {
+    throw new TypeError('Render timeoutSeconds must be an integer from 1 to 86400.');
+  }
+
+  const controller = new AbortController();
+  const deadline = timeoutSeconds === undefined ? undefined : Date.now() + timeoutSeconds * 1000;
+  const timeoutError = () => {
+    const error = new Error(`Render exceeded the configured timeout of ${timeoutSeconds} seconds.`);
+    error.name = 'TimeoutError';
+    return error;
+  };
+  const relayAbort = () => controller.abort(signal.reason ?? new DOMException('Render was aborted.', 'AbortError'));
+  if (signal?.aborted) relayAbort();
+  else signal?.addEventListener('abort', relayAbort, { once: true });
+  const timer = deadline === undefined ? undefined : setTimeout(() => controller.abort(timeoutError()), timeoutSeconds * 1000);
+  timer?.unref();
+
+  return {
+    signal: controller.signal,
+    assertActive() {
+      if (signal?.aborted && !controller.signal.aborted) relayAbort();
+      if (deadline !== undefined && Date.now() >= deadline) controller.abort(timeoutError());
+      if (controller.signal.aborted) throw controller.signal.reason ?? new DOMException('Render was aborted.', 'AbortError');
+    },
+    timeoutMs() {
+      if (deadline === undefined) return undefined;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) {
+        controller.abort(timeoutError());
+        this.assertActive();
+      }
+      return Math.max(1, Math.ceil(remaining));
+    },
+    processError(error) {
+      if (signal?.aborted && !controller.signal.aborted) relayAbort();
+      if (controller.signal.aborted) return controller.signal.reason;
+      if (error?.code === 'ETIMEDOUT' || (deadline !== undefined && Date.now() >= deadline)) {
+        controller.abort(timeoutError());
+        return controller.signal.reason;
+      }
+      return error;
+    },
+    dispose() {
+      if (timer) clearTimeout(timer);
+      signal?.removeEventListener('abort', relayAbort);
+    },
+  };
+}

package/src/timeline/assemble.mjs

@@ -0,0 +1,119 @@
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { retimeTranscript, validateEdl } from '../edits/retime-transcript.mjs';
+import { createCaptionTrack } from './captions.mjs';
+import { timelineFromEdl } from './from-edl.mjs';
+import { renderTimeline, renderTimelineAsync } from './render.mjs';
+import { validateTimeline } from './validate.mjs';
+
+export function assembleEditedTimeline(projectPath, assetId, transcript, edl, options = {}) {
+  const root = resolve(projectPath);
+  const meta = readProjectMeta(root);
+  const manifest = JSON.parse(readFileSync(join(root, 'assets', 'manifest.json'), 'utf8'));
+  const asset = manifest.assets.find((entry) => entry.id === assetId);
+  if (!asset) throw new TypeError(`Asset is not registered in this project: ${assetId}`);
+  if (asset.type !== 'video') throw new TypeError('Transcript-driven editing requires a registered video asset.');
+  validateEdl(edl, asset.durationSeconds);
+  if (Math.abs(transcript.durationSeconds - asset.durationSeconds) > 1e-6) throw new TypeError('Transcript duration must match the registered source media.');
+
+  const retimedTranscript = retimeTranscript(transcript, edl);
+  const timeline = timelineFromEdl(edl, assetId, {
+    id: meta.id,
+    width: meta.width,
+    height: meta.height,
+    fps: meta.fps,
+    sourceFit: meta.sourceFit,
+    backgroundColor: meta.backgroundColor,
+    assetPath: asset.path,
+    assetType: asset.type,
+    assetHasAudio: asset.hasAudio,
+    assetAudioStreams: asset.audioStreams,
+    assetDurationSeconds: asset.durationSeconds,
+    assetStreamTiming: asset.streamTiming,
+    includeAudioTrack: asset.hasAudio,
+  });
+  if (Math.abs(retimedTranscript.durationSeconds - timeline.project.durationSeconds) > 1e-6) throw new Error('Retimed transcript and edit timeline durations do not match.');
+  const captionOptions = { ...options.captionOptions, order: timeline.tracks.length };
+  if (captionOptions.fontSize === undefined) captionOptions.fontSize = Math.max(8, Math.round(54 * Math.min(meta.width, meta.height) / 1080));
+  const captions = createCaptionTrack(retimedTranscript, captionOptions);
+  timeline.tracks.push(captions);
+  timeline.lineage = {
+    assetId,
+    sourceSha256: asset.sha256,
+    approvedEdl: 'edits/approved-edl.json',
+    retimedTranscript: 'transcripts/retimed-transcript.json',
+  };
+  validateTimeline(timeline);
+  return { timeline, retimedTranscript, asset };
+}
+
+export function renderEditedProject(projectPath, assetId, transcript, edl, options = {}) {
+  if (options.signal !== undefined || options.timeoutSeconds !== undefined || options.onProgress !== undefined) {
+    throw new TypeError('Cancellation, timeouts, and progress callbacks require renderEditedProjectAsync.');
+  }
+  return renderEditedProjectWith(projectPath, assetId, transcript, edl, options, renderTimeline);
+}
+
+export function renderEditedProjectAsync(projectPath, assetId, transcript, edl, options = {}) {
+  return renderEditedProjectWith(projectPath, assetId, transcript, edl, options, renderTimelineAsync);
+}
+
+function renderEditedProjectWith(projectPath, assetId, transcript, edl, options, renderTimelineFunction) {
+  const root = resolve(projectPath);
+  const metaPath = join(root, 'meta.json');
+  const indexPath = join(root, 'index.html');
+  const timelinePath = join(root, 'timeline.json');
+  const approvedEdlPath = join(root, 'edits', 'approved-edl.json');
+  const retimedTranscriptPath = join(root, 'transcripts', 'retimed-transcript.json');
+  const outputPath = resolve(options.outputPath ?? join(root, 'renders', 'final.mp4'));
+  for (const path of [timelinePath, approvedEdlPath, retimedTranscriptPath, outputPath]) {
+    if (existsSync(path)) throw new Error(`End-to-end edit would overwrite existing project data: ${path}`);
+  }
+
+  const { timeline, retimedTranscript } = assembleEditedTimeline(root, assetId, transcript, edl, options);
+  const originalMeta = readFileSync(metaPath, 'utf8');
+  const originalHtml = readFileSync(indexPath);
+  const nextMeta = { ...JSON.parse(originalMeta), durationSeconds: timeline.project.durationSeconds };
+  const renderOptions = Object.fromEntries(
+    ['format', 'encoder', 'colorProfile', 'workers', 'lowMemoryMode', 'timeoutSeconds', 'signal', 'onProgress']
+      .filter((field) => options[field] !== undefined)
+      .map((field) => [field, options[field]]),
+  );
+  let wroteEdl = false;
+  let wroteTranscript = false;
+  try {
+    writeFileSync(metaPath, `${JSON.stringify(nextMeta, null, 2)}\n`);
+    writeFileSync(approvedEdlPath, `${JSON.stringify(edl, null, 2)}\n`, { flag: 'wx' });
+    wroteEdl = true;
+    writeFileSync(retimedTranscriptPath, `${JSON.stringify(retimedTranscript, null, 2)}\n`, { flag: 'wx' });
+    wroteTranscript = true;
+    const render = renderTimelineFunction(root, timeline, outputPath, options.quality ?? 'draft', renderOptions);
+    if (render && typeof render.then === 'function') {
+      return render.then((result) => ({ ...result, assetId, timelinePath, approvedEdlPath, retimedTranscriptPath }))
+        .catch((error) => {
+          restoreEditedProject({ metaPath, originalMeta, indexPath, originalHtml, approvedEdlPath, retimedTranscriptPath, timelinePath, wroteEdl, wroteTranscript });
+          throw error;
+        });
+    }
+    return { ...render, assetId, timelinePath, approvedEdlPath, retimedTranscriptPath };
+  } catch (error) {
+    restoreEditedProject({ metaPath, originalMeta, indexPath, originalHtml, approvedEdlPath, retimedTranscriptPath, timelinePath, wroteEdl, wroteTranscript });
+    throw error;
+  }
+}
+
+function restoreEditedProject({ metaPath, originalMeta, indexPath, originalHtml, approvedEdlPath, retimedTranscriptPath, timelinePath, wroteEdl, wroteTranscript }) {
+  writeFileSync(metaPath, originalMeta);
+  writeFileSync(indexPath, originalHtml);
+  if (wroteEdl) unlinkSync(approvedEdlPath);
+  if (wroteTranscript) unlinkSync(retimedTranscriptPath);
+  if (existsSync(timelinePath)) {
+    try { unlinkSync(timelinePath); } catch {}
+  }
+}
+
+function readProjectMeta(root) {
+  const path = join(root, 'meta.json');
+  if (!existsSync(path)) throw new Error(`Not an Engine project: ${root}`);
+  return JSON.parse(readFileSync(path, 'utf8'));
+}

package/src/timeline/audio-effects.mjs

@@ -0,0 +1,75 @@
+const EFFECT_TYPES = new Set(['equalizer', 'highpass', 'lowpass', 'compressor', 'denoise', 'balance']);
+
+export function validateAudioClipEffects(effects, clipId) {
+  if (effects === undefined) return;
+  if (!Array.isArray(effects) || effects.length > 16) {
+    throw new TypeError(`Clip ${clipId} audioEffects must be an array with at most 16 effects.`);
+  }
+  for (const [index, effect] of effects.entries()) {
+    if (!effect || typeof effect !== 'object' || Array.isArray(effect) || !EFFECT_TYPES.has(effect.type)) {
+      throw new TypeError(`Clip ${clipId} audio effect ${index + 1} has an unsupported type.`);
+    }
+    const fields = {
+      equalizer: ['type', 'frequencyHz', 'gainDB', 'q'],
+      highpass: ['type', 'frequencyHz', 'order'],
+      lowpass: ['type', 'frequencyHz', 'order'],
+      compressor: ['type', 'thresholdDB', 'ratio', 'attackMs', 'releaseMs', 'makeupDB'],
+      denoise: ['type', 'reductionDB'],
+      balance: ['type', 'value'],
+    }[effect.type];
+    if (Object.keys(effect).some((field) => !fields.includes(field))) {
+      throw new TypeError(`Clip ${clipId} audio effect ${index + 1} has unsupported settings.`);
+    }
+    if (effect.type === 'equalizer') {
+      requireRange(effect.frequencyHz, 20, 20000, `Clip ${clipId} equalizer frequencyHz`);
+      requireRange(effect.gainDB, -18, 18, `Clip ${clipId} equalizer gainDB`);
+      if (effect.q !== undefined) requireRange(effect.q, 0.1, 10, `Clip ${clipId} equalizer q`);
+    } else if (effect.type === 'highpass' || effect.type === 'lowpass') {
+      requireRange(effect.frequencyHz, 20, 20000, `Clip ${clipId} ${effect.type} frequencyHz`);
+      if (effect.order !== undefined && (!Number.isSafeInteger(effect.order) || effect.order < 1 || effect.order > 2)) {
+        throw new TypeError(`Clip ${clipId} ${effect.type} order must be 1 or 2.`);
+      }
+    } else if (effect.type === 'compressor') {
+      requireRange(effect.thresholdDB, -60, 0, `Clip ${clipId} compressor thresholdDB`);
+      requireRange(effect.ratio, 1, 20, `Clip ${clipId} compressor ratio`);
+      requireRange(effect.attackMs ?? 20, 0.01, 200, `Clip ${clipId} compressor attackMs`);
+      requireRange(effect.releaseMs ?? 250, 1, 2000, `Clip ${clipId} compressor releaseMs`);
+      requireRange(effect.makeupDB ?? 0, 0, 24, `Clip ${clipId} compressor makeupDB`);
+    } else if (effect.type === 'denoise') {
+      requireRange(effect.reductionDB, 0.01, 30, `Clip ${clipId} denoise reductionDB`);
+    } else {
+      requireRange(effect.value, -1, 1, `Clip ${clipId} stereo balance`);
+    }
+  }
+}
+
+export function buildAudioClipEffectFilters(effects = []) {
+  return effects.map((effect) => {
+    if (effect.type === 'equalizer') return `equalizer=f=${effect.frequencyHz}:t=q:w=${effect.q ?? 1}:g=${effect.gainDB}`;
+    if (effect.type === 'highpass' || effect.type === 'lowpass') return `${effect.type}=f=${effect.frequencyHz}:p=${effect.order ?? 2}`;
+    if (effect.type === 'compressor') {
+      return `acompressor=threshold=${10 ** ((effect.thresholdDB ?? -18) / 20)}:ratio=${effect.ratio}:attack=${effect.attackMs ?? 20}:release=${effect.releaseMs ?? 250}:makeup=${10 ** ((effect.makeupDB ?? 0) / 20)}:detection=rms`;
+    }
+    if (effect.type === 'denoise') return `afftdn=nr=${effect.reductionDB}`;
+    return `stereotools=balance_in=${effect.value}`;
+  });
+}
+
+export function audioClipEffectRequirements(effects = []) {
+  const requirements = new Set();
+  for (const effect of effects) {
+    if (effect.type === 'equalizer') requirements.add('equalizer');
+    if (effect.type === 'highpass') requirements.add('highpass');
+    if (effect.type === 'lowpass') requirements.add('lowpass');
+    if (effect.type === 'compressor') requirements.add('acompressor');
+    if (effect.type === 'denoise') requirements.add('afftdn');
+    if (effect.type === 'balance') requirements.add('stereotools');
+  }
+  return [...requirements];
+}
+
+function requireRange(value, minimum, maximum, label) {
+  if (!Number.isFinite(value) || value < minimum || value > maximum) {
+    throw new TypeError(`${label} must be from ${minimum} to ${maximum}.`);
+  }
+}

package/src/timeline/audio-mastering.mjs

@@ -0,0 +1,236 @@
+import { randomUUID } from 'node:crypto';
+import { existsSync, renameSync, rmSync, unlinkSync } from 'node:fs';
+import { basename, dirname, extname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { probeMedia, probeMediaAsync } from '../media/probe.mjs';
+import { frameRateNumber } from '../media/frame-rate.mjs';
+import { runProcess } from '../render/process.mjs';
+import { createFfmpegProgressParser, emitRenderProgress } from '../render/progress.mjs';
+
+const DEFAULTS = Object.freeze({
+  integratedLoudnessLUFS: -16,
+  truePeakDBTP: -1.5,
+  loudnessRangeLU: 11,
+});
+const EQ_FIELDS = new Set(['frequencyHz', 'gainDB', 'q']);
+
+export function validateAudioMastering(timeline) {
+  const settings = timeline.audioMastering;
+  if (settings === undefined) return undefined;
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new TypeError('Timeline audioMastering must be an object.');
+  const allowed = new Set([...Object.keys(DEFAULTS), 'equalizer', 'limiter', 'channelLayout']);
+  for (const field of Object.keys(settings)) if (!allowed.has(field)) throw new TypeError(`Timeline audioMastering has an unsupported setting: ${field}.`);
+  validateEqualizer(settings.equalizer);
+  validateLimiter(settings.limiter);
+  if (settings.channelLayout !== undefined && !['mono', 'stereo'].includes(settings.channelLayout)) {
+    throw new TypeError('Timeline audioMastering.channelLayout must be mono or stereo.');
+  }
+  const values = { ...DEFAULTS, ...settings };
+  if (!Number.isFinite(values.integratedLoudnessLUFS) || values.integratedLoudnessLUFS < -70 || values.integratedLoudnessLUFS > -5) {
+    throw new TypeError('Timeline audioMastering.integratedLoudnessLUFS must be between -70 and -5 LUFS.');
+  }
+  if (!Number.isFinite(values.truePeakDBTP) || values.truePeakDBTP < -9 || values.truePeakDBTP > 0) {
+    throw new TypeError('Timeline audioMastering.truePeakDBTP must be between -9 and 0 dBTP.');
+  }
+  if (!Number.isFinite(values.loudnessRangeLU) || values.loudnessRangeLU < 1 || values.loudnessRangeLU > 50) {
+    throw new TypeError('Timeline audioMastering.loudnessRangeLU must be between 1 and 50 LU.');
+  }
+  if (!timeline.tracks.some((track) => track.kind === 'audio' && track.clips.length > 0)) {
+    throw new TypeError('Timeline audioMastering requires at least one audio clip.');
+  }
+  return values;
+}
+
+export function masterAudioFile(outputPath, format, settings, fps) {
+  const input = probeMedia(outputPath);
+  if (!input.hasAudio) throw new Error('Cannot master loudness because the rendered output has no audio stream.');
+  const targetDuration = input.streamTiming.videoDurationSeconds ?? input.durationSeconds;
+  const baseFilter = `loudnorm=I=${settings.integratedLoudnessLUFS}:TP=${settings.truePeakDBTP}:LRA=${settings.loudnessRangeLU}`;
+  const channelFilter = settings.channelLayout ? [`aresample=ochl=${settings.channelLayout}`] : [];
+  const equalizerFilters = buildEqualizerFilters(settings.equalizer);
+  const preLoudnessFilters = [...channelFilter, ...equalizerFilters];
+  const preLoudnessPrefix = preLoudnessFilters.length ? `${preLoudnessFilters.join(',')},` : '';
+  const analysis = spawnSync('ffmpeg', [
+    '-nostdin', '-hide_banner', '-v', 'info', '-i', outputPath,
+    '-map', '0:a:0', '-af', `${preLoudnessPrefix}${baseFilter}:print_format=json`, '-f', 'null', nullDevice(),
+  ], { encoding: 'utf8', windowsHide: true, maxBuffer: 4 * 1024 * 1024 });
+  if (analysis.error || analysis.status !== 0) throw new Error(`Could not analyze rendered audio loudness: ${analysis.error?.message ?? analysis.stderr.trim()}`);
+  const loudness = parseLoudnessAnalysis(analysis.stderr);
+  const loudnessFilter = loudness.measured
+    ? `${baseFilter}:measured_I=${loudness.measured.input_i}:measured_TP=${loudness.measured.input_tp}:measured_LRA=${loudness.measured.input_lra}:measured_thresh=${loudness.measured.input_thresh}:offset=${loudness.measured.target_offset}:linear=true:print_format=summary`
+    : loudness.silent ? undefined : `${baseFilter}:print_format=summary`;
+  const limiterFilter = settings.limiter ? buildLimiterFilter(settings.limiter) : undefined;
+  const filter = buildMasteringFilter(preLoudnessFilters, loudnessFilter, limiterFilter, targetDuration);
+  const extension = extname(outputPath);
+  const temporaryPath = join(dirname(outputPath), `.${basename(outputPath, extension)}.${randomUUID()}.master${extension}`);
+  try {
+    const audioCodec = format === 'webm' ? ['-c:a', 'libopus', '-b:a', '192k'] : ['-c:a', 'aac', '-b:a', '256k'];
+    const encode = spawnSync('ffmpeg', [
+      '-nostdin', '-hide_banner', '-v', 'error', '-y', '-i', outputPath,
+      '-map', '0:v:0', '-map', '0:a:0', '-c:v', 'copy', ...audioCodec,
+      ...(filter ? ['-af', filter] : []), '-ar', '48000',
+      ...(settings.channelLayout ? ['-ac', settings.channelLayout === 'mono' ? '1' : '2', '-channel_layout', settings.channelLayout] : []),
+      ...(format === 'mp4' || format === 'mov' ? ['-movflags', '+faststart'] : []),
+      temporaryPath,
+    ], { encoding: 'utf8', windowsHide: true, maxBuffer: 4 * 1024 * 1024 });
+    if (encode.error || encode.status !== 0) throw new Error(`Could not apply rendered audio mastering: ${encode.error?.message ?? encode.stderr.trim()}`);
+    const mastered = probeMedia(temporaryPath);
+    validateMasteredOutput(mastered, input, settings, targetDuration, fps);
+    unlinkSync(outputPath);
+    renameSync(temporaryPath, outputPath);
+    return {
+      ...mastered,
+      loudnessMode: loudness.measured ? 'two-pass-linear' : loudness.silent ? 'silent-bypass' : 'single-pass-dynamic',
+    };
+  } catch (error) {
+    if (existsSync(temporaryPath)) rmSync(temporaryPath, { force: true });
+    throw error;
+  }
+}
+
+export async function masterAudioFileAsync(outputPath, format, settings, fps, signal, onProgress) {
+  const input = await probeMediaAsync(outputPath, { signal });
+  if (!input.hasAudio) throw new Error('Cannot master loudness because the rendered output has no audio stream.');
+  const targetDuration = input.streamTiming.videoDurationSeconds ?? input.durationSeconds;
+  const baseFilter = `loudnorm=I=${settings.integratedLoudnessLUFS}:TP=${settings.truePeakDBTP}:LRA=${settings.loudnessRangeLU}`;
+  const channelFilter = settings.channelLayout ? [`aresample=ochl=${settings.channelLayout}`] : [];
+  const equalizerFilters = buildEqualizerFilters(settings.equalizer);
+  const preLoudnessFilters = [...channelFilter, ...equalizerFilters];
+  const preLoudnessPrefix = preLoudnessFilters.length ? `${preLoudnessFilters.join(',')},` : '';
+  emitRenderProgress(onProgress, 'mastering-analysis', 'started');
+  const analysisProgress = onProgress ? createFfmpegProgressParser(onProgress, 'mastering-analysis', input.durationSeconds) : undefined;
+  const analysis = await runProcess('ffmpeg', [
+    '-nostdin', '-hide_banner', '-v', 'info', '-i', outputPath,
+    '-map', '0:a:0', '-af', `${preLoudnessPrefix}${baseFilter}:print_format=json`,
+    ...(onProgress ? ['-progress', 'pipe:1', '-nostats'] : []), '-f', 'null', nullDevice(),
+  ], { signal, stdio: 'capture', ...(analysisProgress ? { onStdout: analysisProgress.push } : {}) });
+  analysisProgress?.flush();
+  emitRenderProgress(onProgress, 'mastering-analysis', 'completed');
+  const loudness = parseLoudnessAnalysis(analysis.stderr);
+  const loudnessFilter = loudness.measured
+    ? `${baseFilter}:measured_I=${loudness.measured.input_i}:measured_TP=${loudness.measured.input_tp}:measured_LRA=${loudness.measured.input_lra}:measured_thresh=${loudness.measured.input_thresh}:offset=${loudness.measured.target_offset}:linear=true:print_format=summary`
+    : loudness.silent ? undefined : `${baseFilter}:print_format=summary`;
+  const limiterFilter = settings.limiter ? buildLimiterFilter(settings.limiter) : undefined;
+  const filter = buildMasteringFilter(preLoudnessFilters, loudnessFilter, limiterFilter, targetDuration);
+  const extension = extname(outputPath);
+  const temporaryPath = join(dirname(outputPath), `.${basename(outputPath, extension)}.${randomUUID()}.master${extension}`);
+  try {
+    const audioCodec = format === 'webm' ? ['-c:a', 'libopus', '-b:a', '192k'] : ['-c:a', 'aac', '-b:a', '256k'];
+    emitRenderProgress(onProgress, 'mastering-encode', 'started', { codec: audioCodec[1] });
+    const encodeProgress = onProgress ? createFfmpegProgressParser(onProgress, 'mastering-encode', input.durationSeconds, { codec: audioCodec[1] }) : undefined;
+    await runProcess('ffmpeg', [
+      '-nostdin', '-hide_banner', '-v', 'error', '-y', '-i', outputPath,
+      '-map', '0:v:0', '-map', '0:a:0', '-c:v', 'copy', ...audioCodec,
+      ...(filter ? ['-af', filter] : []), '-ar', '48000',
+      ...(settings.channelLayout ? ['-ac', settings.channelLayout === 'mono' ? '1' : '2', '-channel_layout', settings.channelLayout] : []),
+      ...(onProgress ? ['-progress', 'pipe:1', '-nostats'] : []),
+      ...(format === 'mp4' || format === 'mov' ? ['-movflags', '+faststart'] : []),
+      temporaryPath,
+    ], { signal, ...(encodeProgress ? {
+      stdio: 'capture',
+      onStdout: encodeProgress.push,
+      onStderr: (chunk) => process.stderr.write(chunk),
+    } : {}) });
+    encodeProgress?.flush();
+    emitRenderProgress(onProgress, 'mastering-encode', 'completed', { codec: audioCodec[1] });
+    emitRenderProgress(onProgress, 'mastering-validation', 'started');
+    const mastered = await probeMediaAsync(temporaryPath, { signal });
+    validateMasteredOutput(mastered, input, settings, targetDuration, fps);
+    emitRenderProgress(onProgress, 'mastering-validation', 'completed');
+    emitRenderProgress(onProgress, 'mastering-publish', 'started');
+    unlinkSync(outputPath);
+    renameSync(temporaryPath, outputPath);
+    emitRenderProgress(onProgress, 'mastering-publish', 'completed');
+    return {
+      ...mastered,
+      loudnessMode: loudness.measured ? 'two-pass-linear' : loudness.silent ? 'silent-bypass' : 'single-pass-dynamic',
+    };
+  } catch (error) {
+    if (existsSync(temporaryPath)) rmSync(temporaryPath, { force: true });
+    throw error;
+  }
+}
+
+function validateEqualizer(equalizer) {
+  if (equalizer === undefined) return;
+  if (!Array.isArray(equalizer) || equalizer.length > 10) throw new TypeError('Timeline audioMastering.equalizer must be an array with at most 10 bands.');
+  for (const [index, band] of equalizer.entries()) {
+    if (!band || typeof band !== 'object' || Array.isArray(band) || Object.keys(band).some((field) => !EQ_FIELDS.has(field))) {
+      throw new TypeError(`Timeline audioMastering.equalizer band ${index} has an invalid shape.`);
+    }
+    if (!Number.isFinite(band.frequencyHz) || band.frequencyHz < 20 || band.frequencyHz > 20000) {
+      throw new TypeError(`Timeline audioMastering.equalizer band ${index} frequencyHz must be from 20 to 20000.`);
+    }
+    if (!Number.isFinite(band.gainDB) || band.gainDB < -18 || band.gainDB > 18) {
+      throw new TypeError(`Timeline audioMastering.equalizer band ${index} gainDB must be from -18 to 18.`);
+    }
+    if (band.q !== undefined && (!Number.isFinite(band.q) || band.q < 0.1 || band.q > 10)) {
+      throw new TypeError(`Timeline audioMastering.equalizer band ${index} q must be from 0.1 to 10.`);
+    }
+  }
+}
+
+function validateLimiter(limiter) {
+  if (limiter === undefined) return;
+  const fields = ['limitDBFS', 'attackMs', 'releaseMs'];
+  if (!limiter || typeof limiter !== 'object' || Array.isArray(limiter) || Object.keys(limiter).some((field) => !fields.includes(field))) {
+    throw new TypeError('Timeline audioMastering.limiter has an invalid shape.');
+  }
+  if (!Number.isFinite(limiter.limitDBFS) || limiter.limitDBFS < -20 || limiter.limitDBFS > 0) {
+    throw new TypeError('Timeline audioMastering.limiter.limitDBFS must be from -20 to 0.');
+  }
+  if (!Number.isFinite(limiter.attackMs) || limiter.attackMs < 0.1 || limiter.attackMs > 80) {
+    throw new TypeError('Timeline audioMastering.limiter.attackMs must be from 0.1 to 80.');
+  }
+  if (!Number.isFinite(limiter.releaseMs) || limiter.releaseMs < 10 || limiter.releaseMs > 1000) {
+    throw new TypeError('Timeline audioMastering.limiter.releaseMs must be from 10 to 1000.');
+  }
+}
+
+function buildEqualizerFilters(equalizer = []) {
+  return equalizer.map(({ frequencyHz, gainDB, q = 1 }) => `equalizer=f=${frequencyHz}:t=q:w=${q}:g=${gainDB}`);
+}
+
+function buildLimiterFilter({ limitDBFS, attackMs, releaseMs }) {
+  const linearLimit = 10 ** (limitDBFS / 20);
+  return `alimiter=limit=${linearLimit}:attack=${attackMs}:release=${releaseMs}:level=0`;
+}
+
+function buildMasteringFilter(preLoudnessFilters, loudnessFilter, limiterFilter, targetDuration) {
+  const duration = Number(targetDuration.toFixed(9));
+  return [...preLoudnessFilters, loudnessFilter, limiterFilter, `apad=whole_dur=${duration}`, `atrim=duration=${duration}`]
+    .filter(Boolean)
+    .join(',');
+}
+
+function validateMasteredOutput(mastered, input, settings, targetDuration, fps) {
+  const expectedChannels = settings.channelLayout === 'mono' ? 1 : settings.channelLayout === 'stereo' ? 2 : undefined;
+  const frameTolerance = 1 / frameRateNumber(fps);
+  const videoDuration = mastered.streamTiming.videoDurationSeconds ?? mastered.durationSeconds;
+  const audioDuration = mastered.streamTiming.audioDurationSeconds ?? mastered.durationSeconds;
+  if (!mastered.hasAudio || mastered.width !== input.width || mastered.height !== input.height
+      || (expectedChannels !== undefined && mastered.audioChannels !== expectedChannels)
+      || Math.abs(videoDuration - targetDuration) > frameTolerance
+      || Math.abs(audioDuration - videoDuration) > frameTolerance) {
+    throw new Error('Mastered output failed audio/video stream or channel-layout validation.');
+  }
+}
+
+function parseLoudnessAnalysis(stderr) {
+  const blocks = [...stderr.matchAll(/\{\s*"input_i"[\s\S]*?\}/g)];
+  if (blocks.length === 0) return { silent: false };
+  let values;
+  try {
+    values = JSON.parse(blocks.at(-1)[0]);
+  } catch {
+    return { silent: false };
+  }
+  if (values.input_i === '-inf' && values.input_tp === '-inf') return { silent: true };
+  const required = ['input_i', 'input_tp', 'input_lra', 'input_thresh', 'target_offset'];
+  if (!required.every((field) => Number.isFinite(Number(values[field])))) return { silent: false };
+  return { measured: Object.fromEntries(required.map((field) => [field, Number(values[field])])) };
+}
+
+function nullDevice() {
+  return process.platform === 'win32' ? 'NUL' : '/dev/null';
+}