multiplane 0.3.7 → 0.3.10

package/src/render-pool.mjs

@@ -4,6 +4,7 @@ import { MultiplaneError } from './errors.mjs';
 import { availableParallelism, freemem, totalmem } from 'node:os';
 import { Worker } from 'node:worker_threads';
 import { blurSampleReport } from './post.mjs';
+import { createCaptureWatchdog } from './capture-watchdog.mjs';
 
 export function defaultWorkers(scale = 1, hardware = {}) {
   const cores = hardware.cores ?? availableParallelism();
@@ -12,24 +13,50 @@ export function defaultWorkers(scale = 1, hardware = {}) {
   return Math.max(1, Math.min(12, Math.floor(cores / 2), Math.floor((free - 2 * 1024 ** 3) / workerBytes)));
 }
 
-export function createRenderPool(shot, options, fps, workers, size, onWarning, onCaptured) {
+export function createRenderPool(shot, options, fps, workers, size, onWarning, onCaptured, onInput) {
   options = { ...options, _browserRecovery: options._browserRecovery ?? recoveryBudget() };
   reuseState(options);
   const slots = [], stats = { frames: 0, samples: 0, staticFrames: 0 };
   const histogram = {}, dofHistogram = {};
   const captured = new Set();
-  let failure;
+  let failure, stopping = false, closing;
+  function close() {
+    if (closing) return closing;
+    stopping = true; watchdog.stop();
+    for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'close' });
+    // A blocked page cannot finish its frame. Close only browsers owned by
+    // these workers after the grace period, letting their normal cleanup run.
+    const timer = setTimeout(() => {
+      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'cancel' });
+    }, options._stopGraceMs ?? 5000); // Internal override for short fault tests.
+    closing = Promise.all(slots.map(s => s.exited)).finally(() => clearTimeout(timer));
+    return closing;
+  }
+  // Internal deadline override for short fault-injection tests; no CLI option.
+  const watchdog = createCaptureWatchdog(slots, (slot, details) => {
+    if (failure || stopping) return;
+    try {
+      onWarning?.({ code: 'worker_stalled', severity: 'warning', message: 'Rendering worker stalled.', details });
+      slot.worker.postMessage({ type: 'stalled', details });
+    } catch (error) { fail(error); }
+  }, { minimumMs: options._stallTimeoutMs });
+  const fail = error => {
+    failure ??= error;
+    watchdog.stop();
+    for (const s of slots) { s.pending?.reject(failure); s.pending = null; }
+    void close();
+  };
   for (let i = 0; i < workers; i++) {
     const worker = new Worker(new URL('./render-worker.mjs', import.meta.url), { workerData: { shot, options, fps, size } });
     const slot = { worker, pending: null, closed: false };
-    const fail = error => {
-      failure ??= error;
-      for (const s of slots) { s.pending?.reject(error); s.pending = null; }
-    };
     slot.ready = new Promise((resolve, reject) => { slot.pending = { resolve, reject }; });
     slot.ready.catch(() => {});
     worker.on('message', message => {
+      if (message.type === 'frame-start') { slot.frame = message.frame; slot.frameStarted = performance.now(); return; }
+      if (message.type === 'recovered') { watchdog.recovered(slot); return; }
+      if (message.type === 'input') { try { onInput?.(message.file, message.record); } catch (error) { fail(error); } return; }
       if (message.type === 'captured') {
+        watchdog.completed(slot);
         if (!captured.has(message.frame)) {
           captured.add(message.frame);
           try { onCaptured?.(captured.size); } catch (error) { fail(error); }
@@ -39,6 +66,7 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
       if (message.type === 'warning') { onWarning?.(message.warning); return; }
       if (message.type === 'failure') { fail(new MultiplaneError(message.code ?? 'worker_crashed', message.error, { details: message.details, hint: message.hint })); return; }
       const pending = slot.pending; slot.pending = null;
+      slot.job = null;
       pending?.resolve(message);
     });
     worker.on('error', error => fail(new MultiplaneError('worker_crashed', undefined, { cause: error })));
@@ -66,6 +94,8 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
         next = Math.min(end, next + chunk, reuseEnabled(options) ? (Math.floor(begin / REUSE_INTERVAL) + 1) * REUSE_INTERVAL + 1 : end);
         const promise = new Promise((resolve, reject) => { slot.pending = { resolve, reject }; });
         promise.catch(() => {});
+        slot.job = { first: begin, end: next }; slot.frame = begin;
+        slot.lastDelivery = performance.now(); slot.frameStarted = undefined;
         slot.worker.postMessage({ type: 'render', first: begin, end: next });
         queue.push({ slot, promise });
       };
@@ -86,13 +116,10 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
         if (options.transport !== 'raw') schedule(slot);
       }
     },
-    async close() {
-      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'close' });
-      await Promise.all(slots.map(s => s.exited));
-    },
+    close,
     async cancel() {
-      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'cancel' });
-      await Promise.all(slots.map(s => s.exited));
+      fail(new MultiplaneError('cancelled'));
+      await close();
     },
   };
   const frames = api.frames.bind(api);

package/src/render-worker.mjs

@@ -3,8 +3,11 @@ import { MultiplaneError, asError } from './errors.mjs';
 import { parentPort, workerData, isMarkedAsUntransferable } from 'node:worker_threads';
 import { openShot } from './capture.mjs';
 import { createPostCapture, resolveScale } from './post.mjs';
+import { inputRecords } from './input-records.mjs';
 
-let capture, closing = false, running = false;
+if (workerData.options._recordInputs) inputRecords.enterWith((file, record) => parentPort.postMessage({ type: 'input', file, record }));
+
+let capture, closing = false, running = false, activeFrame;
 const sendFailure = error => {
   const failure = asError(error);
   parentPort.postMessage({ type: 'failure', error: failure.message, code: failure.code, details: failure.details, hint: failure.hint });
@@ -16,12 +19,17 @@ async function close() {
   parentPort.close();
 }
 try {
-  capture = await openShot(workerData.shot, resolveScale(workerData.options).renderScale, { ...workerData.options, onWarning: warning => parentPort.postMessage({ type: 'warning', warning }), check: () => { if (closing) throw new MultiplaneError('cancelled'); } });
+  capture = await openShot(workerData.shot, resolveScale(workerData.options).renderScale, { ...workerData.options, onRecovered: () => parentPort.postMessage({ type: 'recovered' }), onWarning: warning => parentPort.postMessage({ type: 'warning', warning }), check: () => { if (closing) throw new MultiplaneError('cancelled'); } });
   if (workerData.size && (capture.width !== workerData.size.width || capture.height !== workerData.size.height)) throw new MultiplaneError('internal_error', 'Worker stage dimensions differ from the main process.');
   const processed = createPostCapture(capture, { ...workerData.options, onWarning: warning => parentPort.postMessage({ type: 'warning', warning }) }, workerData.fps);
   parentPort.on('message', async message => {
     if (message.type === 'cancel') { closing = true; await capture?.close(); if (!running) parentPort.close(); return; }
     if (message.type === 'close') { await close(); return; }
+    if (message.type === 'stalled') {
+      if (!closing && activeFrame === message.details.frame) await capture.stall(message.details).catch(sendFailure);
+      else parentPort.postMessage({ type: 'recovered' });
+      return;
+    }
     if (closing) return;
     running = true;
     try {
@@ -29,7 +37,10 @@ try {
       const source = async function* (first, end) {
         for (let index = first; index < end && !closing; index++) {
           const frame = message.first + index;
+          activeFrame = frame;
+          parentPort.postMessage({ type: 'frame-start', frame });
           const png = await processed.frame(frame / workerData.fps, frame, index === end - 1);
+          activeFrame = undefined;
           parentPort.postMessage({ type: 'captured', frame });
           yield { png, hash: processed.lastHash, blurSamples: processed.lastBlurSamples, dofSamples: processed.lastDofSamples };
         }

package/src/render.mjs

@@ -1,9 +1,8 @@
 import { readBenchmark, benchmarkMachine, selectWorkers, classifyShot } from './workers.mjs';
 import { recoveryBudget } from './browser-recovery.mjs';
 import path from 'node:path';
-import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { mkdir, rm, writeFile, rename } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
 import { stopChild } from './process.mjs';
 import { inspectFFmpeg } from './ffmpeg.mjs';
 import { openShot, number } from './capture.mjs';
@@ -11,19 +10,28 @@ import { createPostCapture, resolveScale } from './post.mjs';
 import { createRenderPool } from './render-pool.mjs';
 import { resolveFormat, videoEncoding } from './format.mjs';
 import { checkAlphaVideo } from './output-alpha.mjs';
-import { writeFrame } from './video-pipe.mjs';
-import { runCommand } from './events.mjs';
+import { inputRecords, recordInput } from './input-records.mjs';
+import { atomicJSON, lockSegments, manifestStore, checkInputs, checkEnvironment, reusableSegments, readManifest, unavailable } from './segments.mjs';
+import { segmentEncoder, assembleSegments } from './segment-encoder.mjs';
+import { version, runCommand } from './events.mjs';
 import { loaded, observeBrowser, environment } from './environment.mjs';
-import { MultiplaneError, invalidOption } from './errors.mjs';
+import { invalidOption } from './errors.mjs';
 import { requireNewOutput, publishVideo } from './artifacts.mjs';
 import { createPreview } from './preview.mjs';
 import { checkVideo } from './output-check.mjs';
 import { frameRate } from './frame-rate.mjs';
 
+const persistedOptions = options => Object.fromEntries(Object.entries(options).filter(([key, value]) =>
+  !key.startsWith('_') && typeof value !== 'function' && !['job-dir-exact', 'hosted-executor'].includes(key)));
+
 export async function renderShot(shot, options = {}) {
-  return runCommand('render', shot, options, async events => {
+  return runCommand('render', shot, options, async events => inputRecords.run(null, async () => {
     options = { ...events.options };
     delete options.onEvent;
+    const resume = options._resume; delete options._resume;
+    const hook = options._segmentHook; delete options._segmentHook;
+    const segmentFrames = options._segmentFrames; delete options._segmentFrames;
+    delete options._effectiveOptions;
     const probe = options._probeVideo;
     delete options._probeVideo;
     const inspect = options._inspectFFmpeg ?? inspectFFmpeg;
@@ -32,25 +40,56 @@ export async function renderShot(shot, options = {}) {
     const name = path.basename(shot, path.extname(shot));
     let result;
 
-    let capture, pool, encoder, temporary, cleaning, encoderClosed = false;
+    let capture, pool, temporary, cleaning, store, directory, release, movedSource;
+    const encoders = new Set(), pending = [];
+    const inputs = {};
+    const onInput = (file, record) => { if (store) store.input(file, record); else inputs[file] = record; };
+    inputRecords.enterWith(onInput);
     function cleanup() { return cleaning ??= cleanResources(); }
     async function cleanResources() {
       try {
-        if (encoder && !encoderClosed) await stopChild(encoder);
+        await Promise.all([...encoders].map(encoder => stopChild(encoder)));
+        await Promise.allSettled(pending);
       } finally {
         try { await capture?.close(); }
-        finally { try { await pool?.close(); } finally { if (temporary) await rm(temporary, { force: true }); } }
+        finally { try { await pool?.close(); } finally {
+          try {
+            if (temporary && movedSource) await rename(temporary, movedSource);
+            else if (temporary) await rm(temporary, { force: true });
+          } finally { release?.(); }
+        } }
       }
     }
 
     try {
+      if (resume) {
+        directory = resume.directory;
+        release ??= lockSegments(directory);
+        resume.manifest = readManifest(directory);
+        if (!resume.manifest) throw unavailable('missing_manifest');
+        atomicJSON(path.join(events.directory, 'resume.json'), { directory });
+        await checkInputs(resume.manifest);
+      }
       const out = path.resolve(options.out ?? path.join(events.directory, `${name}.${options.format}`));
+      if (!resume) {
+        directory = path.join(events.directory, 'segments');
+        release = lockSegments(directory);
+        // A launch failure can be retried even before metadata or a first frame
+        // exists. Replace this provisional record with effective values below.
+        store = manifestStore(directory, { schema: 'multiplane-segments/1', jobId: events.jobId,
+          shot: path.resolve(options.root, shot), options: persistedOptions({ ...options, out,
+            audio: options.audio ? path.resolve(options.audio) : undefined }),
+          environment: null, first: 0, end: 0, total: 0, segmentFrames: segmentFrames ?? null, inputs: {}, segments: [] });
+        store.save();
+        await recordInput(path.resolve(options.root, shot));
+        if (options.audio) await recordInput(path.resolve(options.audio));
+      }
       if (!options.overwrite) await requireNewOutput(out);
       events.check();
       events.progress('launch');
       const { scale, renderScale } = resolveScale(options);
       const encoding = videoEncoding(options);
-      let videoArgs = encoding.args;
+
       const ffmpegInfo = await inspect(options.ffmpeg, process.env, { x264: 'libx264', 'nvenc-h264': 'h264_nvenc', 'nvenc-hevc': 'hevc_nvenc' }[encoding.encoder] ?? encoding.encoder);
       const ffmpeg = ffmpegInfo.path;
       options.transport = 'raw';
@@ -74,8 +113,7 @@ export async function renderShot(shot, options = {}) {
       options.alpha = events.options.alpha = capture.alpha;
       resolveFormat(options);
       Object.assign(encoding, videoEncoding(options));
-      videoArgs = encoding.args;
-      await loaded(events, capture, ffmpegInfo);
+
       const fps = number(options.fps ?? capture.fps, '--fps', { positive: true });
       const rate = frameRate(fps);
       const processed = createPostCapture(capture, options, fps);
@@ -87,57 +125,110 @@ export async function renderShot(shot, options = {}) {
       const total = end - first;
       if (!total) throw invalidOption('--from', 'Range contains no frames.');
       const { width, height } = capture;
-      events.progress('capture', 0, total);
+      directory = resume?.directory ?? path.join(events.directory, 'segments');
+      release ??= lockSegments(directory);
+      const info = await environment(capture.browser);
+      const currentEnvironment = { multiplane: version, chromium: info.chromium, raster: options.raster,
+        renderer: info.gpu.renderer, ffmpeg: ffmpegInfo.version, encoder: encoding.encoder };
+      const effective = { ...options, fps, from, to, out, ffmpeg, audio: options.audio ? path.resolve(options.audio) : undefined,
+        'motion-blur': processed.post.motionBlur, 'max-motion-blur': processed.post.maxMotionBlur,
+        shutter: processed.post.shutter, grain: processed.post.grain };
+      const savedOptions = persistedOptions(effective);
+      let manifest;
+      if (resume) {
+        manifest = resume.manifest;
+        checkEnvironment(manifest.environment, currentEnvironment);
+        if (manifest.environment && manifest.environment.renderer !== currentEnvironment.renderer) {
+          events.warning({ code: 'resume_renderer_changed', message: 'GPU renderer changed since the original render.',
+            details: { before: manifest.environment.renderer, after: currentEnvironment.renderer } });
+        }
+        await checkInputs(manifest);
+        manifest.segments = await reusableSegments(directory, manifest);
+        if (!manifest.environment) Object.assign(manifest, { environment: currentEnvironment, options: savedOptions,
+          first, end, total, segmentFrames: manifest.segmentFrames ?? Math.max(1, Math.round(fps * 10)) });
+      } else {
+        manifest = { schema: 'multiplane-segments/1', jobId: events.jobId, shot: path.resolve(options.root, shot),
+          options: savedOptions, environment: currentEnvironment, first, end, total,
+          segmentFrames: segmentFrames ?? Math.max(1, Math.round(fps * 10)), inputs: store.manifest.inputs, segments: [] };
+      }
+      if (!Number.isSafeInteger(manifest.segmentFrames) || manifest.segmentFrames < 1) throw invalidOption('_segmentFrames', 'Segment size must be a positive integer.');
+      store = manifestStore(directory, manifest);
+      for (const [file, record] of Object.entries(inputs)) store.input(file, record);
+      if (options.audio) await recordInput(path.resolve(options.audio));
+      store.save();
+      const framesReused = manifest.segments.reduce((sum, segment) => sum + segment.end - segment.first, 0);
+      const resumeData = resume ? { resumedFrom: resume.jobId, resume: { segmentsReused: manifest.segments.length, framesReused } } : {};
+      events.resumeData = resumeData;
+      if (resume) atomicJSON(path.join(events.directory, 'resume.json'), { directory });
+      await loaded(events, capture, ffmpegInfo);
+      events.progress('capture', framesReused, total);
       await capture.close(); capture = undefined;
       events.check();
-      const actualWorkers = Math.min(workers, Math.ceil(total / 4));
+      const actualWorkers = Math.min(workers, Math.max(1, Math.ceil((total - framesReused) / 4)));
       events.resources.setWorkers(actualWorkers);
       const started = performance.now();
       const frameHashes = process.env.RENDER_FRAME_HASHES ? [] : null;
+      options._recordInputs = true;
       pool = createRenderPool(shot, options, fps, actualWorkers, { width, height }, events.warning,
-        done => events.progress('capture', done, total));
+        done => events.progress('capture', done + framesReused, total), onInput);
       events.onCancel(() => pool?.cancel());
       await mkdir(path.dirname(out), { recursive: true });
-      events.check();
-      temporary = `${out}.${events.jobId}.partial.${options.format}`;
-      const audioArgs = options.audio
-        ? ['-i', path.resolve(options.audio), '-map', '0:v:0', '-map', '1:a:0', '-af', `atrim=start=${audioOffset + rate.seconds(first)},asetpts=PTS-STARTPTS,apad,atrim=duration=${rate.seconds(total)}`, ...encoding.audio]
-        : ['-an'];
-      // Supported since FFmpeg 5.1; older FFmpeg uses the global -vsync 0.
-      // Do not add output -r: passthrough must neither drop nor duplicate frames.
-      encoder = spawn(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', '-f', 'rawvideo', '-pixel_format', 'rgba', '-video_size', `${width * scale}x${height * scale}`, '-framerate', rate.argument, '-i', 'pipe:0', ...audioArgs, ...videoArgs, '-fps_mode', 'passthrough', '-pix_fmt', encoding.pixelFormat, ...encoding.mux, temporary], { windowsHide: true, stdio: ['pipe', 'ignore', 'pipe'] });
-      encoder.once('close', () => { encoderClosed = true; });
-      events.onCancel(() => stopChild(encoder));
-      let stderr = '', failure;
-      encoder.stderr.on('data', data => { stderr = (stderr + data).slice(-8000); });
-      encoder.stdin.on('error', error => { failure = error; });
-      const finished = new Promise((resolve, reject) => {
-        encoder.once('error', cause => reject(new MultiplaneError('encode_failed', undefined, { cause, details: { reason: cause.message } })));
-        encoder.once('close', code => code === 0 ? resolve() : reject(new MultiplaneError('encode_failed', undefined, { details: { exitCode: code, stderr } })));
-      });
-      finished.catch(error => { failure = error; });
+      temporary = out + '.' + events.jobId + '.partial.' + options.format;
       const alphaReferences = new Map();
-      let encoderWriteMs = 0, framesSent = 0;
-      // Internal switch for the pixel-equivalence and overhead tests, not a CLI option.
+      let encoderWriteMs = 0, framesSent = total, sealingFailure;
       const preview = createPreview(events, width * scale, height * scale, { enabled: options._preview !== false });
-      for await (const { frame, png } of pool.frames(first, end, async ({ frame, png }) => {
-        events.check();
-        await preview(png, frame);
-      })) {
-        events.check();
-        if (failure) throw new MultiplaneError('encode_failed', undefined, { cause: failure });
-        if (options.alpha && (framesSent === 0 || framesSent === Math.floor(total / 2))) alphaReferences.set(framesSent, Buffer.from(png.filter((_, i) => i % 4 === 3)));
-        frameHashes?.push({ frame, sha256: createHash('sha256').update(png).digest('hex') });
-        const writeStarted = performance.now();
-        await writeFrame(encoder.stdin, png).catch(cause => { throw new MultiplaneError('encode_failed', undefined, { cause, details: { reason: cause.message } }); });
-        encoderWriteMs += performance.now() - writeStarted;
-        framesSent++;
+      const remember = segment => {
+        frameHashes?.push(...(segment.frameHashes ?? []));
+        for (const [frame, bytes] of Object.entries(segment.alphaReferences ?? {})) alphaReferences.set(Number(frame), Buffer.from(bytes, 'base64'));
+      };
+      // Keep workers busy while the preceding encoder drains and seals.
+      const ranges = [];
+      for (let start = first, index = 0; start < end; start += manifest.segmentFrames, index++) {
+        const stop = Math.min(end, start + manifest.segmentFrames);
+        const reused = manifest.segments.find(item => item.first === start && item.end === stop);
+        if (reused) { remember(reused); continue; }
+        ranges.push({ first: start, end: stop, index });
+      }
+      for (let cursor = 0; cursor < ranges.length;) {
+        let last = cursor;
+        while (last + 1 < ranges.length && ranges[last].end === ranges[last + 1].first) last++;
+        let active, hashes, references, rangeIndex = cursor;
+        for await (const { frame, png } of pool.frames(ranges[cursor].first, ranges[last].end)) {
+          events.check();
+          if (sealingFailure) throw sealingFailure;
+          if (!active) {
+            active = segmentEncoder({ ffmpeg, directory, ...ranges[rangeIndex], width: width * scale, height: height * scale,
+              rate, encoding, format: options.format, events, store, hook });
+            encoders.add(active.child);
+            active.finished.finally(() => encoders.delete(active.child)).catch(() => {});
+            hashes = []; references = {};
+          }
+          await preview(png, frame);
+          const relative = frame - first;
+          if (options.alpha && (relative === 0 || relative === Math.floor(total / 2))) references[relative] = Buffer.from(png.filter((_, i) => i % 4 === 3)).toString('base64');
+          if (frameHashes) hashes.push({ frame, sha256: createHash('sha256').update(png).digest('hex') });
+          const writeStarted = performance.now();
+          await active.write(png);
+          encoderWriteMs += performance.now() - writeStarted;
+          if (frame + 1 === ranges[rangeIndex].end) {
+            const sealed = active.seal({ ...(frameHashes ? { frameHashes: hashes } : {}), ...(options.alpha ? { alphaReferences: references } : {}) }).then(remember);
+            sealed.catch(error => { sealingFailure ??= error; });
+            pending.push(sealed);
+            // Hooks model interruption at an exact durable boundary in tests.
+            if (hook) await sealed;
+            active = undefined; rangeIndex++;
+          }
+        }
+        cursor = last + 1;
       }
       const drainStarted = performance.now();
       events.progress('encode', total, total);
-      encoder.stdin.end();
-      await finished;
+      await Promise.all(pending);
+      // Finish all resource requests before the final input audit/publication.
+      await pool.close();
       events.check();
+      await checkInputs(manifest);
+      movedSource = await assembleSegments({ ffmpeg, directory, manifest, temporary, encoding, rate, audioOffset, events });
       const encoderDrainMs = performance.now() - drainStarted;
       const probeStarted = performance.now();
       const outputCheck = await checkVideo(ffmpeg, temporary, { frames: framesSent, durationSeconds: rate.seconds(framesSent), width: width * scale, height: height * scale, fps: rate.fps, ...(options.alpha ? { alpha: true, format: options.format } : {}) }, events, probe);
@@ -145,13 +236,18 @@ export async function renderShot(shot, options = {}) {
       const outputCheckMs = performance.now() - probeStarted;
       await publishVideo(temporary, out, options.overwrite);
       temporary = undefined;
+      // Invalidate the checkpoint while still holding the lock, so another
+      // resume cannot reuse a manifest whose output has already been published.
+      await rm(path.join(directory, 'manifest.json'), { force: true });
+      await rm(directory, { recursive: true, force: true });
+      release(); release = undefined;
       const elapsed = (performance.now() - started) / 1000;
-      if (frameHashes) await writeFile(process.env.RENDER_FRAME_HASHES, JSON.stringify(frameHashes, null, 2));
+      if (frameHashes) await writeFile(process.env.RENDER_FRAME_HASHES, JSON.stringify(frameHashes.sort((a, b) => a.frame - b.frame), null, 2));
       if (process.env.RENDER_PROFILE) await writeFile(process.env.RENDER_PROFILE, JSON.stringify({elapsed,frames:total,workers:actualWorkers,options,stats:pool.stats,encoderWriteMs,encoderDrainMs,outputCheckMs},null,2));
       events.artifact(out, 'video');
-      result = { staticReuse: pool.staticReuse, blurSamples: pool.blurSamples, dofSamples: pool.dofSamples, output: out, frames: framesSent, fps, from, to, width: width * scale, height: height * scale, encoder: encoding.encoder, format: options.format, alpha: options.alpha, post: { ...processed.post, adaptiveBlur: Number(options['adaptive-blur'] ?? 0.5) }, renderScale, scale, outputCheck };
+      result = { ...resumeData, staticReuse: pool.staticReuse, blurSamples: pool.blurSamples, dofSamples: pool.dofSamples, output: out, frames: framesSent, fps, from, to, width: width * scale, height: height * scale, encoder: encoding.encoder, format: options.format, alpha: options.alpha, post: { ...processed.post, adaptiveBlur: Number(options['adaptive-blur'] ?? 0.5) }, renderScale, scale, outputCheck };
     } finally { await cleanup(); }
 
     return options.draft ? { ...result, draft: true } : result;
-  });
+  }));
 }

package/src/resume.mjs

@@ -0,0 +1,23 @@
+import { renderShot } from './render.mjs';
+import { readStatus, resolveJob } from './jobs.mjs';
+import { readManifest, segmentDirectory, unavailable, checkInputs } from './segments.mjs';
+import { invalidOption } from './errors.mjs';
+import { loadUserConfig } from './user-home.mjs';
+
+export async function resumeRender(target, options = {}) {
+  const allowed = ['workers', 'json', 'job-dir', 'no-hosted', 'onEvent', '_hostedCLI', '_segmentHook', '_inspectFFmpeg', '_probeVideo', 'hosted-executor', 'job-dir-exact'];
+  for (const key of Object.keys(options)) if (!allowed.includes(key)) throw invalidOption('--' + key, 'This option cannot be changed when resuming.');
+  const configured = loadUserConfig('status', options);
+  const jobDir = resolveJob(target, configured.options);
+  const status = await readStatus(jobDir);
+  if (status.command !== 'render') throw unavailable('not_render');
+  if (status.state === 'succeeded') throw unavailable('succeeded');
+  if (!['failed', 'cancelled'].includes(status.state)) throw unavailable('running');
+  const directory = segmentDirectory(jobDir), manifest = readManifest(directory);
+  if (!manifest) throw unavailable('missing_manifest');
+  await checkInputs(manifest);
+  return renderShot(manifest.shot, { ...manifest.options, ...options,
+    _resume: { directory, jobId: status.jobId }, _effectiveOptions: true,
+    // Only hosting policy and job lookup use current configuration.
+    hosted: loadUserConfig('render', {}).options.hosted, 'no-hosted': options['no-hosted'] ?? false });
+}

package/src/segment-encoder.mjs

@@ -0,0 +1,91 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { rename, stat, writeFile, open } from 'node:fs/promises';
+import path from 'node:path';
+import { stopChild } from './process.mjs';
+import { writeFrame } from './video-pipe.mjs';
+import { MultiplaneError } from './errors.mjs';
+import { fileDigest } from './input-records.mjs';
+
+function childProcess(ffmpeg, args, events, input = false, onLine) {
+  events.check();
+  const child = spawn(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', ...args],
+    { windowsHide: true, stdio: [input ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+  let stderr = '', stdout = '', failure;
+  const unsubscribe = events.onCancel(() => stopChild(child));
+  child.stderr.on('data', bytes => { stderr = (stderr + bytes).slice(-8000); });
+  if (onLine) createInterface({ input: child.stdout, crlfDelay: Infinity }).on('line', onLine);
+  else child.stdout.on('data', bytes => { stdout = (stdout + bytes).slice(-8000); });
+  child.stdin?.on('error', error => { failure = error; });
+  const finished = new Promise((resolve, reject) => {
+    child.once('error', cause => reject(new MultiplaneError('encode_failed', undefined, { cause })));
+    child.once('close', code => {
+      unsubscribe();
+      if (code === 0) resolve(stdout);
+      else reject(new MultiplaneError('encode_failed', undefined, { details: { exitCode: code, stderr } }));
+    });
+  });
+  finished.catch(error => { failure = error; });
+  return { child, finished, async write(bytes) {
+    try {
+      if (failure) throw failure;
+      await writeFrame(child.stdin, bytes);
+    } catch (cause) {
+      throw cause instanceof MultiplaneError ? cause : new MultiplaneError('encode_failed', undefined,
+        { cause, details: { reason: cause.message } });
+    }
+  } };
+}
+
+export function segmentEncoder({ ffmpeg, directory, index, first, end, width, height, rate, encoding, format, events, store, hook }) {
+  const file = `segment-${String(index).padStart(6, '0')}.${format}`;
+  const temporary = path.join(directory, file + '.partial.' + format);
+  const encoder = childProcess(ffmpeg, ['-f', 'rawvideo', '-pixel_format', 'rgba', '-video_size', `${width}x${height}`,
+    '-framerate', rate.argument, '-i', 'pipe:0', '-an', ...encoding.args, '-fps_mode', 'passthrough',
+    '-pix_fmt', encoding.pixelFormat, ...encoding.mux, temporary], events, true);
+  return { ...encoder, async seal(extra = {}) {
+    encoder.child.stdin.end();
+    await encoder.finished;
+    events.check();
+    // Count copied video packets without decoding or relying on version-specific progress fields.
+    let frames = 0;
+    const probe = childProcess(ffmpeg, ['-i', temporary, '-map', '0:v:0', '-an', '-c', 'copy', '-f', 'framecrc', '-'], events, false, line => {
+      if (line.trim() && !line.trimStart().startsWith('#')) frames++;
+    });
+    await probe.finished;
+    if (!frames) throw new MultiplaneError('output_invalid', 'Segment frame count could not be read.', { details: { expected: end - first, frames: null } });
+    if (frames !== end - first) throw new MultiplaneError('output_invalid', 'Segment frame count differs.', { details: { expected: end - first, frames } });
+    const handle = await open(temporary, 'r+');
+    try { await handle.sync(); } finally { await handle.close(); }
+    await hook?.('beforeSeal', index);
+    await rename(temporary, path.join(directory, file));
+    const segment = { file, first, end, bytes: (await stat(path.join(directory, file))).size,
+      sha256: await fileDigest(path.join(directory, file)), ...extra };
+    store.manifest.segments = store.manifest.segments.filter(item => item.first !== first).concat(segment).sort((a, b) => a.first - b.first);
+    store.save();
+    await hook?.('sealed', index);
+    return segment;
+  } };
+}
+
+export async function assembleSegments({ ffmpeg, directory, manifest, temporary, encoding, rate, audioOffset, events }) {
+  const segments = [...manifest.segments].sort((a, b) => a.first - b.first);
+  const { options, first, total } = manifest;
+  if (segments.length === 1 && !options.audio) {
+    const source = path.join(directory, segments[0].file);
+    try { await rename(source, temporary); return source; }
+    catch (error) {
+      if (error.code !== 'EXDEV') throw error;
+      const { copyFile } = await import('node:fs/promises');
+      await copyFile(source, temporary);
+      return;
+    }
+  }
+  const list = path.join(directory, 'concat.txt');
+  // Relative generated names avoid quoting user paths in the concat language.
+  await writeFile(list, segments.map(segment => `file '${segment.file}'\nduration ${rate.seconds(segment.end - segment.first)}\n`).join(''));
+  const input = segments.length === 1 ? ['-i', path.join(directory, segments[0].file)] : ['-f', 'concat', '-safe', '1', '-i', list];
+  const audio = options.audio ? ['-i', options.audio, '-map', '0:v:0', '-map', '1:a:0', '-af',
+    `atrim=start=${audioOffset + rate.seconds(first)},asetpts=PTS-STARTPTS,apad,atrim=duration=${rate.seconds(total)}`, ...encoding.audio] : ['-map', '0:v:0', '-an'];
+  await childProcess(ffmpeg, [...input, ...audio, '-c:v', 'copy', ...encoding.mux, temporary], events).finished;
+}