@hyperframes/producer 0.8.183 → 0.8.185

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export { type BrowserDiagnosticSummary, type RenderCaptureObservability, type Re
 export { localizeRemoteMediaSources, localizeRemoteImageSources, localizeRemoteFontFaces, } from "./services/htmlCompiler.js";
 export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, getCompositionDuration, getCapturePerfSummary, isTransientBrowserError, prepareCaptureSessionForReuse, type CaptureOptions, type CaptureSession, type CaptureResult, type CapturePerfSummary, type BeforeCaptureHook, } from "./services/frameCapture.js";
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
+export { prepareAnimatedGifInputs } from "./services/animatedGifPrep.js";
 export { createVideoFrameInjector } from "@hyperframes/engine";
 export { resolveConfig, DEFAULT_CONFIG, type ProducerConfig } from "./config.js";
 export { type ProducerLogger, type LogLevel, createConsoleLogger, defaultLogger, } from "./logger.js";

package/dist/index.js

@@ -8982,6 +8982,7 @@ async function runCaptureStage(input) {
           if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
           return;
         }
+        if (progress.landedFrame) input.onFrameLanded?.(progress.landedFrame);
         job.framesRendered = progress.capturedFrames;
         checkDiskProjection(progress.capturedFrames);
         const frameProgress = progress.capturedFrames / progress.totalFrames;
@@ -10151,6 +10152,7 @@ import {
   statSync as statSync5,
   writeFileSync as writeFileSync4
 } from "node:fs";
+import { readFile as readFile2 } from "node:fs/promises";
 import { dirname as dirname8, join as join24 } from "node:path";
 import {
   encodeFramesChunkedConcat,
@@ -10158,7 +10160,8 @@ import {
   formatFfmpegError,
   MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME2,
   resolveConfig,
-  runFfmpeg as runFfmpeg3
+  runFfmpeg as runFfmpeg3,
+  spawnStreamingEncoder as spawnStreamingEncoder4
 } from "@hyperframes/engine";
 import {
   clearGifFramesBeforeNext,
@@ -10295,6 +10298,124 @@ function startEncodeProgress(job, stage, onProgress) {
   });
   return (frames = total) => reportEncodeProgress(job, frames, total, onProgress, 75);
 }
+function resolveEngineConfig(input) {
+  return input.engineConfig ?? input.job.config.producerConfig ?? resolveConfig();
+}
+function videoEncoderOptions(input, engineCfg) {
+  const { job, preset } = input;
+  return {
+    fps: job.config.fps,
+    width: input.width,
+    height: input.height,
+    codec: preset.codec,
+    preset: preset.preset,
+    quality: input.effectiveQuality,
+    bitrate: input.effectiveBitrate,
+    pixelFormat: preset.pixelFormat,
+    vp9CpuUsed: engineCfg.vp9CpuUsed,
+    useGpu: job.config.useGpu,
+    hdr: preset.hdr,
+    // Distributed chunk renders pass these so the encoder writes closed-GOP
+    // keyframes that survive `-f concat -c copy` at assemble time. In-process
+    // renders leave both undefined → preserves the existing open-GOP output.
+    lockGopForChunkConcat: input.lockGopForChunkConcat === true,
+    gopSize: input.gopSize
+  };
+}
+function canEncodeWhileCapturing(input, workerCount, cpuCount) {
+  return workerCount > 1 && workerCount < cpuCount && !input.isPngSequence && !input.isGif && !input.enableChunkedEncode && input.preset.codec === "h264" && !input.preset.hdr && input.job.config.useGpu !== true && input.captureImageFormat === "jpeg" && input.lockGopForChunkConcat !== true;
+}
+async function readLandedFrame(workerPath, mergedPath) {
+  if (workerPath !== void 0) {
+    try {
+      return await readFile2(workerPath);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+  return readFile2(mergedPath);
+}
+function encodeWhileCapturing(input, totalFrames) {
+  const engineCfg = resolveEngineConfig(input);
+  const stop = new AbortController();
+  const signal = input.abortSignal ? AbortSignal.any([input.abortSignal, stop.signal]) : stop.signal;
+  const landed = /* @__PURE__ */ new Map();
+  let captureDone = false;
+  let framesFed = 0;
+  let wake = null;
+  const nudge = () => {
+    wake?.();
+    wake = null;
+  };
+  signal.addEventListener("abort", nudge, { once: true });
+  let reportFed = null;
+  const encoder = spawnStreamingEncoder4(
+    input.videoOnlyPath,
+    { ...videoEncoderOptions(input, engineCfg), imageFormat: "jpeg" },
+    signal,
+    engineCfg
+  );
+  const fed = (async () => {
+    const stream = await encoder;
+    for (let next = 0; next < totalFrames; next++) {
+      while (!landed.has(next) && !captureDone && !signal.aborted) {
+        await new Promise((resolve12) => wake = resolve12);
+      }
+      if (signal.aborted) return;
+      const mergedPath = join24(input.framesDir, formatCaptureFrameName(next, "jpg"));
+      const frame = await readLandedFrame(landed.get(next), mergedPath);
+      landed.delete(next);
+      if (!await stream.writeFrame(frame)) {
+        throw new Error(stream.getExitError() ?? "encoder exited before the last frame");
+      }
+      framesFed++;
+      reportFed?.(framesFed);
+    }
+  })().then(
+    () => void 0,
+    (error) => error ?? new Error("encode failed")
+  );
+  const closeEncoder = async () => (await encoder.catch(() => null))?.close();
+  return {
+    onFrameLanded: (frame) => {
+      landed.set(frame.index, frame.path);
+      nudge();
+    },
+    finish: async () => {
+      const start = Date.now();
+      captureDone = true;
+      input.log.info("[Render] Encoded frames while capturing", {
+        framesFed,
+        totalFrames
+      });
+      const encoded = startEncodeProgress(input.job, "Encoding video", input.onProgress);
+      reportFed = encoded;
+      nudge();
+      const failure = await fed;
+      const result = await closeEncoder();
+      input.assertNotAborted();
+      if (failure === void 0 && result?.success) {
+        encoded();
+        return { encodeMs: Date.now() - start };
+      }
+      input.log.warn(
+        "[Render] Encoding while capturing failed; encoding the frames after capture",
+        {
+          error: String(failure ?? result?.error)
+        }
+      );
+      return runEncodeStage(input);
+    },
+    abort: async () => {
+      stop.abort();
+      await fed;
+      await closeEncoder();
+    },
+    get framesFed() {
+      return framesFed;
+    }
+  };
+}
 async function runEncodeStage(input) {
   const {
     job,
@@ -10302,16 +10423,11 @@ async function runEncodeStage(input) {
     outputPath,
     framesDir,
     videoOnlyPath,
-    width,
-    height,
     needsAlpha,
     hasAudio,
     audioOutputPath,
     isPngSequence,
     isGif,
-    preset,
-    effectiveQuality,
-    effectiveBitrate,
     enableChunkedEncode,
     chunkedEncodeSize,
     abortSignal,
@@ -10341,7 +10457,7 @@ async function runEncodeStage(input) {
     encoded();
     return { encodeMs: Date.now() - stage5Start };
   }
-  const engineCfg = input.engineConfig ?? job.config.producerConfig ?? resolveConfig();
+  const engineCfg = resolveEngineConfig(input);
   if (isGif) {
     const encoded = startEncodeProgress(job, "Encoding GIF", onProgress);
     if (hasAudio) {
@@ -10371,24 +10487,7 @@ async function runEncodeStage(input) {
   const videoEngineCfg = scaledEncodeTimeout > engineCfg.ffmpegEncodeTimeout ? { ...engineCfg, ffmpegEncodeTimeout: scaledEncodeTimeout } : engineCfg;
   const frameExt = frameFileExtension2(input.captureImageFormat);
   const framePattern = `frame_%06d.${frameExt}`;
-  const encoderOpts = {
-    fps: job.config.fps,
-    width,
-    height,
-    codec: preset.codec,
-    preset: preset.preset,
-    quality: effectiveQuality,
-    bitrate: effectiveBitrate,
-    pixelFormat: preset.pixelFormat,
-    vp9CpuUsed: engineCfg.vp9CpuUsed,
-    useGpu: job.config.useGpu,
-    hdr: preset.hdr,
-    // Distributed chunk renders pass these so the encoder writes closed-GOP
-    // keyframes that survive `-f concat -c copy` at assemble time. In-process
-    // renders leave both undefined → preserves the existing open-GOP output.
-    lockGopForChunkConcat: input.lockGopForChunkConcat === true,
-    gopSize: input.gopSize
-  };
+  const encoderOpts = videoEncoderOptions(input, engineCfg);
   const encodeResult = enableChunkedEncode ? await encodeFramesChunkedConcat(
     framesDir,
     framePattern,
@@ -10672,7 +10771,6 @@ async function enforceAacTruePeak(input) {
   try {
     scratchDir = mkdtempSync3(join25(dirname9(input.audioPath), ".true-peak-"));
     const correctedPath = join25(scratchDir, "audio.m4a");
-    const correctionTargetDbfs = AAC_DELIVERY_TRUE_PEAK_DBFS - AAC_TRUE_PEAK_CORRECTION_HEADROOM_DB;
     const measurements = [];
     let attenuationDb = 0;
     let measuredPath = input.audioPath;
@@ -10690,7 +10788,8 @@ async function enforceAacTruePeak(input) {
         return { success: true, loweredDb: Number((-attenuationDb).toFixed(2)) };
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
-      attenuationDb += correctionTargetDbfs - truePeakDbfs;
+      const headroomDb = AAC_TRUE_PEAK_CORRECTION_HEADROOM_DB * 2 ** pass;
+      attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - headroomDb - truePeakDbfs;
       const result = await input.encode(
         input.audioPath,
         correctedPath,
@@ -13313,6 +13412,34 @@ async function executeRenderPipeline(input) {
           throw new Error(`Disk capture requires sdr_disk plan; got ${capturePlan.kind}`);
         }
         resetCaptureAttemptProgress(job);
+        const encodeInput = {
+          job,
+          log,
+          outputPath: stagedOutputPath,
+          framesDir,
+          videoOnlyPath,
+          width,
+          height,
+          needsAlpha,
+          captureImageFormat: captureOptions.format ?? "jpeg",
+          hasAudio,
+          audioOutputPath,
+          isPngSequence,
+          isGif,
+          preset,
+          effectiveQuality,
+          effectiveBitrate,
+          enableChunkedEncode,
+          chunkedEncodeSize,
+          engineConfig: cfg,
+          // Same value the streaming encoder above spreads — the disk and
+          // chunked-concat encoders need an identical GOP lock for HLS.
+          ...hlsEncoderGopLock,
+          abortSignal: executionSignal,
+          assertNotAborted,
+          onProgress
+        };
+        const overlap = !cfg.useDrawElement && workerSizing !== void 0 && canEncodeWhileCapturing(encodeInput, capturePlan.workerCount, workerSizing.cpuCount) ? encodeWhileCapturing(encodeInput, totalFrames) : null;
         const captureFrameStart = Date.now();
         const invokeDiskCapture = (diskPlan) => observeRenderStage(
           observability,
@@ -13334,13 +13461,15 @@ async function executeRenderPipeline(input) {
             createRenderVideoFrameInjector,
             abortSignal: executionSignal,
             assertNotAborted,
-            onProgress
+            onProgress,
+            onFrameLanded: (frame) => overlap?.onFrameLanded(frame)
           })
         );
         let captureRes;
         try {
           captureRes = await invokeDiskCapture(capturePlan);
         } catch (err) {
+          await overlap?.abort();
           if (!isDrawElementVerificationError(err) && !isDrawElementCaptureError(err) || err instanceof RenderCancelledError || executionSignal?.aborted === true) {
             throw err;
           }
@@ -13409,33 +13538,7 @@ async function executeRenderPipeline(input) {
             isGif,
             chunkedEncode: enableChunkedEncode
           }),
-          () => runEncodeStage({
-            job,
-            log,
-            outputPath: stagedOutputPath,
-            framesDir,
-            videoOnlyPath,
-            width,
-            height,
-            needsAlpha,
-            captureImageFormat: captureOptions.format ?? "jpeg",
-            hasAudio,
-            audioOutputPath,
-            isPngSequence,
-            isGif,
-            preset,
-            effectiveQuality,
-            effectiveBitrate,
-            enableChunkedEncode,
-            chunkedEncodeSize,
-            engineConfig: cfg,
-            // Same value the streaming encoder above spreads — the disk and
-            // chunked-concat encoders need an identical GOP lock for HLS.
-            ...hlsEncoderGopLock,
-            abortSignal: executionSignal,
-            assertNotAborted,
-            onProgress
-          })
+          () => overlap ? overlap.finish() : runEncodeStage(encodeInput)
         );
         perfStages.encodeMs = encodeRes.encodeMs;
       }
@@ -14042,7 +14145,14 @@ var RenderChunkValidationError = class extends Error {
   }
 };
 function createChunkVideoFrameInjectorFactory(frameLookup) {
-  return () => createVideoFrameInjector2(frameLookup);
+  if (!(frameLookup instanceof Promise)) return () => createVideoFrameInjector2(frameLookup);
+  return () => {
+    let hook;
+    return async (page, time, heldVideoTime) => {
+      hook ??= createVideoFrameInjector2(await frameLookup);
+      await hook?.(page, time, heldVideoTime);
+    };
+  };
 }
 function frameNumberFromFileName(name) {
   const match = /(\d+)(?=\.[^.]+$)/.exec(name);
@@ -17063,9 +17173,6 @@ function validateOutputResolutionOverride(body) {
   if (body.outputResolution.trim().length > 0 && normalized === void 0) {
     return `Invalid outputResolution "${body.outputResolution}". Must be one of: landscape, portrait, landscape-4k, portrait-4k, square, square-4k (aliases: 1080p, 4k, \u2026).`;
   }
-  if (normalized !== void 0 && (body.format === "webm" || body.format === "mov")) {
-    return `outputResolution is not supported with format "${body.format}": the alpha (webm/mov) capture path can't supersample. Use format "mp4", or omit outputResolution to render at the composition's native dimensions.`;
-  }
   return void 0;
 }
 function prepareProjectDirectory(projectDir, options) {
@@ -18794,6 +18901,12 @@ function validatePlanVideosForChunk(value) {
     );
   }
 }
+var MIN_FRAMES_PER_CHUNK_BROWSER = 20;
+function resolveChunkCaptureWorkers(framesInChunk, machineSized, maxCaptureWorkers) {
+  if (maxCaptureWorkers === void 0) return machineSized;
+  const byFrames = Math.floor(framesInChunk / MIN_FRAMES_PER_CHUNK_BROWSER);
+  return Math.max(machineSized, Math.floor(Math.min(maxCaptureWorkers, byFrames)));
+}
 function resolveChunkFrameRange(slice, chunkIndex, frameRange) {
   if (frameRange === void 0) return { startFrame: slice.startFrame, endFrame: slice.endFrame };
   const { startFrame, endFrame } = frameRange;
@@ -19030,7 +19143,11 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
         deferredVideos.filter((video) => remoteVideoIds.has(video.videoId))
       )
     });
-    const chunkWorkerCount = calculateOptimalWorkers2(framesInChunk, void 0, cfg);
+    const chunkWorkerCount = resolveChunkCaptureWorkers(
+      framesInChunk,
+      calculateOptimalWorkers2(framesInChunk, void 0, cfg),
+      options?.maxCaptureWorkers
+    );
     let session = null;
     let outputKind;
     let framesEncoded = 0;
@@ -19042,6 +19159,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
     const captureAttempts = [];
     let forceScreenshotForChunk = encoder.forceScreenshot;
     let shownBoxes;
+    let extraction;
     try {
       if (chunkWorkerCount === 1 || !forceScreenshotForChunk) {
         const bootStarted = Date.now();
@@ -19098,7 +19216,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           session = null;
         }
       }
-      const deferredVideoFrames = planVideos ? await extractDeferredVideoFramesForChunk({
+      const deferredVideoFrames = planVideos ? extractDeferredVideoFramesForChunk({
         planDir,
         planVideos,
         frames: chunkFrameNumbers,
@@ -19107,19 +19225,24 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
         cfg,
         remoteSources,
         shownBoxes
-      }) : [];
-      const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? createFrameLookupTable5(
-        planVideos.videos,
-        [
-          ...rebuildExtractedFramesFromPlanDir(
-            planDir,
-            planVideos.extracted.filter((video) => !video.deferredRange),
-            v2Manifest === null ? "dense-v1" : "sparse-v2"
-          ),
-          ...deferredVideoFrames
-        ],
-        resolveRenderFpsConfig(job.config.fps).value
+      }) : Promise.resolve([]);
+      extraction = deferredVideoFrames;
+      const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? deferredVideoFrames.then(
+        (deferred) => createFrameLookupTable5(
+          planVideos.videos,
+          [
+            ...rebuildExtractedFramesFromPlanDir(
+              planDir,
+              planVideos.extracted.filter((video) => !video.deferredRange),
+              v2Manifest === null ? "dense-v1" : "sparse-v2"
+            ),
+            ...deferred
+          ],
+          resolveRenderFpsConfig(job.config.fps).value
+        )
       ) : null;
+      videoFrameLookup?.catch(() => {
+      });
       const createChunkVideoFrameInjector = createChunkVideoFrameInjectorFactory(videoFrameLookup);
       const captureStarted = Date.now();
       captureMode = await runCaptureWithScreenshotFallback({
@@ -19202,7 +19325,11 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
             }
           );
         }
+      }).catch(async (captureError) => {
+        await deferredVideoFrames;
+        throw captureError;
       });
+      await deferredVideoFrames;
       captureStageMs = Date.now() - captureStarted;
       applyRenderWarningPolicy(
         job,
@@ -19281,6 +19408,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       }
       encodeStageMs = Date.now() - encodeStarted;
     } finally {
+      await extraction?.catch(() => {
+      });
       if (session) {
         try {
           await closeCaptureSession11(session);
@@ -19447,6 +19576,7 @@ export {
   plan,
   planV2,
   planV2WithPublisher,
+  prepareAnimatedGifInputs,
   prepareCaptureSessionForReuse4 as prepareCaptureSessionForReuse,
   prepareHyperframeLintBody,
   publishPlanV2FromExecutionPlan,