@hyperframes/producer 0.8.183 → 0.8.185

package/dist/public-server.js

@@ -8965,6 +8965,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;
@@ -10134,6 +10135,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,
@@ -10141,7 +10143,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,
@@ -10278,6 +10281,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((resolve10) => wake = resolve10);
+      }
+      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,
@@ -10285,16 +10406,11 @@ async function runEncodeStage(input) {
     outputPath,
     framesDir,
     videoOnlyPath,
-    width,
-    height,
     needsAlpha,
     hasAudio,
     audioOutputPath,
     isPngSequence,
     isGif,
-    preset,
-    effectiveQuality,
-    effectiveBitrate,
     enableChunkedEncode,
     chunkedEncodeSize,
     abortSignal,
@@ -10324,7 +10440,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) {
@@ -10354,24 +10470,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,
@@ -10645,7 +10744,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;
@@ -10663,7 +10761,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,
@@ -13286,6 +13385,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,
@@ -13307,13 +13434,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;
           }
@@ -13382,33 +13511,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;
       }
@@ -14370,9 +14473,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) {

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

@@ -17,7 +17,7 @@ export declare class RenderChunkValidationError extends Error {
     constructor(code: RenderChunkValidationCode, message: string);
 }
 /** One injector per browser session: a hook reused on a fresh page can skip its first injection. */
-export declare function createChunkVideoFrameInjectorFactory(frameLookup: FrameLookupTable | null): () => BeforeCaptureHook | null;
+export declare function createChunkVideoFrameInjectorFactory(frameLookup: FrameLookupTable | Promise<FrameLookupTable> | null): () => BeforeCaptureHook | null;
 /**
  * Rebuilds `ExtractedFrames[]` from `<planDir>/video-frames/<videoId>/`. `framePaths` keys are 0-based
  * frame indexes (what `getFrameAtTime` reads); any other key drops every video's first-paint frame.

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

@@ -73,7 +73,7 @@ export interface ChunkResult {
     sessionBootMs: number;
     captureStageMs: number;
     encodeStageMs: number;
-    /** Capture workers used for this chunk (`calculateOptimalWorkers` result). */
+    /** Capture workers used for this chunk (`resolveChunkCaptureWorkers` result). */
     workers: number;
     /**
      * Effective engine mode used by every worker, after any browser fallback.
@@ -110,11 +110,18 @@ export interface RenderChunkOptions {
      * whole slice.
      */
     frameRange?: ChunkFrameRange;
+    /**
+     * Capture browsers the runtime can host. Raises the machine-wide sizing up to
+     * this many, one browser per 20 frames; never lowers it.
+     */
+    maxCaptureWorkers?: number;
 }
+/** Capture browsers for a chunk: the machine-wide sizing, raised by the runtime's budget. */
+export declare function resolveChunkCaptureWorkers(framesInChunk: number, machineSized: number, maxCaptureWorkers: number | undefined): number;
 /** The frames a chunk renders: its slice, or a validated sub-range of it. */
 export declare function resolveChunkFrameRange(slice: ChunkSliceJson, chunkIndex: number, frameRange: ChunkFrameRange | undefined): ChunkFrameRange;
 /** Compatibility-safe adapter seam for built-in or injected chunk renderers. */
-export type ChunkRenderer = (planDir: string, chunkIndex: number, outputChunkPath: string) => Promise<ChunkResult>;
+export type ChunkRenderer = (planDir: string, chunkIndex: number, outputChunkPath: string, options?: RenderChunkOptions) => Promise<ChunkResult>;
 interface DistributedCaptureSessionDependencies {
     createCaptureSession: typeof createCaptureSession;
     assertSwiftShader: typeof assertSwiftShader;

package/dist/services/render/stages/captureStage.d.ts

@@ -34,7 +34,7 @@
  * `safeCleanup`, `sampleDirectoryBytes`, etc.) into a shared module so
  * the stages can import them without reaching back into the orchestrator.
  */
-import { type BeforeCaptureHook, type CaptureOptions, type CapturePerfSummary, type CaptureSession, type EngineConfig } from "@hyperframes/engine";
+import { type BeforeCaptureHook, type CaptureOptions, type CapturePerfSummary, type CaptureSession, type EngineConfig, type LandedFrame } from "@hyperframes/engine";
 import type { FileServerHandle } from "../../fileServer.js";
 import type { ProducerLogger } from "../../../logger.js";
 import { type CaptureAttemptSummary, type ProgressCallback, type RenderConfig, type RenderJob } from "../../renderOrchestrator.js";
@@ -87,6 +87,7 @@ export interface CaptureStageInput {
         startFrame: number;
         endFrame: number;
     };
+    onFrameLanded?: (frame: LandedFrame) => void;
 }
 export interface CaptureStageResult {
     /** Final worker count after any adaptive retry. */

package/dist/services/render/stages/encodeStage.d.ts

@@ -26,8 +26,12 @@
  *     branch + same args.
  *   - `Encoding failed: <err>` throws on the encoder's
  *     `success: false`.
+ *
+ * `encodeWhileCapturing` runs the same mp4 encode during multi-worker disk
+ * capture, feeding frames in order as they land, and falls back to this
+ * stage's encode if it fails.
  */
-import { getEncoderPreset, type EngineConfig } from "@hyperframes/engine";
+import { getEncoderPreset, type EngineConfig, type LandedFrame } from "@hyperframes/engine";
 import type { ProducerLogger } from "../../../logger.js";
 import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 export interface EncodeStageInput {
@@ -71,7 +75,7 @@ export interface EncodeStageInput {
     enableChunkedEncode: boolean;
     chunkedEncodeSize: number;
     /** Already-resolved engine config from the orchestrator; direct callers fall back below. */
-    engineConfig?: Pick<EngineConfig, "ffmpegEncodeTimeout" | "vp9CpuUsed">;
+    engineConfig?: Pick<EngineConfig, "ffmpegEncodeTimeout" | "vp9CpuUsed"> & Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>;
     abortSignal: AbortSignal | undefined;
     assertNotAborted: () => void;
     onProgress?: ProgressCallback;
@@ -97,4 +101,24 @@ export interface EncodeStageResult {
     /** Wall-clock ms for the encode (or png-copy) phase. */
     encodeMs: number;
 }
+/**
+ * Software libx264 from JPEG only: the streaming encoder then runs the disk encoder's
+ * arguments (same bytes). Needs a core the capture workers leave free.
+ */
+export declare function canEncodeWhileCapturing(input: EncodeStageInput, workerCount: number, cpuCount: number): boolean;
+export interface EncodeWhileCapturing {
+    /** A worker finished writing this frame. */
+    onFrameLanded: (frame: LandedFrame) => void;
+    /** Capture succeeded and every frame is in `framesDir`: encode the rest. */
+    finish: () => Promise<EncodeStageResult>;
+    /** Capture failed: stop the encoder and wait for it to exit. */
+    abort: () => Promise<void>;
+    /** Frames handed to the encoder so far. */
+    readonly framesFed: number;
+}
+/**
+ * Feeds frames 0, 1, 2… to the encoder as each lands; capture never waits on it.
+ * On failure `finish` re-runs `runEncodeStage` on the same frames.
+ */
+export declare function encodeWhileCapturing(input: EncodeStageInput, totalFrames: number): EncodeWhileCapturing;
 export declare function runEncodeStage(input: EncodeStageInput): Promise<EncodeStageResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.183",
+  "version": "0.8.185",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/core": "0.8.183",
-    "@hyperframes/engine": "0.8.183",
-    "@hyperframes/parsers": "0.8.183",
-    "@hyperframes/studio-server": "0.8.183",
-    "@hyperframes/lint": "0.8.183"
+    "@hyperframes/lint": "0.8.185",
+    "@hyperframes/parsers": "0.8.185",
+    "@hyperframes/studio-server": "0.8.185",
+    "@hyperframes/engine": "0.8.185",
+    "@hyperframes/core": "0.8.185"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
@@ -48,7 +48,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@hyperframes/aws-lambda": "0.8.183"
+    "@hyperframes/aws-lambda": "0.8.185"
   },
   "engines": {
     "node": ">=22"