multiplane 0.3.6 → 0.3.8

package/src/capture.mjs

@@ -119,10 +119,10 @@ async function openShotOnce(shot, scale = 1, options = {}) {
     }
     if (alpha && cdp) await cdp.send('Emulation.setDefaultBackgroundColorOverride', { color: { r: 0, g: 0, b: 0, a: 0 } });
     const timings = { renderCallMs: 0, screenshotMs: 0 };
-    let closing, sampleContextUsed = false, motionProbeUsed = false, dofSamples = 0;
-    const draw = async (t, { motionBlur = 1, motionBlurBase = motionBlur, motionProbeTime, dofMotionSamples } = {}) => {
+    let closing, sampleContextUsed = false, motionProbeUsed = false, dofSamples = 0;
+    const draw = async (t, { motionBlur = 1, motionBlurBase = motionBlur, motionProbeTime, dofMotionSamples, dofMotionIndex } = {}) => {
         const renderStart = performance.now();
-        const changed = await page.evaluate(({ t, motionBlur, motionBlurBase, motionProbeTime, dofMotionSamples, alpha }) => {
+        const changed = await page.evaluate(({ t, motionBlur, motionBlurBase, motionProbeTime, dofMotionSamples, dofMotionIndex, alpha }) => {
           globalThis.__multiplaneStatic?.suspend();
           if (alpha) document.documentElement.style.setProperty('--multiplane-page-background', 'transparent');
           const stage = document.querySelector('#stage');
@@ -139,7 +139,7 @@ async function openShotOnce(shot, scale = 1, options = {}) {
           SHOT.sampleContext = { time: t, motionBlurBase, get motionBlur() { contextUsed = true; return motionBlur; } };
           let failure;
           // Private renderer/layer handshake; never part of the shot contract.
-          const probe = globalThis.__multiplaneMotionProbe = { time: motionProbeTime, used: false, motionSamples: dofMotionSamples, samples: 0 };
+          const probe = globalThis.__multiplaneMotionProbe = { time: motionProbeTime, used: false, motionSamples: dofMotionSamples, motionIndex: dofMotionIndex, samples: 0 };
           try { SHOT.render(t); } catch (error) { failure = String(error?.message ?? error); } finally {
             delete globalThis.__multiplaneMotionProbe;
             if (previous === undefined) delete SHOT.sampleContext;
@@ -147,11 +147,11 @@ async function openShotOnce(shot, scale = 1, options = {}) {
           }
           stage.getBoundingClientRect();
           const changed = globalThis.__multiplaneStatic?.read() ?? true;
-          return { failure, contextUsed, probeUsed: probe.used, dofSamples: probe.samples, changed, reason: globalThis.__multiplaneStatic?.reason };
-        }, { t, motionBlur, motionBlurBase, motionProbeTime, dofMotionSamples, alpha }).then(({ failure, changed, contextUsed, probeUsed, dofSamples: count, reason }) => {
+          return { failure, contextUsed, probeUsed: probe.used, dofSamples: probe.samples, changed, reason: globalThis.__multiplaneStatic?.reason };
+        }, { t, motionBlur, motionBlurBase, motionProbeTime, dofMotionSamples, dofMotionIndex, alpha }).then(({ failure, changed, contextUsed, probeUsed, dofSamples: count, reason }) => {
           sampleContextUsed = contextUsed;
-          motionProbeUsed = probeUsed;
-          dofSamples = count;
+          motionProbeUsed = probeUsed;
+          dofSamples = count;
           const index = observationReasons.indexOf(reason);
           if (index >= 0) Atomics.add(reuseState(options), index + 4, 1);
           if (failure !== undefined) throw new MultiplaneError('render_threw', undefined, { details: { t, reason: failure } });
@@ -175,10 +175,10 @@ async function openShotOnce(shot, scale = 1, options = {}) {
         return { png: measured };
     };
     return {
-      page, browser, server, ...metadata, alpha, beginFrame, timings,
+      page, browser, server, ...metadata, alpha, beginFrame, timings, _inspectSample: draw,
       get sampleContextUsed() { return sampleContextUsed; },
-      get motionProbeUsed() { return motionProbeUsed; },
-      get dofSamples() { return dofSamples; },
+      get motionProbeUsed() { return motionProbeUsed; },
+      get dofSamples() { return dofSamples; },
       ...(reuseEnabled(options) ? { observe: draw } : {}),
       isCrash: error => browserClosed(error, browser, page, crashed),
       ...(metadata.hasBlurAt ? { blurAt: async t => {
@@ -195,13 +195,13 @@ async function openShotOnce(shot, scale = 1, options = {}) {
 // Recovery belongs to a complete output frame, never to an individual blur sample.
 export async function openShot(shot, scale = 1, options = {}) {
   const budget = options._browserRecovery ?? recoveryBudget();
-  let current, closed = false;
-  const recover = async (error, t) => {
+  let current, closed = false, stalled;
+  const recover = async (error, t, stallAttempt) => {
     options.check?.();
     if (closed) throw error;
     const failure = crashedError(error, t);
-    if (Atomics.load(budget, 0) >= MAX_BROWSER_RESTARTS) throw failure;
-    const attempt = Atomics.add(budget, 0, 1) + 1;
+    if (!stallAttempt && Atomics.load(budget, 0) >= MAX_BROWSER_RESTARTS) throw failure;
+    const attempt = stallAttempt ?? Atomics.add(budget, 0, 1) + 1;
     if (attempt > MAX_BROWSER_RESTARTS) throw failure;
     await current?.close().catch(() => {});
     try { current = await openShotOnce(shot, scale, options); }
@@ -211,7 +211,8 @@ export async function openShot(shot, scale = 1, options = {}) {
       restarted.details = { ...failure.details, ...restarted.details };
       throw restarted;
     }
-    options.onWarning?.({ code: 'browser_restarted', message: 'Browser restarted; retrying the affected frame.', details: { ...failure.details, attempt } });
+    if (!stallAttempt) options.onWarning?.({ code: 'browser_restarted', message: 'Browser restarted; retrying the affected frame.', details: { ...failure.details, attempt } });
+    options.onRecovered?.();
   };
   try { current = await openShotOnce(shot, scale, options); }
   catch (error) { if (error.code !== 'browser_crashed') throw error; await recover(error); }
@@ -220,17 +221,32 @@ export async function openShot(shot, scale = 1, options = {}) {
     get page() { return current.page; },
     get browser() { return current.browser; },
     get sampleContextUsed() { return current.sampleContextUsed; },
-    get motionProbeUsed() { return current.motionProbeUsed; },
-    get dofSamples() { return current.dofSamples; },
+    get motionProbeUsed() { return current.motionProbeUsed; },
+    get dofSamples() { return current.dofSamples; },
     ...(current.observe ? { observe: (...args) => current.observe(...args) } : {}),
     beginFrame: (...args) => current.beginFrame(...args),
+    _inspectSample: (...args) => current._inspectSample(...args),
     frame: (...args) => current.frame(...args),
     ...(current.blurAt ? { blurAt: (...args) => current.blurAt(...args) } : {}),
+    // Closing the owned browser interrupts a blocked evaluate/CDP screenshot.
+    // Let the complete post frame unwind before retrying any of its samples.
+    async stall(details) {
+      if (closed || stalled) return;
+      stalled = new MultiplaneError('browser_crashed', 'Rendering worker stopped delivering frames.', { details });
+      await current.close();
+    },
     async retryFrame(t, operation) {
+      let stallAttempts = 0;
       for (;;) {
         try { return await operation(); }
         catch (error) {
           options.check?.();
+          if (!closed && stalled) {
+            const failure = stalled; stalled = undefined;
+            if (stallAttempts >= MAX_BROWSER_RESTARTS) throw failure;
+            await recover(failure, t, ++stallAttempts);
+            continue;
+          }
           if (closed || !current.isCrash(error)) throw error;
           await recover(error, t);
         }

package/src/encoder.mjs

@@ -1,16 +1,16 @@
-import { invalidOption } from './errors.mjs';
-export const encoders = ['x264', 'nvenc-h264', 'nvenc-hevc'];
-
-export function encoderArgs(name = 'x264', quality, maxMbps) {
-  if (!encoders.includes(name)) throw invalidOption('--encoder', '--encoder must be x264, nvenc-h264 or nvenc-hevc.');
-  if (maxMbps !== undefined && !(Number.isFinite(maxMbps) && maxMbps > 0)) throw invalidOption('--max-bitrate', '--max-bitrate must be positive (Mbps).');
-  const cap = maxMbps ? ['-maxrate', `${maxMbps}M`, '-bufsize', `${maxMbps * 2}M`] : [];
-  if (name === 'x264') return ['-c:v', 'libx264', '-profile:v', 'high', '-crf', '16', ...cap];
-  quality ??= name === 'nvenc-hevc' ? 20 : 21;
-  if (!Number.isInteger(quality) || quality < 1 || quality > 51) throw invalidOption('NVENC', 'NVENC CQ must be an integer from 1 to 51.');
-  return ['-c:v', name === 'nvenc-h264' ? 'h264_nvenc' : 'hevc_nvenc',
-    '-preset', 'p7', '-tune', 'hq', '-rc', 'vbr', '-cq', String(quality), '-b:v', '0',
-    ...(maxMbps ? cap : ['-qmin', '0', '-qmax', String(Math.min(51, quality + 2))]),
-    '-multipass', 'fullres', '-spatial-aq', '1', '-temporal-aq', '1', '-rc-lookahead', '32', '-bf', '3',
-    ...(name === 'nvenc-h264' ? ['-profile:v', 'high'] : ['-tag:v', 'hvc1'])];
-}
+import { invalidOption } from './errors.mjs';
+export const encoders = ['x264', 'nvenc-h264', 'nvenc-hevc'];
+
+export function encoderArgs(name = 'x264', quality, maxMbps) {
+  if (!encoders.includes(name)) throw invalidOption('--encoder', '--encoder must be x264, nvenc-h264 or nvenc-hevc.');
+  if (maxMbps !== undefined && !(Number.isFinite(maxMbps) && maxMbps > 0)) throw invalidOption('--max-bitrate', '--max-bitrate must be positive (Mbps).');
+  const cap = maxMbps ? ['-maxrate', `${maxMbps}M`, '-bufsize', `${maxMbps * 2}M`] : [];
+  if (name === 'x264') return ['-c:v', 'libx264', '-profile:v', 'high', '-crf', '16', ...cap];
+  quality ??= name === 'nvenc-hevc' ? 20 : 21;
+  if (!Number.isInteger(quality) || quality < 1 || quality > 51) throw invalidOption('NVENC', 'NVENC CQ must be an integer from 1 to 51.');
+  return ['-c:v', name === 'nvenc-h264' ? 'h264_nvenc' : 'hevc_nvenc',
+    '-preset', 'p7', '-tune', 'hq', '-rc', 'vbr', '-cq', String(quality), '-b:v', '0',
+    ...(maxMbps ? cap : ['-qmin', '0', '-qmax', String(Math.min(51, quality + 2))]),
+    '-multipass', 'fullres', '-spatial-aq', '1', '-temporal-aq', '1', '-rc-lookahead', '32', '-bf', '3',
+    ...(name === 'nvenc-h264' ? ['-profile:v', 'high'] : ['-tag:v', 'hvc1'])];
+}

package/src/environment.mjs

@@ -1,56 +1,56 @@
-import { chromium } from 'playwright';
-import { browserOptions, browserHint } from './platform.mjs';
-import { MultiplaneError } from './errors.mjs';
-export async function launchBrowser(options = {}, launcher = chromium, platform = process.platform) {
-  let browser;
-  try {
-    try {
-      browser = await launcher.launch(browserOptions(options.raster ?? 'gpu', options, platform));
-      if (platform !== 'linux' || options.raster === 'software' || (await environment(browser)).gpu.hardware) return browser;
-      await browser.close(); browser = undefined;
-    } catch (error) {
-      await browser?.close(); browser = undefined;
-      if (platform !== 'linux' || options.raster === 'software' || /Executable doesn't exist/.test(error.message)) throw error;
-    }
-    // ANGLE can launch without a working GL device on a headless Linux host.
-    // Relaunch with SwiftShader so WebGL shots remain usable and repeatable.
-    return await launcher.launch(browserOptions('software', options, platform));
-  } catch (cause) { throw new MultiplaneError(/Executable doesn't exist/.test(cause.message) ? 'browser_not_installed' : 'browser_launch_failed', undefined,
-    { cause, hint: browserHint(/Executable doesn't exist/.test(cause.message), platform), details: { reason: cause.message.split(/\r?\n/)[0] } }); }
-}
-export async function environment(browser, ffmpeg = null) {
-  const session = await browser.newBrowserCDPSession();
-  try {
-    const { gpu } = await session.send('SystemInfo.getInfo');
-    const renderer = gpu.auxAttributes?.glRenderer ?? gpu.devices?.[0]?.deviceString ?? 'unknown';
-    return { node: process.version, platform: process.platform, chromium: browser.version(),
-      gpu: { renderer, hardware: !/swiftshader|llvmpipe|software|unknown/i.test(renderer) }, ffmpeg };
-  } finally { await session.detach(); }
-}
-export async function loaded(events, capture, ffmpeg = null) {
-  events.options.alpha = capture.alpha;
-  events.start(true);
-  const { width, height, duration, fps, cuts, post } = capture;
-  events.emit('shot', { width, height, duration, fps, cuts, post });
-  events.check();
-}
-
-export function warnGpuFallback(events, info, options = {}) {
-  if ((options.raster ?? 'gpu') === 'gpu' && !info.gpu.hardware) {
-    events.emit('warning', { code: 'gpu_software_fallback', message: 'Hardware GPU rasterization is unavailable.' });
-  }
-}
-
-export const observeBrowser = (events, ffmpeg = null) => {
-  let observed = false;
-  return async browser => {
-    const unsubscribe = events.onCancel(() => browser.close());
-    browser.once('disconnected', unsubscribe);
-    events.check();
-    if (observed) return;
-    const info = await environment(browser, ffmpeg);
-    observed = true;
-    events.emit('environment', info);
-    warnGpuFallback(events, info, events.options);
-  };
-};
+import { chromium } from 'playwright';
+import { browserOptions, browserHint } from './platform.mjs';
+import { MultiplaneError } from './errors.mjs';
+export async function launchBrowser(options = {}, launcher = chromium, platform = process.platform) {
+  let browser;
+  try {
+    try {
+      browser = await launcher.launch(browserOptions(options.raster ?? 'gpu', options, platform));
+      if (platform !== 'linux' || options.raster === 'software' || (await environment(browser)).gpu.hardware) return browser;
+      await browser.close(); browser = undefined;
+    } catch (error) {
+      await browser?.close(); browser = undefined;
+      if (platform !== 'linux' || options.raster === 'software' || /Executable doesn't exist/.test(error.message)) throw error;
+    }
+    // ANGLE can launch without a working GL device on a headless Linux host.
+    // Relaunch with SwiftShader so WebGL shots remain usable and repeatable.
+    return await launcher.launch(browserOptions('software', options, platform));
+  } catch (cause) { throw new MultiplaneError(/Executable doesn't exist/.test(cause.message) ? 'browser_not_installed' : 'browser_launch_failed', undefined,
+    { cause, hint: browserHint(/Executable doesn't exist/.test(cause.message), platform), details: { reason: cause.message.split(/\r?\n/)[0] } }); }
+}
+export async function environment(browser, ffmpeg = null) {
+  const session = await browser.newBrowserCDPSession();
+  try {
+    const { gpu } = await session.send('SystemInfo.getInfo');
+    const renderer = gpu.auxAttributes?.glRenderer ?? gpu.devices?.[0]?.deviceString ?? 'unknown';
+    return { node: process.version, platform: process.platform, chromium: browser.version(),
+      gpu: { renderer, hardware: !/swiftshader|llvmpipe|software|unknown/i.test(renderer) }, ffmpeg };
+  } finally { await session.detach(); }
+}
+export async function loaded(events, capture, ffmpeg = null) {
+  events.options.alpha = capture.alpha;
+  events.start(true);
+  const { width, height, duration, fps, cuts, post } = capture;
+  events.emit('shot', { width, height, duration, fps, cuts, post });
+  events.check();
+}
+
+export function warnGpuFallback(events, info, options = {}) {
+  if ((options.raster ?? 'gpu') === 'gpu' && !info.gpu.hardware) {
+    events.emit('warning', { code: 'gpu_software_fallback', message: 'Hardware GPU rasterization is unavailable.' });
+  }
+}
+
+export const observeBrowser = (events, ffmpeg = null) => {
+  let observed = false;
+  return async browser => {
+    const unsubscribe = events.onCancel(() => browser.close());
+    browser.once('disconnected', unsubscribe);
+    events.check();
+    if (observed) return;
+    const info = await environment(browser, ffmpeg);
+    observed = true;
+    events.emit('environment', info);
+    warnGpuFallback(events, info, events.options);
+  };
+};

package/src/errors.mjs

@@ -18,6 +18,7 @@ export const errorCodes = Object.freeze(Object.fromEntries([
   [3, 'skill_changed', 'The installed skill changed since inspection.'],
   [3, 'unsupported_node', 'Node 24 or newer is required.'],
   [2, 'invalid_option', 'Invalid option.'],
+  [2, 'resume_unavailable', 'This render cannot be resumed.'],
   [2, 'invalid_scale', 'Scale must produce positive even integer dimensions.'],
   [2, 'output_exists', 'Output already exists.'],
   [3, 'ffmpeg_not_found', 'FFmpeg was not found.'],

package/src/events.mjs

@@ -105,6 +105,7 @@ export function createEvents(command, shot, options = {}, job = false, deferStar
   if (!options._hostedCLI) monitor();
   return {
     directory, jobId, emit, warning, artifacts, options, monitor,
+    ...(options._resume ? { resumeData: { resumedFrom: options._resume.jobId, resume: { segmentsReused: 0, framesReused: 0 } } } : {}),
     // TODO(design): Document memoryBytes in status.json (latest sample, null on failure).
     memory(bytes) { state.memoryBytes = bytes; state.updatedAt = new Date().toISOString(); save(); },
     preview(frame) { state.previewFrame = frame; state.updatedAt = new Date().toISOString(); save(); },
@@ -113,7 +114,8 @@ export function createEvents(command, shot, options = {}, job = false, deferStar
       if (deferStart && !resolved) { save(); return; }
       startedEvent = true;
       const { onEvent, _preview, _resources, _probeVideo, _inspectFFmpeg, _hostedCLI, ...effective } = options;
-      emit('start', { version, shot, ...(jobId ? { jobId } : {}), options: effective, ...(this.workersSource ? { workersSource: this.workersSource } : {}) });
+      for (const key of Object.keys(effective)) if (key.startsWith('_')) delete effective[key];
+      emit('start', { ...this.resumeData, version, shot, ...(jobId ? { jobId } : {}), options: effective, ...(this.workersSource ? { workersSource: this.workersSource } : {}) });
       index('start', { command, shot, pid: process.pid });
       for (const [type, fields] of pendingEvents.splice(0)) emit(type, fields);
     },
@@ -129,7 +131,7 @@ export function createEvents(command, shot, options = {}, job = false, deferStar
       if (deferStart) this.start(true);
       const result = { command, ok: !error, code: error?.code ?? null, message: error?.message ?? null,
         ...(error?.hint ? { hint: error.hint } : {}), ...(error?.details ? { details: error.details } : {}),
-        artifacts, elapsedMs: Math.round(performance.now() - started), ...(jobId ? { jobId } : {}), data };
+        artifacts, elapsedMs: Math.round(performance.now() - started), ...(jobId ? { jobId } : {}), data: this.resumeData ? { ...this.resumeData, ...data } : data };
       index('end', { state: !error ? 'succeeded' : error.code === 'cancelled' ? 'cancelled' : 'failed' });
       emit('result', result);
       return result;
@@ -142,7 +144,7 @@ export async function runCommand(command, shot, options, action, job = true) {
   let events, resources, linted = false;
   try {
     const explicit = options;
-    const user = loadUserConfig(command, options);
+    const user = options._effectiveOptions ? { options: { ...options }, config: { applied: [] }, warnings: [] } : loadUserConfig(command, options);
     options = user.options;
     if (['render', 'stills', 'verify'].includes(command)) {
       options.quality = resolveQuality(options);
@@ -192,7 +194,7 @@ export async function runCommand(command, shot, options, action, job = true) {
       if (!options['no-lint']) { await checkLint(shot, events.options, events); linted = true; }
       events.start();
       const request = { schema: 'multiplane/1', jobId: events.jobId, jobDir: events.directory,
-        command, args: options._hostedCLI.args, cwd: process.cwd(), node: process.execPath,
+        command: options._resume ? 'resume' : command, args: options._hostedCLI.args, cwd: process.cwd(), node: process.execPath,
         bin: options._hostedCLI.bin, env: hostedEnvironment(process.env), at: new Date().toISOString() };
       const ownership = await handoff(request);
       if (ownership.hosted) {
@@ -210,7 +212,7 @@ export async function runCommand(command, shot, options, action, job = true) {
       resources = createResourceSampler({ enabled: options._resources !== false, onSample: events.memory });
       events.resources = resources;
     }
-    if (options.draft) {
+    if (options.draft && !options._effectiveOptions) {
       // Keep lint and cancellation active before the dimension-only draft probe.
       if (!linted && !options['no-lint']) {
         const { findings, data } = await scanShot(shot, events.options);
@@ -221,17 +223,17 @@ export async function runCommand(command, shot, options, action, job = true) {
         }
       }
       const normalized = { ...Object.fromEntries(Object.keys(explicit).filter(key => key !== '_hostedCLI').map(key => [key, options[key]])), draft: true };
-      Object.assign(events.options, await applyDraft(command, shot, normalized, options, {
+      Object.assign(events.options, await applyDraft(command, shot, normalized, options, {
         check: events.check,
         onBrowser: browser => {
           const unsubscribe = events.onCancel(() => browser.close());
           browser.once('disconnected', unsubscribe);
           events.check();
         },
-      }));
-      // Draft merges explicit options again; retain the absolute output path
-      // required by atomic directory publication and artifact relocation.
-      events.options.out = path.resolve(events.options.out);
+      }));
+      // Draft merges explicit options again; retain the absolute output path
+      // required by atomic directory publication and artifact relocation.
+      events.options.out = path.resolve(events.options.out);
     }
     events.start();
     for (const warning of user.warnings) events.warning(warning);

package/src/ffmpeg.mjs

@@ -1,32 +1,32 @@
-import { spawn } from 'node:child_process';
-import { MultiplaneError } from './errors.mjs';
-import { ffmpegName, ffmpegHint } from './platform.mjs';
-
-export function ffmpegOutput(executable, args, env = process.env) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(executable, args, { env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
-    const timer = setTimeout(() => child.kill('SIGKILL'), 15000);
-    child.once('close', () => clearTimeout(timer));
-    child.once('error', () => clearTimeout(timer));
-    let output = '';
-    child.stdout.on('data', bytes => { output += bytes; });
-    child.stderr.on('data', bytes => { output += bytes; });
-    child.once('error', reject);
-    child.once('close', code => code === 0 ? resolve(output) : reject(new Error(`FFmpeg exited with code ${code}.`)));
-  });
-}
-export async function inspectFFmpeg(explicit, env = process.env, encoder, output = ffmpegOutput) {
-  const executable = explicit ?? env.MULTIPLANE_FFMPEG ?? ffmpegName();
-  try {
-    const version = (await output(executable, ['-version'], env)).split(/\r?\n/)[0];
-    if (encoder && !new RegExp(`\\b${encoder}\\b`).test(await output(executable, ['-encoders'], env))) throw new Error(`Missing encoder: ${encoder}`);
-    return { path: executable, version };
-  } catch (cause) {
-    throw new MultiplaneError(cause.code === 'ENOENT' ? 'ffmpeg_not_found' : 'ffmpeg_unusable', undefined,
-      { cause, hint: cause.message.startsWith('Missing encoder:') ? `${cause.message}. Use an FFmpeg build that includes it.` : ffmpegHint(), details: { reason: cause.message } });
-  }
-}
-
-export async function resolveFFmpeg(explicit, env = process.env) {
-  return (await inspectFFmpeg(explicit, env)).path;
-}
+import { spawn } from 'node:child_process';
+import { MultiplaneError } from './errors.mjs';
+import { ffmpegName, ffmpegHint } from './platform.mjs';
+
+export function ffmpegOutput(executable, args, env = process.env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const timer = setTimeout(() => child.kill('SIGKILL'), 15000);
+    child.once('close', () => clearTimeout(timer));
+    child.once('error', () => clearTimeout(timer));
+    let output = '';
+    child.stdout.on('data', bytes => { output += bytes; });
+    child.stderr.on('data', bytes => { output += bytes; });
+    child.once('error', reject);
+    child.once('close', code => code === 0 ? resolve(output) : reject(new Error(`FFmpeg exited with code ${code}.`)));
+  });
+}
+export async function inspectFFmpeg(explicit, env = process.env, encoder, output = ffmpegOutput) {
+  const executable = explicit ?? env.MULTIPLANE_FFMPEG ?? ffmpegName();
+  try {
+    const version = (await output(executable, ['-version'], env)).split(/\r?\n/)[0];
+    if (encoder && !new RegExp(`\\b${encoder}\\b`).test(await output(executable, ['-encoders'], env))) throw new Error(`Missing encoder: ${encoder}`);
+    return { path: executable, version };
+  } catch (cause) {
+    throw new MultiplaneError(cause.code === 'ENOENT' ? 'ffmpeg_not_found' : 'ffmpeg_unusable', undefined,
+      { cause, hint: cause.message.startsWith('Missing encoder:') ? `${cause.message}. Use an FFmpeg build that includes it.` : ffmpegHint(), details: { reason: cause.message } });
+  }
+}
+
+export async function resolveFFmpeg(explicit, env = process.env) {
+  return (await inspectFFmpeg(explicit, env)).path;
+}

package/src/format.mjs

@@ -1,27 +1,27 @@
-import path from 'node:path';
-import { MultiplaneError, invalidOption } from './errors.mjs';
-import { encoderArgs } from './encoder.mjs';
-
-export function resolveFormat(options = {}) {
-  const extension = path.extname(options.out ?? '').slice(1).toLowerCase();
-  const formats = ['mp4', 'webm', 'mov'];
-  const format = options.format ?? (formats.includes(extension) ? extension : 'mp4');
-  if (!formats.includes(format)) throw invalidOption('--format', '--format must be mp4, webm or mov.');
-  // TODO(design): Document rejection of unknown output extensions as well as conflicts.
-  if (extension && extension !== format) throw invalidOption('--out', '--out extension must match --format.');
-  if (format !== 'mp4' && options.encoder !== undefined) throw invalidOption('--encoder', '--encoder only applies to mp4; omit it for webm or mov.');
-  // TODO(design): Define bitrate controls for the fixed-codec formats if needed.
-  if (format !== 'mp4' && options['max-bitrate'] !== undefined) throw invalidOption('--max-bitrate', '--max-bitrate currently only applies to mp4.');
-  if (format === 'mp4' && options.alpha) throw new MultiplaneError('invalid_option', 'MP4 does not support alpha.', { details: { option: '--alpha' }, hint: 'Use --format webm or --format mov and a matching --out extension.' });
-  return format;
-}
-
-export function videoEncoding(options) {
-  const { format, alpha } = options;
-  if (format === 'webm') {
-    // TODO(design): Document the fixed VP9 quality preset and audio codec.
-    return { encoder: 'libvpx-vp9', args: ['-c:v', 'libvpx-vp9', '-crf', alpha ? '0' : '16', '-b:v', '0', '-auto-alt-ref', '0', ...(alpha ? ['-lossless', '1'] : [])], pixelFormat: alpha ? 'yuva420p' : 'yuv420p', mux: [], audio: ['-c:a', 'libopus', '-b:a', '320k', '-ac', '2'] };
-  }
-  if (format === 'mov') return { encoder: 'prores_ks', args: ['-c:v', 'prores_ks', '-profile:v', '4'], pixelFormat: alpha ? 'yuva444p10le' : 'yuv444p10le', mux: ['-movflags', '+faststart'], audio: ['-c:a', 'aac', '-b:a', '320k', '-ac', '2'] };
-  return { encoder: options.encoder ?? 'x264', args: encoderArgs(options.encoder ?? 'x264', undefined, options['max-bitrate']), pixelFormat: 'yuv420p', mux: ['-movflags', '+faststart'], audio: ['-c:a', 'aac', '-b:a', '320k', '-ac', '2'] };
-}
+import path from 'node:path';
+import { MultiplaneError, invalidOption } from './errors.mjs';
+import { encoderArgs } from './encoder.mjs';
+
+export function resolveFormat(options = {}) {
+  const extension = path.extname(options.out ?? '').slice(1).toLowerCase();
+  const formats = ['mp4', 'webm', 'mov'];
+  const format = options.format ?? (formats.includes(extension) ? extension : 'mp4');
+  if (!formats.includes(format)) throw invalidOption('--format', '--format must be mp4, webm or mov.');
+  // TODO(design): Document rejection of unknown output extensions as well as conflicts.
+  if (extension && extension !== format) throw invalidOption('--out', '--out extension must match --format.');
+  if (format !== 'mp4' && options.encoder !== undefined) throw invalidOption('--encoder', '--encoder only applies to mp4; omit it for webm or mov.');
+  // TODO(design): Define bitrate controls for the fixed-codec formats if needed.
+  if (format !== 'mp4' && options['max-bitrate'] !== undefined) throw invalidOption('--max-bitrate', '--max-bitrate currently only applies to mp4.');
+  if (format === 'mp4' && options.alpha) throw new MultiplaneError('invalid_option', 'MP4 does not support alpha.', { details: { option: '--alpha' }, hint: 'Use --format webm or --format mov and a matching --out extension.' });
+  return format;
+}
+
+export function videoEncoding(options) {
+  const { format, alpha } = options;
+  if (format === 'webm') {
+    // TODO(design): Document the fixed VP9 quality preset and audio codec.
+    return { encoder: 'libvpx-vp9', args: ['-c:v', 'libvpx-vp9', '-crf', alpha ? '0' : '16', '-b:v', '0', '-auto-alt-ref', '0', ...(alpha ? ['-lossless', '1'] : [])], pixelFormat: alpha ? 'yuva420p' : 'yuv420p', mux: [], audio: ['-c:a', 'libopus', '-b:a', '320k', '-ac', '2'] };
+  }
+  if (format === 'mov') return { encoder: 'prores_ks', args: ['-c:v', 'prores_ks', '-profile:v', '4'], pixelFormat: alpha ? 'yuva444p10le' : 'yuv444p10le', mux: ['-movflags', '+faststart'], audio: ['-c:a', 'aac', '-b:a', '320k', '-ac', '2'] };
+  return { encoder: options.encoder ?? 'x264', args: encoderArgs(options.encoder ?? 'x264', undefined, options['max-bitrate']), pixelFormat: 'yuv420p', mux: ['-movflags', '+faststart'], audio: ['-c:a', 'aac', '-b:a', '320k', '-ac', '2'] };
+}

package/src/frame-rate.mjs

@@ -1,28 +1,28 @@
-import { invalidOption } from './errors.mjs';
-
-// Encoding time only: capture and post-processing must keep the requested fps.
-// Snap NTSC shorthand within 0.0001 fps of n * 1000 / 1001. Otherwise round
-// to six decimal places (at most 0.0000005 fps error) and reduce the fraction.
-// FFmpeg's AVRational stores both terms as signed 32-bit integers.
-export function frameRate(fps) {
-  if (!Number.isFinite(fps) || fps <= 0) throw invalidOption('--fps', '--fps must be positive and finite.');
-  const nominal = Math.round(fps * 1001 / 1000);
-  let numerator, denominator;
-  if (nominal > 0 && Math.abs(fps - nominal * 1000 / 1001) <= 0.0001) {
-    numerator = nominal * 1000;
-    denominator = 1001;
-  } else {
-    numerator = Math.round(fps * 1e6);
-    denominator = 1e6;
-  }
-  if (!Number.isSafeInteger(numerator) || numerator <= 0) throw invalidOption('--fps', 'Frame rate cannot be represented at micro-fps precision.');
-  let a = numerator, b = denominator;
-  while (b) [a, b] = [b, a % b];
-  numerator /= a; denominator /= a;
-  if (numerator > 2147483647) throw invalidOption('--fps', 'Frame rate exceeds FFmpeg rational precision.');
-  return {
-    numerator, denominator, argument: `${numerator}/${denominator}`,
-    fps: numerator / denominator,
-    seconds: frames => frames * denominator / numerator,
-  };
-}
+import { invalidOption } from './errors.mjs';
+
+// Encoding time only: capture and post-processing must keep the requested fps.
+// Snap NTSC shorthand within 0.0001 fps of n * 1000 / 1001. Otherwise round
+// to six decimal places (at most 0.0000005 fps error) and reduce the fraction.
+// FFmpeg's AVRational stores both terms as signed 32-bit integers.
+export function frameRate(fps) {
+  if (!Number.isFinite(fps) || fps <= 0) throw invalidOption('--fps', '--fps must be positive and finite.');
+  const nominal = Math.round(fps * 1001 / 1000);
+  let numerator, denominator;
+  if (nominal > 0 && Math.abs(fps - nominal * 1000 / 1001) <= 0.0001) {
+    numerator = nominal * 1000;
+    denominator = 1001;
+  } else {
+    numerator = Math.round(fps * 1e6);
+    denominator = 1e6;
+  }
+  if (!Number.isSafeInteger(numerator) || numerator <= 0) throw invalidOption('--fps', 'Frame rate cannot be represented at micro-fps precision.');
+  let a = numerator, b = denominator;
+  while (b) [a, b] = [b, a % b];
+  numerator /= a; denominator /= a;
+  if (numerator > 2147483647) throw invalidOption('--fps', 'Frame rate exceeds FFmpeg rational precision.');
+  return {
+    numerator, denominator, argument: `${numerator}/${denominator}`,
+    fps: numerator / denominator,
+    seconds: frames => frames * denominator / numerator,
+  };
+}