@hyperframes/producer 0.8.181 → 0.8.183

package/dist/public-server.js

@@ -48,6 +48,8 @@ import {
   extractMediaMetadata as extractMediaMetadata4,
   resolveConfig as resolveConfig2,
   closeCaptureSession as closeCaptureSession8,
+  createCaptureSession as createCaptureSession8,
+  initializeSession as initializeSession8,
   createVideoFrameInjector,
   getEncoderPreset as getEncoderPreset3,
   distributeFrames as distributeFrames2,
@@ -1421,7 +1423,7 @@ function pidScope() {
   return {
     host: hostname(),
     // Without /proc (macOS, Windows) the boot time, to the minute, stands in for the boot id.
-    boot: attempt(() => readFileSync2("/proc/sys/kernel/random/boot_id", "utf-8").trim()) ?? String(Math.round(Date.now() / 6e4 - uptime() / 60)),
+    boot: attempt(() => readFileSync2("/proc/sys/kernel/random/boot_id", "utf-8").trim()) ?? attempt(() => String(Math.round(Date.now() / 6e4 - uptime() / 60))),
     pidns: attempt(() => readlinkSync("/proc/self/ns/pid"))
   };
 }
@@ -1439,9 +1441,14 @@ function alive(pid) {
     return error.code === "EPERM";
   }
 }
-function inThisPidScope(owner) {
+function knownPidScope() {
   const scope = pidScope();
-  return owner.host === scope.host && owner.boot === scope.boot && owner.pidns === scope.pidns;
+  const unknown = scope.boot === void 0 || process.platform === "linux" && scope.pidns === void 0;
+  return unknown ? void 0 : scope;
+}
+function inThisPidScope(owner) {
+  const scope = knownPidScope();
+  return scope !== void 0 && owner.host === scope.host && owner.boot === scope.boot && owner.pidns === scope.pidns;
 }
 function ownerState(dir) {
   let owner;
@@ -1506,7 +1513,9 @@ async function defaultArtifactDurationProbe(path) {
   const meta = await extractMediaMetadata(path);
   return {
     durationSeconds: meta.durationSeconds,
-    frames: meta.frames
+    frames: meta.frames,
+    width: meta.width,
+    height: meta.height
   };
 }
 function buildArtifactExpectation(input) {
@@ -1515,7 +1524,9 @@ function buildArtifactExpectation(input) {
   const expectation = {
     expectedDurationSeconds: input.durationSeconds,
     fps: input.fps,
-    expectedFrames: input.expectedFrames
+    expectedFrames: input.expectedFrames,
+    expectedWidth: input.width,
+    expectedHeight: input.height
   };
   if (input.outputFormat !== "hls") return expectation;
   return {
@@ -1583,6 +1594,16 @@ function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPa
     `Render artifact is truncated: expected ${expectedFrames} frames, probed ${probedFrames} frames (shortfall ${shortfall} frames). Artifact: ${stagingPath}`
   );
 }
+function assertSizeMatches(expected, probed, stagingPath) {
+  const { expectedWidth: width, expectedHeight: height } = expected;
+  if (width === void 0 || height === void 0) return;
+  if (probed.width === void 0 || probed.height === void 0) return;
+  const fits = (want, got) => got === want || got === want + want % 2;
+  if (fits(width, probed.width) && fits(height, probed.height)) return;
+  throw new Error(
+    `Render artifact has the wrong size: expected ${width}x${height}, probed ${probed.width}x${probed.height}. Artifact: ${stagingPath}`
+  );
+}
 var ArtifactTransaction = class {
   constructor(destinationPath, kind, fileSystem = defaultFileSystem, durationProbe = defaultArtifactDurationProbe) {
     this.kind = kind;
@@ -1653,6 +1674,7 @@ var ArtifactTransaction = class {
     if (expected.expectedFrames !== void 0) {
       assertFrameCountWithinTolerance(expected.expectedFrames, probed.frames, probePath);
     }
+    assertSizeMatches(expected, probed, probePath);
   }
   async runDurationProbe(probePath) {
     try {
@@ -3201,7 +3223,9 @@ function aggregateDrawElement(perfs, de) {
   if (perfs.length === 0) return void 0;
   const modes = [...new Set(perfs.map((p) => p.captureMode).filter(Boolean))].sort();
   const gateReasons = [
-    ...new Set(perfs.map((p) => p.deGateReason).filter((r) => !!r))
+    ...new Set(
+      [de.probeGateReason, ...perfs.map((p) => p.deGateReason)].filter((r) => !!r)
+    )
   ].sort();
   const gpuRenderers = [
     ...new Set(perfs.map((p) => p.gpuRenderer).filter((r) => !!r))
@@ -8665,6 +8689,7 @@ async function runAudioStage(input) {
     audios,
     masterFxChain,
     urlByAbsentLocalPath,
+    keepEncoderInputAt,
     abortSignal,
     assertNotAborted,
     log
@@ -8684,7 +8709,13 @@ async function runAudioStage(input) {
         audioOutputPath,
         duration,
         abortSignal,
-        { ffmpegProcessTimeout, audioGain, masterFxChain, urlByAbsentLocalPath },
+        {
+          ffmpegProcessTimeout,
+          audioGain,
+          masterFxChain,
+          urlByAbsentLocalPath,
+          keepEncoderInputAt
+        },
         compiledDir
       );
     } catch (err) {
@@ -8798,13 +8829,29 @@ function inspectDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, free
   }
   return { available: false, estimatedBytes, freeBytes };
 }
-function diskCaptureShortfallError(needBytes, freeBytes, framesDir, basis) {
+function diskCaptureRemedy(cfg, outputFormat, durationSeconds, workerCount) {
+  const oneWorker = explainStreamingEncodeGate(cfg, outputFormat, 1, durationSeconds);
+  if (workerCount > 1 && oneWorker.enabled) {
+    return `This render stores frames because it captures with ${workerCount} workers. Free up disk space, or re-run this render with --workers 1 to stream frames into the encoder instead. One worker is slower, so keep the default worker count for renders that fit on disk.`;
+  }
+  switch (oneWorker.reason) {
+    case "format_excluded":
+      return `${outputFormat} output stores every frame at any worker count. Free up disk space or render to mp4.`;
+    case "disabled_by_config":
+      return "PRODUCER_ENABLE_STREAMING_ENCODE=false sends every render to disk. Free up disk space or unset it.";
+    case "duration_cap":
+      return "The streaming duration cap (PRODUCER_STREAMING_ENCODE_DURATION_CAP_ENABLED=true) sends renders longer than PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS to disk at any worker count. Free up disk space, unset the cap, or use --low-memory-mode, which streams past it on one worker.";
+    default:
+      return "Free up disk space.";
+  }
+}
+function diskCaptureShortfallError(needBytes, freeBytes, framesDir, basis, remedy) {
   const basisNote = basis === "measured" ? ` (measured from the first ${DISK_PROJECTION_SAMPLE_FRAMES} frames)` : "";
   return new Error(
-    `Disk capture may need ~${(needBytes / 1e6).toFixed(1)} MB of temporary frame storage${basisNote}, but only ${(freeBytes / 1e6).toFixed(1)} MB is free at ${framesDir}. Disk capture stores every frame as an image file (JPEG, or PNG for alpha). mp4/mov renders stream instead: always at --workers 1, and multi-worker on Linux BeginFrame capture. This render landed on disk because the output is png-sequence or gif, because it is multi-worker screenshot capture (opt in with HF_CAPTURE_PARALLEL_STREAM=true), or because streaming was switched off: HF_CAPTURE_PARALLEL_STREAM=false, PRODUCER_ENABLE_STREAMING_ENCODE=false, or the duration cap (PRODUCER_STREAMING_ENCODE_DURATION_CAP_ENABLED=true) on a render longer than PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS. HDR and shader-transition renders never reach this check; they run their own compositor. Re-run with --workers 1, use --low-memory-mode, or free up disk space.`
+    `Disk capture may need ~${(needBytes / 1e6).toFixed(1)} MB of temporary frame storage${basisNote}, but only ${(freeBytes / 1e6).toFixed(1)} MB is free at ${framesDir}. Disk capture stores every frame as an image file (JPEG, or PNG for alpha). ${remedy}`
   );
 }
-function assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, freeDiskBytes) {
+function assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, remedy, freeDiskBytes) {
   const headroom = inspectDiskCaptureHeadroom(
     framesDir,
     totalFrames,
@@ -8816,7 +8863,8 @@ function assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, freeD
     headroom.estimatedBytes,
     headroom.freeBytes,
     framesDir,
-    "estimate"
+    "estimate",
+    remedy
   );
 }
 function measureCaptureFrameBytes(workDir, framesDir) {
@@ -8836,7 +8884,7 @@ function measureCaptureFrameBytes(workDir, framesDir) {
   return total;
 }
 function createDiskCaptureProjection(input) {
-  const { framesDir, totalFrames, measureBytes, freeDiskBytes = freeDiskBytesAt } = input;
+  const { framesDir, totalFrames, measureBytes, remedy, freeDiskBytes = freeDiskBytesAt } = input;
   let checked = false;
   return (capturedFrames) => {
     if (checked || capturedFrames < DISK_PROJECTION_SAMPLE_FRAMES) return;
@@ -8848,7 +8896,7 @@ function createDiskCaptureProjection(input) {
     if (remaining <= 0 || freeBytes === null) return;
     const needBytes = Math.ceil(measured / capturedFrames * remaining);
     if (needBytes > freeBytes * 0.9) {
-      throw diskCaptureShortfallError(needBytes, freeBytes, framesDir, "measured");
+      throw diskCaptureShortfallError(needBytes, freeBytes, framesDir, "measured", remedy);
     }
   };
 }
@@ -8890,11 +8938,13 @@ async function runCaptureStage(input) {
     }
   }
   const captureOptions = buildCaptureOptions();
-  assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions);
+  const remedy = diskCaptureRemedy(cfg, job.config.format ?? "mp4", job.duration ?? 0, workerCount);
+  assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, remedy);
   const checkDiskProjection = createDiskCaptureProjection({
     framesDir,
     totalFrames,
-    measureBytes: () => measureCaptureFrameBytes(workDir, framesDir)
+    measureBytes: () => measureCaptureFrameBytes(workDir, framesDir),
+    remedy
   });
   if (workerCount > 1) {
     const attempts = await executeDiskCaptureWithAdaptiveRetry({
@@ -10105,8 +10155,10 @@ function fpsToFfmpegArg2(fps) {
 }
 var KEEP_FILTER_GRAPH_WHEN_FRAMES_DROP_ALPHA = ["-reinit_filter", "0"];
 var WRITE_EVERY_FRAME_WHOLE = ["-gifflags", "0"];
+var FAIL_ON_UNREADABLE_FRAME_INSTEAD_OF_ENDING_THERE = ["-xerror"];
 function framesInput(input, fpsArg) {
   return [
+    ...FAIL_ON_UNREADABLE_FRAME_INSTEAD_OF_ENDING_THERE,
     "-framerate",
     fpsArg,
     ...KEEP_FILTER_GRAPH_WHEN_FRAMES_DROP_ALPHA,
@@ -10357,7 +10409,8 @@ import { dirname as dirname9, join as join25 } from "node:path";
 import {
   DEFAULT_CONFIG,
   describeFfmpegFailure as describeFfmpegFailure2,
-  extractAudioMetadata as extractAudioMetadata2,
+  encodeAac,
+  extractAudioMetadata as extractAudioMetadata3,
   getFfprobeBinary,
   ManagedChildProcess,
   runFfmpeg as runFfmpeg5,
@@ -10366,7 +10419,12 @@ import {
 import { redactKnownPaths, redactTelemetryString as redactTelemetryString3 } from "@hyperframes/core";
 
 // src/services/render/audioTruePeak.ts
-import { aacSegmentCount, describeFfmpegFailure, runFfmpeg as runFfmpeg4 } from "@hyperframes/engine";
+import {
+  aacSegmentCount,
+  describeFfmpegFailure,
+  extractAudioMetadata as extractAudioMetadata2,
+  runFfmpeg as runFfmpeg4
+} from "@hyperframes/engine";
 var toDbfs = (token) => token.toLowerCase() === "-inf" ? Number.NEGATIVE_INFINITY : Number(token);
 function checkedDbfs(value) {
   if (Number.isNaN(value) || value === Number.POSITIVE_INFINITY) {
@@ -10404,12 +10462,13 @@ async function scanTruePeak(audioPath, trim, timeoutMs, signal) {
   };
 }
 async function measureTruePeakDbfs(audioPath, options) {
-  const { timeoutMs, signal, segments } = options;
+  const { timeoutMs, signal } = options;
   const wholeFile = async () => (await scanTruePeak(audioPath, "", timeoutMs, signal)).peak;
+  const { durationSeconds, sampleRate } = await extractAudioMetadata2(audioPath, { signal });
   const block = 4800;
-  const count = segments?.sampleRate === 48e3 ? aacSegmentCount(segments.durationSeconds) : 1;
-  if (!segments || count === 1) return wholeFile();
-  const cut = (k) => k * Math.floor(segments.durationSeconds * 10 / count) * block;
+  const count = sampleRate === 48e3 && Number.isFinite(durationSeconds) ? aacSegmentCount(durationSeconds) : 1;
+  if (count === 1) return wholeFile();
+  const cut = (k) => k * Math.floor(durationSeconds * 10 / count) * block;
   const peers = new AbortController();
   const segmentSignal = signal ? AbortSignal.any([signal, peers.signal]) : peers.signal;
   const scans = await Promise.all(
@@ -10438,24 +10497,8 @@ var AUDIO_DURATION_TOLERANCE_SECONDS = 1e-3;
 var AAC_DELIVERY_TRUE_PEAK_DBFS = -1;
 var AAC_TRUE_PEAK_CORRECTION_HEADROOM_DB = 0.5;
 var MAX_TRUE_PEAK_CORRECTION_PASSES = 3;
-function buildAacTruePeakCorrectionArgs(inputPath, outputPath, targetDurationSeconds, attenuationDb) {
-  return [
-    "-i",
-    inputPath,
-    "-map",
-    "0:a:0",
-    "-vn",
-    "-af",
-    `volume=${attenuationDb.toFixed(3)}dB`,
-    "-t",
-    formatSeconds(targetDurationSeconds),
-    "-c:a",
-    "aac",
-    "-b:a",
-    "192k",
-    "-y",
-    outputPath
-  ];
+function aacTruePeakCorrectionFilter(targetDurationSeconds, attenuationDb) {
+  return `volume=${attenuationDb.toFixed(3)}dB,apad,atrim=0:${formatSeconds(targetDurationSeconds)}`;
 }
 function buildPadTrimAudioPlan(audioPath, outputPath, sourceDurationSeconds, targetDurationSeconds) {
   const delta = targetDurationSeconds - sourceDurationSeconds;
@@ -10470,53 +10513,13 @@ function buildPadTrimAudioPlan(audioPath, outputPath, sourceDurationSeconds, tar
   if (delta > 0) {
     return {
       operation: "pad",
-      steps: [
-        {
-          kind: "normalize",
-          args: [
-            "-i",
-            audioPath,
-            "-af",
-            `apad,atrim=0:${targetSec}`,
-            "-t",
-            targetSec,
-            "-c:a",
-            "aac",
-            "-b:a",
-            "192k",
-            "-y",
-            outputPath
-          ]
-        }
-      ],
+      steps: [{ kind: "normalize", filter: `apad,atrim=0:${targetSec}` }],
       cleanupPaths: []
     };
   }
   return {
     operation: "trim",
-    steps: [
-      {
-        kind: "trim",
-        args: [
-          "-i",
-          audioPath,
-          "-af",
-          `atrim=duration=${targetSec},asetpts=PTS-STARTPTS`,
-          // `atrim` limits decoded samples but does not cap muxer timestamps
-          // introduced by encoder delay/flush.  The output duration contract
-          // is enforced at the container boundary as well; without `-t`, a
-          // long primed source can retain its original tail after re-encode.
-          "-t",
-          targetSec,
-          "-c:a",
-          "aac",
-          "-b:a",
-          "192k",
-          "-y",
-          outputPath
-        ]
-      }
-    ],
+    steps: [{ kind: "trim", filter: `atrim=duration=${targetSec},asetpts=PTS-STARTPTS` }],
     cleanupPaths: []
   };
 }
@@ -10533,7 +10536,8 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   const probeAudio = input.probeAudioInfo ?? defaultProbeAudioInfo;
   const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
   const runner = input.runFfmpeg ?? ((args) => defaultRunFfmpeg(args, timeoutMs, input.signal));
-  const probeTruePeak = input.probeAudioTruePeakDbfs ?? (input.runFfmpeg ? void 0 : (audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal }));
+  const encode = input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal);
+  const probeTruePeak = input.probeAudioTruePeakDbfs ?? (input.runFfmpeg || input.encodeAac ? void 0 : (audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal }));
   const [videoResult, audioResult] = await Promise.allSettled([
     probeVideo(input.videoPath),
     probeAudio(input.audioPath, input.signal)
@@ -10580,7 +10584,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   );
   try {
     for (const step of plan.steps) {
-      const ffmpegResult = await runner(step.args);
+      const ffmpegResult = step.kind === "copy" ? await runner(step.args) : await encode(input.audioPath, input.outputPath, targetDurationSeconds, step.filter);
       if (!ffmpegResult.success) {
         return {
           success: false,
@@ -10612,7 +10616,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
       targetDurationSeconds,
       signal: input.signal,
       probeTruePeak,
-      runner
+      encode
     });
     if (!correction.success) {
       return {
@@ -10660,13 +10664,11 @@ async function enforceAacTruePeak(input) {
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
       attenuationDb += correctionTargetDbfs - truePeakDbfs;
-      const result = await input.runner(
-        buildAacTruePeakCorrectionArgs(
-          input.audioPath,
-          correctedPath,
-          input.targetDurationSeconds,
-          attenuationDb
-        )
+      const result = await input.encode(
+        input.audioPath,
+        correctedPath,
+        input.targetDurationSeconds,
+        aacTruePeakCorrectionFilter(input.targetDurationSeconds, attenuationDb)
       );
       if (!result.success) {
         return {
@@ -10761,7 +10763,7 @@ function parseFrameRate(rate) {
   return { fpsNum, fpsDen };
 }
 async function defaultProbeAudioInfo(audioPath, signal) {
-  const metadata = await extractAudioMetadata2(audioPath, { signal });
+  const metadata = await extractAudioMetadata3(audioPath, { signal });
   return {
     durationSeconds: metadata.durationSeconds,
     sampleRate: metadata.sampleRate,
@@ -10770,7 +10772,18 @@ async function defaultProbeAudioInfo(audioPath, signal) {
   };
 }
 async function defaultRunFfmpeg(args, timeoutMs, signal) {
-  const result = await runFfmpeg5(args, { signal, timeout: timeoutMs });
+  return toStepResult(await runFfmpeg5(args, { signal, timeout: timeoutMs }), timeoutMs);
+}
+function defaultAacEncoder(timeoutMs, signal, pcmSourcePath) {
+  return async (inputPath, outputPath, durationSeconds, filter) => {
+    const options = pcmSourcePath ? { signal, timeout: timeoutMs, filter } : { signal, timeout: timeoutMs, filter, segments: 1 };
+    return toStepResult(
+      await encodeAac(pcmSourcePath ?? inputPath, outputPath, durationSeconds, options),
+      timeoutMs
+    );
+  };
+}
+function toStepResult(result, timeoutMs) {
   if (result.success) return { success: true };
   return {
     success: false,
@@ -10958,7 +10971,7 @@ function assertOutputScaleSupported(deviceScaleFactor, route) {
   const reason = UNSUPPORTED_REASON2[route];
   if (reason === null) return;
   throw new Error(
-    `[Render] --resolution other than the composition's size is not supported on the "${route}" capture route: ${reason}. Render at the composition's size, or as mp4 with page-side compositing.`
+    `[Render] --resolution other than the composition's size is not supported on the "${route}" capture route: ${reason}. Render at the composition's size; or, for HDR footage, add --sdr to render this size in standard colour; or, for shader transitions, render as mp4.`
   );
 }
 
@@ -11175,7 +11188,7 @@ function getNextRetryWorkerCount(currentWorkers) {
   return Math.max(1, Math.floor(currentWorkers / 2));
 }
 function resolveRenderWorkDirPrefix(outputPath, jobId, platform2 = process.platform, systemTempDir = tmpdir2()) {
-  if (platform2 === "win32") return join26(systemTempDir, "hf-render-");
+  if (platform2 === "win32" || platform2 === "darwin") return join26(systemTempDir, "hf-render-");
   return join26(dirname10(outputPath), `work-${jobId}-`);
 }
 var MAX_TRANSIENT_CAPTURE_RETRIES = 1;
@@ -11669,6 +11682,9 @@ function resolveDeShortBand(args) {
 function shouldPreferSingleWorkerDrawElement(args) {
   return args.workerCount > 1 && typeof args.requestedWorkers !== "number" && args.useDrawElement && !args.deCompileGate && !args.forceScreenshot && outputUsesH264Pipeline(args.outputFormat) && args.minFrames > 0 && args.totalFrames >= args.minFrames && args.singleWorkerStreamingOk && !args.layeredOrEffectRoute && !args.supersampling && !args.probeDeGated && !args.experimentalParallelDeOptIn;
 }
+function isProbeDeGated(session) {
+  return session !== null && session.captureMode !== "drawelement" && !session.deInitDeferred;
+}
 function resolveInversionRetryPlan(args) {
   if (args.deWorkerInversion !== "inverted") return null;
   const workerCount = args.isMemoryExhaustion ? 1 : args.preInversionWorkerCount;
@@ -11750,7 +11766,8 @@ async function closeOrphanedProbeForRetry(probe, closer, log, retryContext) {
 }
 function resolveParallelCaptureMode(args) {
   const supersampling = (args.deviceScaleFactor ?? 1) !== 1;
-  return args.headlessShell && args.platform === "linux" && !args.forceScreenshot && !supersampling ? "beginframe" : "screenshot";
+  const headlessShell = args.headlessShellPath !== void 0;
+  return headlessShell && args.platform === "linux" && !args.forceScreenshot && !supersampling ? "beginframe" : "screenshot";
 }
 function isCaptureParallelStreamRouterEnabled(env, resolvedMode) {
   const raw = env.HF_CAPTURE_PARALLEL_STREAM?.trim().toLowerCase();
@@ -12358,6 +12375,7 @@ async function executeRenderPipeline(input) {
     );
     const nativeHdrIds = /* @__PURE__ */ new Set([...nativeHdrVideoIds, ...nativeHdrImageIds]);
     const hasHdrContent = Boolean(effectiveHdr && nativeHdrIds.size > 0);
+    if (hasHdrContent) assertOutputScaleSupported(deviceScaleFactor, "hdr_layered");
     const deSingleMinFramesRaw = process.env.HF_DE_SINGLE_MIN_FRAMES;
     const deSingleMinFramesNum = deSingleMinFramesRaw === void 0 || deSingleMinFramesRaw.trim() === "" ? 900 : Number(deSingleMinFramesRaw);
     const deSingleMinFrames = Number.isFinite(deSingleMinFramesNum) ? deSingleMinFramesNum : 900;
@@ -12398,7 +12416,7 @@ async function executeRenderPipeline(input) {
       singleWorkerStreamingOk: shouldUseStreamingEncode(cfg, outputFormat, 1, job.duration),
       layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
       supersampling: deviceScaleFactor !== 1,
-      probeDeGated: probeSession !== null && probeSession.captureMode !== "drawelement" && !probeSession.deInitDeferred,
+      probeDeGated: isProbeDeGated(probeSession),
       experimentalParallelDeOptIn: process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" || // Verified parallel DE streaming (opt-in) wants its parallelism kept.
       process.env.HF_DE_PARALLEL_STREAM === "true"
     };
@@ -12407,14 +12425,14 @@ async function executeRenderPipeline(input) {
       ...deInversionArgs,
       minFrames: Math.min(deSingleMinFrames, deShortBandMinFrames)
     });
-    const deShortBand = resolveDeShortBand({
+    let deShortBand = resolveDeShortBand({
       invertAtBaseFloor,
       invertAtBandFloor,
       bandEnabled: deShortBandEnabled,
       bandOpen: deShortBandOpen,
       elementCountSource: compositionElementCountSource
     });
-    const deInversionEligible = deShortBandRoute && deShortBand === "applied" ? invertAtBandFloor : invertAtBaseFloor;
+    let deInversionEligible = deShortBandRoute && deShortBand === "applied" ? invertAtBandFloor : invertAtBaseFloor;
     const deInversionEffectiveMinFrames = deShortBandRoute && deShortBand === "applied" ? Math.min(deSingleMinFrames, deShortBandMinFrames) : deSingleMinFrames;
     const deParallelRouterEnabled = isDeParallelRouterEnabled(process.env);
     const deParallelMinFramesRaw = process.env.HF_DE_PARALLEL_MIN_FRAMES;
@@ -12423,7 +12441,7 @@ async function executeRenderPipeline(input) {
     const deParallelMinMemRaw = process.env.HF_DE_PARALLEL_MIN_MEM_MB;
     const deParallelMinMemNum = deParallelMinMemRaw === void 0 || deParallelMinMemRaw.trim() === "" ? 24576 : Number(deParallelMinMemRaw);
     const deParallelMinMemoryMb = Number.isFinite(deParallelMinMemNum) ? deParallelMinMemNum : 24576;
-    const deParallelRouterEligible = shouldPreferParallelDrawElement({
+    let deParallelRouterEligible = shouldPreferParallelDrawElement({
       workerCount: WOULD_RESOLVE_MULTI_WORKER,
       requestedWorkers: job.config.workers,
       useDrawElement: cfg.useDrawElement,
@@ -12434,7 +12452,7 @@ async function executeRenderPipeline(input) {
       minFrames: deParallelMinFrames,
       layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
       supersampling: deviceScaleFactor !== 1,
-      probeDeGated: probeSession !== null && probeSession.captureMode !== "drawelement" && !probeSession.deInitDeferred,
+      probeDeGated: isProbeDeGated(probeSession),
       experimentalParallelDeOptIn: process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" || process.env.HF_DE_PARALLEL_STREAM === "true",
       routerEnabled: deParallelRouterEnabled,
       // Router pins 3 workers for the streaming path; don't pin when a
@@ -12450,6 +12468,35 @@ async function executeRenderPipeline(input) {
       totalMemoryMb: Math.round(totalmem2() / (1024 * 1024)),
       minMemoryMb: deParallelMinMemoryMb
     });
+    if (probeSession === null && (deInversionEligible || deParallelRouterEligible)) {
+      try {
+        probeSession = await createCaptureSession8(
+          activeFileServer.url,
+          framesDir,
+          buildCaptureOptions(),
+          null,
+          { ...cfg, forceScreenshot: captureForceScreenshot }
+        );
+        await initializeSession8(probeSession);
+      } catch (error) {
+        assertNotAborted();
+        if (probeSession) {
+          lastBrowserConsole = probeSession.browserConsoleBuffer;
+          await closeCaptureSession8(probeSession).catch(() => {
+          });
+          probeSession = null;
+        }
+        log.warn("[Render] Fast capture gate check failed; routing without it.", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+      if (isProbeDeGated(probeSession)) {
+        deInversionEligible = false;
+        deParallelRouterEligible = false;
+        deShortBand = void 0;
+      }
+    }
+    const deProbeGateReason = isProbeDeGated(probeSession) ? probeSession.deGateReason : void 0;
     let workerCount;
     const captureStageObservationData = (extra = {}) => ({
       stagePhase: "capturing",
@@ -12637,7 +12684,7 @@ async function executeRenderPipeline(input) {
     }
     const parallelCaptureMode = resolveParallelCaptureMode({
       platform: process.platform,
-      headlessShell: resolveHeadlessShellPath(cfg) !== null,
+      headlessShellPath: resolveHeadlessShellPath(cfg),
       forceScreenshot: captureForceScreenshot,
       deviceScaleFactor: captureOptions.deviceScaleFactor
     });
@@ -13409,7 +13456,9 @@ async function executeRenderPipeline(input) {
         outputFormat,
         durationSeconds: job.duration,
         fps: fpsToNumber9(job.config.fps),
-        expectedFrames: captureTotalFrames
+        expectedFrames: captureTotalFrames,
+        width: outputWidth,
+        height: outputHeight
       })
     );
     const totalElapsed = Date.now() - pipelineStart;
@@ -13445,6 +13494,7 @@ async function executeRenderPipeline(input) {
       drawElement: {
         compileGate: deCompileGate,
         clampReason: deClampReason,
+        probeGateReason: deProbeGateReason,
         workerInversion: deWorkerInversion,
         preInversionWorkers: deWorkerInversion ? preRoutingWorkerCount : void 0,
         compositionElementCount,
@@ -13846,9 +13896,9 @@ import {
 // src/services/distributed/planFrameCost.ts
 import {
   closeCaptureSession as closeCaptureSession9,
-  createCaptureSession as createCaptureSession8,
+  createCaptureSession as createCaptureSession9,
   createFrameLookupTable as createFrameLookupTable3,
-  initializeSession as initializeSession8
+  initializeSession as initializeSession9
 } from "@hyperframes/engine";
 
 // src/services/distributed/chunkFrames.ts

package/dist/services/distributed/assemble.d.ts

@@ -68,6 +68,7 @@ export declare function assemble(planDir: string, chunkOutputs: AssembleChunkPat
      */
     cfr?: boolean;
 }): Promise<AssembleResult>;
-/** Chunks that carry their audio are stitched under one index, the same bytes as the S3 stitch. */
+/** Chunks carrying audio, or with it as a separate file, stitch under one index like S3's. */
 export declare function chunksAreStitchedMp4(planDir: string, cfr: boolean): boolean;
+export declare function stitchesSeparateAudio(planDir: string): boolean;
 export {};

package/dist/services/distributed/chunkFrames.d.ts

@@ -1,4 +1,4 @@
-import { type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, type EngineConfig, type ExtractedFrames, type FrameLookupTable } from "@hyperframes/engine";
+import { type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, type EngineConfig, type ExtractedFrames, type FrameLookupTable, type ShownBox } from "@hyperframes/engine";
 import type { LockedRenderConfig } from "../render/stages/freezePlan.js";
 import type { PlanV2RemoteSources } from "./planV2.js";
 import { type DistributedFormat, INVALID_VIDEO_METADATA, type PlanVideosJson } from "./shared.js";
@@ -39,6 +39,10 @@ export declare function buildChunkCaptureOptions(input: {
     videoMetadataHints?: CaptureOptions["videoMetadataHints"];
 }): CaptureOptions;
 /** Extracts the given frames of deferred videos under the names a full extraction gives them. */
+export declare function shownDeferredFrameIndexes(planVideos: PlanVideosJson, frames: Iterable<number>, fps: {
+    num: number;
+    den: number;
+}): Map<string, Set<number>>;
 export declare function extractDeferredVideoFramesForChunk(input: {
     planDir: string;
     planVideos: PlanVideosJson;
@@ -50,4 +54,5 @@ export declare function extractDeferredVideoFramesForChunk(input: {
     outputRoot: string;
     cfg: Pick<EngineConfig, "ffmpegProcessTimeout">;
     remoteSources?: PlanV2RemoteSources;
+    shownBoxes?: ReadonlyMap<string, ShownBox>;
 }): Promise<ExtractedFrames[]>;

package/dist/services/distributed/mp4Stitch.d.ts

@@ -31,9 +31,9 @@ export interface TrackTable {
 }
 /** Each track's sample tables, expanded to one entry per sample (and per chunk). */
 export declare function readTracks(moov: Buffer): TrackTable[];
-export declare function buildStitchedHeader(layouts: readonly Mp4Layout[]): Buffer;
+export declare function buildStitchedHeader(layouts: readonly Mp4Layout[], audio?: Mp4Layout): Buffer;
 export declare function fileRange(path: string): ReadRange;
-/** Local join: the stitched header, then each chunk's mdat payload in order. Like the ffmpeg
- * join, it writes in a work folder beside `outputPath` and renames only a finished file there. */
-export declare function writeStitchedMp4(chunkPaths: readonly string[], outputPath: string): Promise<void>;
+/** Local join: the header, then `audioPath`'s and each chunk's payload. Like the ffmpeg join, it
+ * writes in a work folder beside `outputPath` and renames only a finished file there. */
+export declare function writeStitchedMp4(chunkPaths: readonly string[], outputPath: string, audioPath?: string): Promise<void>;
 export {};

package/dist/services/distributed/plan.d.ts

@@ -211,6 +211,8 @@ export interface BuildLocalExecutionPlanOptions {
     readonly chunksCarryAudio?: boolean;
     /** With `chunksCarryAudio`, also write each chunk's audio packets to their own file. Plan v2 only. */
     readonly sliceChunkAudio?: boolean;
+    /** Leave the audio to {@link buildPlanAudio}; chunks render video only. mp4 without `cfr` only. */
+    readonly deferAudio?: boolean;
 }
 export interface RemoteProjectFile {
     readonly url: string;
@@ -401,7 +403,16 @@ export declare function resolveDistributedEngineConfig(config: DistributedRender
  * Build the shared local execution representation used by both transport
  * protocols. See the module docstring for the directory layout.
  */
+/** Whether the plan leaves its audio to {@link buildPlanAudio}. */
+export declare function plansSeparateAudio(config: Pick<DistributedRenderConfig, "format" | "cfr">, options: Pick<BuildLocalExecutionPlanOptions, "deferAudio">): boolean;
 export declare function buildLocalExecutionPlan(projectDir: string, config: DistributedRenderConfig, executionPlanDir: string, options?: Readonly<BuildLocalExecutionPlanOptions>): Promise<LocalExecutionPlan>;
+/**
+ * The audio of a plan made with `deferAudio`: the mix and true-peak hold that plan would have
+ * made, written to `outputPath` (on `workRoot`'s filesystem) at exactly the video's length.
+ */
+export declare function buildPlanAudio(projectDir: string, config: DistributedRenderConfig, workRoot: string, outputPath: string, options?: Pick<BuildLocalExecutionPlanOptions, "remoteFiles">): Promise<{
+    hasAudio: boolean;
+}>;
 /**
  * Legacy v1 transport wrapper around {@link buildLocalExecutionPlan}.
  *

package/dist/services/distributed/planV2.d.ts

@@ -91,6 +91,7 @@ export interface PlanV2WithPublisherOptions {
     /** See {@link BuildLocalExecutionPlanOptions.remoteFiles}; needs a publisher with `referenceStoredBlob`. */
     readonly remoteFiles?: BuildLocalExecutionPlanOptions["remoteFiles"];
     readonly chunksCarryAudio?: boolean;
+    readonly deferAudio?: boolean;
 }
 export interface PlanV2MaterializationResult {
     readonly planDir: string;

package/dist/services/distributed/projectHash.d.ts

@@ -22,9 +22,6 @@ export declare function listSiteFiles(projectDir: string): string[];
  * same-bytes rename still yields a fresh id. We trim to 16 chars because the
  * full 64 isn't useful in an object key for legibility. Pass `files` when the
  * caller already listed them, so the hashed set is the shipped set.
- *
- * Reads are synchronous: project trees are typically tens of MB at most
- * (HTML/CSS/JS plus a few composition assets), so the simpler shape wins over
- * a streaming pipeline.
+ * Files are read in fixed-size chunks, so no file is ever held whole in memory.
  */
 export declare function hashProjectDir(projectDir: string, files?: readonly string[]): string;