@hyperframes/producer 0.8.200 → 0.8.202

package/dist/index.js

@@ -33,6 +33,7 @@ import {
   createVideoFrameInjector,
   getEncoderPreset as getEncoderPreset3,
   distributeFrames as distributeFrames2,
+  distributeFramesInterleaved as distributeFramesInterleaved2,
   executeParallelCapture as executeParallelCapture2,
   mergeWorkerFrames,
   getSystemTotalMb,
@@ -5579,6 +5580,7 @@ import {
   parseVideoElements,
   parseImageElements,
   parseAudioElements,
+  isSelfOrAncestorHidden,
   resolveReferencedStart
 } from "@hyperframes/engine";
 function resolveHostEnd(host, hostStart) {
@@ -5639,6 +5641,15 @@ function collectHostWindows(html) {
   }
   return windows;
 }
+function collectHiddenVideoIds(html) {
+  const { document: document2 } = parseHTML2(html);
+  const hidden = /* @__PURE__ */ new Set();
+  for (const element of document2.querySelectorAll("video")) {
+    const id = element.getAttribute(MEDIA_RENDER_ID_ATTR) || element.getAttribute("id");
+    if (id && isSelfOrAncestorHidden(element)) hidden.add(id);
+  }
+  return hidden;
+}
 function toAbsoluteWindow(start, end, window2) {
   const absoluteStart = resolveAbsoluteMediaStartSeconds({
     authoredStart: start,
@@ -5672,8 +5683,13 @@ function collectRenderMedia(html) {
   const windows = collectHostWindows(html);
   const windowFor = (id) => windows.get(id) ?? ROOT_WINDOW;
   const droppedMediaIds = /* @__PURE__ */ new Set();
+  const hiddenIds = collectHiddenVideoIds(html);
   const videos = [];
   for (const video of parseVideoElements(html)) {
+    if (hiddenIds.has(video.id)) {
+      droppedMediaIds.add(video.id);
+      continue;
+    }
     const absolute = toAbsoluteWindow(video.start, video.end, windowFor(video.id));
     if (!absolute) {
       droppedMediaIds.add(video.id);
@@ -5883,7 +5899,7 @@ async function runAnimatedGifTranscode(request) {
       failureReason: result.failureReason
     });
   }
-  if (result.terminationReason === "deadline") {
+  if (result.terminationReason === "inactivity") {
     throw new Error(`Animated GIF transcode timed out after ${timeout}ms`);
   }
   throw result.error ?? new Error(`Animated GIF transcode failed (${result.exitCode}): ${result.stderr.slice(-500)}`);
@@ -6502,8 +6518,9 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
   const markedStaticHtml = markInferredVariableMediaDurations(staticCompiled, mediaUnresolved);
   let compiledHtml = resolutions.length > 0 ? injectDurations(markedStaticHtml, resolutions) : markedStaticHtml;
   const preResolved = extractResolvedMedia(compiledHtml);
+  const hiddenVideoIds = collectHiddenVideoIds(compiledHtml);
   const clampResults = await Promise.all(
-    preResolved.filter((el) => !!el.src && !el.loop).map(async (el) => {
+    preResolved.filter((el) => !!el.src && !el.loop && !hiddenVideoIds.has(el.id)).map(async (el) => {
       const { duration: maxDuration } = await resolveMediaDuration(
         el.src,
         el.mediaStart,
@@ -8174,6 +8191,7 @@ async function runProbeStage(input) {
         height,
         fps: job.config.fps,
         format: captureFormat,
+        transparent: needsAlpha,
         quality: captureFormat === "png" ? void 0 : resolveCaptureJpegQuality(job.config.quality),
         variables: job.config.variables,
         deviceScaleFactor,
@@ -9803,6 +9821,7 @@ async function runCaptureStage(input) {
       createBeforeCaptureHook: createRenderVideoFrameInjector,
       abortSignal,
       frameRangeStart: frameRange?.startFrame,
+      interleaveFrames: input.interleaveFrames,
       dedupPerfs,
       pageErrorLines: workerPageErrors,
       onProgress: (progress) => {
@@ -11318,9 +11337,6 @@ async function runEncodeStage(input) {
     return { encodeMs: Date.now() - stage5Start };
   }
   const onFramesEncoded = startEncodeProgress(job, "Encoding video", onProgress);
-  const baseScaledEncodeTimeout = Math.ceil((job.duration ?? 0) * 4e3);
-  const scaledEncodeTimeout = baseScaledEncodeTimeout * (job.config.quality === "high" ? 6 : 1);
-  const videoEngineCfg = scaledEncodeTimeout > engineCfg.ffmpegEncodeTimeout ? { ...engineCfg, ffmpegEncodeTimeout: scaledEncodeTimeout } : engineCfg;
   const frameExt = frameFileExtension2(input.captureImageFormat);
   const framePattern = `frame_%06d.${frameExt}`;
   const encoderOpts = videoEncoderOptions(input, engineCfg);
@@ -11331,7 +11347,7 @@ async function runEncodeStage(input) {
     encoderOpts,
     chunkedEncodeSize,
     abortSignal,
-    videoEngineCfg,
+    engineCfg,
     onFramesEncoded
   ) : await encodeFramesFromDir(
     framesDir,
@@ -11339,7 +11355,7 @@ async function runEncodeStage(input) {
     videoOnlyPath,
     encoderOpts,
     abortSignal,
-    videoEngineCfg,
+    engineCfg,
     onFramesEncoded
   );
   assertNotAborted();
@@ -11681,16 +11697,42 @@ function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
   }
   return ranges;
 }
-function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt, rangeStart = 0) {
+function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt, rangeStart = 0, stride = 1) {
   const workersPerBatch = Math.max(1, Math.floor(maxWorkers));
   const batches = [];
+  const outputDirFor = (batchIndex, workerId) => join26(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`);
+  if (stride > 1) {
+    const spans = /* @__PURE__ */ new Map();
+    for (const range of ranges) {
+      for (let frame = range.startFrame; frame < range.endFrame; frame++) {
+        const span = spans.get(frame % stride);
+        if (span) span.last = frame;
+        else spans.set(frame % stride, { first: frame, last: frame });
+      }
+    }
+    const strided = [...spans.values()];
+    for (let i = 0; i < strided.length; i += workersPerBatch) {
+      const batchIndex = batches.length;
+      batches.push(
+        strided.slice(i, i + workersPerBatch).map(({ first, last }, workerId) => ({
+          workerId,
+          startFrame: rangeStart + first,
+          endFrame: rangeStart + last + 1,
+          frameStride: stride,
+          outputDir: outputDirFor(batchIndex, workerId),
+          outputFrameOffset: rangeStart
+        }))
+      );
+    }
+    return batches;
+  }
   for (let i = 0; i < ranges.length; i += workersPerBatch) {
     const batchIndex = batches.length;
     const batch = ranges.slice(i, i + workersPerBatch).map((range, workerId) => ({
       workerId,
       startFrame: rangeStart + range.startFrame,
       endFrame: rangeStart + range.endFrame,
-      outputDir: join26(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`),
+      outputDir: outputDirFor(batchIndex, workerId),
       outputFrameOffset: rangeStart
     }));
     batches.push(batch);
@@ -11783,8 +11825,16 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
       currentWorkers,
       attemptWorkDir,
       attempt,
-      rangeStart
-    ) : [distributeFrames2(options.totalFrames, currentWorkers, attemptWorkDir, rangeStart)];
+      rangeStart,
+      options.interleaveFrames ? options.initialWorkerCount : 1
+    ) : [
+      (options.interleaveFrames ? distributeFramesInterleaved2 : distributeFrames2)(
+        options.totalFrames,
+        currentWorkers,
+        attemptWorkDir,
+        rangeStart
+      )
+    ];
     options.dedupPerfs.length = 0;
     try {
       for (const tasks of batches) {
@@ -12896,6 +12946,7 @@ async function executeRenderPipeline(input) {
       height,
       fps: job.config.fps,
       format: captureImageFormat,
+      transparent: needsAlpha,
       quality: captureImageFormat === "png" ? void 0 : resolveCaptureJpegQuality(job.config.quality),
       variables: job.config.variables,
       deviceScaleFactor,
@@ -13928,7 +13979,8 @@ async function executeRenderPipeline(input) {
             abortSignal: executionSignal,
             assertNotAborted,
             onProgress,
-            onFrameLanded: (frame) => overlap?.onFrameLanded(frame)
+            onFrameLanded: (frame) => overlap?.onFrameLanded(frame),
+            interleaveFrames: overlap !== null
           })
         );
         let captureRes;
@@ -19979,7 +20031,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
             assertNotAborted: () => {
             },
             frameRange: range,
-            onFrameLanded: (frame) => overlap.current?.onFrameLanded(frame)
+            onFrameLanded: (frame) => overlap.current?.onFrameLanded(frame),
+            interleaveFrames: overlap.current !== null
           }).catch(async (captureError) => {
             await overlap.current?.abort();
             overlap.current = null;

package/dist/public-server.js

@@ -54,6 +54,7 @@ import {
   createVideoFrameInjector,
   getEncoderPreset as getEncoderPreset3,
   distributeFrames as distributeFrames2,
+  distributeFramesInterleaved as distributeFramesInterleaved2,
   executeParallelCapture as executeParallelCapture2,
   mergeWorkerFrames,
   getSystemTotalMb,
@@ -5599,6 +5600,7 @@ import {
   parseVideoElements,
   parseImageElements,
   parseAudioElements,
+  isSelfOrAncestorHidden,
   resolveReferencedStart
 } from "@hyperframes/engine";
 function resolveHostEnd(host, hostStart) {
@@ -5659,6 +5661,15 @@ function collectHostWindows(html) {
   }
   return windows;
 }
+function collectHiddenVideoIds(html) {
+  const { document: document2 } = parseHTML2(html);
+  const hidden = /* @__PURE__ */ new Set();
+  for (const element of document2.querySelectorAll("video")) {
+    const id = element.getAttribute(MEDIA_RENDER_ID_ATTR) || element.getAttribute("id");
+    if (id && isSelfOrAncestorHidden(element)) hidden.add(id);
+  }
+  return hidden;
+}
 function toAbsoluteWindow(start, end, window2) {
   const absoluteStart = resolveAbsoluteMediaStartSeconds({
     authoredStart: start,
@@ -5692,8 +5703,13 @@ function collectRenderMedia(html) {
   const windows = collectHostWindows(html);
   const windowFor = (id) => windows.get(id) ?? ROOT_WINDOW;
   const droppedMediaIds = /* @__PURE__ */ new Set();
+  const hiddenIds = collectHiddenVideoIds(html);
   const videos = [];
   for (const video of parseVideoElements(html)) {
+    if (hiddenIds.has(video.id)) {
+      droppedMediaIds.add(video.id);
+      continue;
+    }
     const absolute = toAbsoluteWindow(video.start, video.end, windowFor(video.id));
     if (!absolute) {
       droppedMediaIds.add(video.id);
@@ -5903,7 +5919,7 @@ async function runAnimatedGifTranscode(request) {
       failureReason: result.failureReason
     });
   }
-  if (result.terminationReason === "deadline") {
+  if (result.terminationReason === "inactivity") {
     throw new Error(`Animated GIF transcode timed out after ${timeout}ms`);
   }
   throw result.error ?? new Error(`Animated GIF transcode failed (${result.exitCode}): ${result.stderr.slice(-500)}`);
@@ -6522,8 +6538,9 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
   const markedStaticHtml = markInferredVariableMediaDurations(staticCompiled, mediaUnresolved);
   let compiledHtml = resolutions.length > 0 ? injectDurations(markedStaticHtml, resolutions) : markedStaticHtml;
   const preResolved = extractResolvedMedia(compiledHtml);
+  const hiddenVideoIds = collectHiddenVideoIds(compiledHtml);
   const clampResults = await Promise.all(
-    preResolved.filter((el) => !!el.src && !el.loop).map(async (el) => {
+    preResolved.filter((el) => !!el.src && !el.loop && !hiddenVideoIds.has(el.id)).map(async (el) => {
       const { duration: maxDuration } = await resolveMediaDuration(
         el.src,
         el.mediaStart,
@@ -8194,6 +8211,7 @@ async function runProbeStage(input) {
         height,
         fps: job.config.fps,
         format: captureFormat,
+        transparent: needsAlpha,
         quality: captureFormat === "png" ? void 0 : resolveCaptureJpegQuality(job.config.quality),
         variables: job.config.variables,
         deviceScaleFactor,
@@ -9787,6 +9805,7 @@ async function runCaptureStage(input) {
       createBeforeCaptureHook: createRenderVideoFrameInjector,
       abortSignal,
       frameRangeStart: frameRange?.startFrame,
+      interleaveFrames: input.interleaveFrames,
       dedupPerfs,
       pageErrorLines: workerPageErrors,
       onProgress: (progress) => {
@@ -11302,9 +11321,6 @@ async function runEncodeStage(input) {
     return { encodeMs: Date.now() - stage5Start };
   }
   const onFramesEncoded = startEncodeProgress(job, "Encoding video", onProgress);
-  const baseScaledEncodeTimeout = Math.ceil((job.duration ?? 0) * 4e3);
-  const scaledEncodeTimeout = baseScaledEncodeTimeout * (job.config.quality === "high" ? 6 : 1);
-  const videoEngineCfg = scaledEncodeTimeout > engineCfg.ffmpegEncodeTimeout ? { ...engineCfg, ffmpegEncodeTimeout: scaledEncodeTimeout } : engineCfg;
   const frameExt = frameFileExtension2(input.captureImageFormat);
   const framePattern = `frame_%06d.${frameExt}`;
   const encoderOpts = videoEncoderOptions(input, engineCfg);
@@ -11315,7 +11331,7 @@ async function runEncodeStage(input) {
     encoderOpts,
     chunkedEncodeSize,
     abortSignal,
-    videoEngineCfg,
+    engineCfg,
     onFramesEncoded
   ) : await encodeFramesFromDir(
     framesDir,
@@ -11323,7 +11339,7 @@ async function runEncodeStage(input) {
     videoOnlyPath,
     encoderOpts,
     abortSignal,
-    videoEngineCfg,
+    engineCfg,
     onFramesEncoded
   );
   assertNotAborted();
@@ -11665,16 +11681,42 @@ function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
   }
   return ranges;
 }
-function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt, rangeStart = 0) {
+function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt, rangeStart = 0, stride = 1) {
   const workersPerBatch = Math.max(1, Math.floor(maxWorkers));
   const batches = [];
+  const outputDirFor = (batchIndex, workerId) => join26(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`);
+  if (stride > 1) {
+    const spans = /* @__PURE__ */ new Map();
+    for (const range of ranges) {
+      for (let frame = range.startFrame; frame < range.endFrame; frame++) {
+        const span = spans.get(frame % stride);
+        if (span) span.last = frame;
+        else spans.set(frame % stride, { first: frame, last: frame });
+      }
+    }
+    const strided = [...spans.values()];
+    for (let i = 0; i < strided.length; i += workersPerBatch) {
+      const batchIndex = batches.length;
+      batches.push(
+        strided.slice(i, i + workersPerBatch).map(({ first, last }, workerId) => ({
+          workerId,
+          startFrame: rangeStart + first,
+          endFrame: rangeStart + last + 1,
+          frameStride: stride,
+          outputDir: outputDirFor(batchIndex, workerId),
+          outputFrameOffset: rangeStart
+        }))
+      );
+    }
+    return batches;
+  }
   for (let i = 0; i < ranges.length; i += workersPerBatch) {
     const batchIndex = batches.length;
     const batch = ranges.slice(i, i + workersPerBatch).map((range, workerId) => ({
       workerId,
       startFrame: rangeStart + range.startFrame,
       endFrame: rangeStart + range.endFrame,
-      outputDir: join26(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`),
+      outputDir: outputDirFor(batchIndex, workerId),
       outputFrameOffset: rangeStart
     }));
     batches.push(batch);
@@ -11767,8 +11809,16 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
       currentWorkers,
       attemptWorkDir,
       attempt,
-      rangeStart
-    ) : [distributeFrames2(options.totalFrames, currentWorkers, attemptWorkDir, rangeStart)];
+      rangeStart,
+      options.interleaveFrames ? options.initialWorkerCount : 1
+    ) : [
+      (options.interleaveFrames ? distributeFramesInterleaved2 : distributeFrames2)(
+        options.totalFrames,
+        currentWorkers,
+        attemptWorkDir,
+        rangeStart
+      )
+    ];
     options.dedupPerfs.length = 0;
     try {
       for (const tasks of batches) {
@@ -12880,6 +12930,7 @@ async function executeRenderPipeline(input) {
       height,
       fps: job.config.fps,
       format: captureImageFormat,
+      transparent: needsAlpha,
       quality: captureImageFormat === "png" ? void 0 : resolveCaptureJpegQuality(job.config.quality),
       variables: job.config.variables,
       deviceScaleFactor,
@@ -13912,7 +13963,8 @@ async function executeRenderPipeline(input) {
             abortSignal: executionSignal,
             assertNotAborted,
             onProgress,
-            onFrameLanded: (frame) => overlap?.onFrameLanded(frame)
+            onFrameLanded: (frame) => overlap?.onFrameLanded(frame),
+            interleaveFrames: overlap !== null
           })
         );
         let captureRes;

package/dist/regression-harness.d.ts

@@ -105,6 +105,54 @@ type CliOptions = {
      */
     mode: HarnessMode;
 };
+type TestResult = {
+    suite: TestSuite;
+    passed: boolean;
+    /**
+     * Set when `--mode=distributed-simulated` skips a fixture that the
+     * distributed pipeline can't run (HDR, NTSC fps, fps outside DISTRIBUTED_FPS).
+     * `passed` is `true` for skipped fixtures — skipping is a clean outcome,
+     * not a failure — but the summary distinguishes them.
+     */
+    skipped?: {
+        reason: string;
+    };
+    compilation?: {
+        passed: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    visual?: {
+        passed: boolean;
+        failedFrames: number;
+        checkpoints: Array<{
+            time: number;
+            psnr: number;
+            passed: boolean;
+        }>;
+    };
+    audio?: {
+        passed: boolean;
+        correlation: number;
+        lagWindows: number;
+        /**
+         * Residual Overall RMS (dBFS) of `rendered - snapshot`. Present only
+         * when the fixture opts in via `meta.maxAudioResidualRmsDb`.
+         * `Number.NEGATIVE_INFINITY` ⇒ perfect cancellation. `NaN` ⇒ residual
+         * check could not run (missing ffmpeg, duration mismatch, ...); see
+         * `audio.residualError` for the reason.
+         */
+        residualRmsDb?: number;
+        residualError?: string;
+    };
+    streamDurationParity?: {
+        passed: boolean;
+        videoDurationSeconds: number;
+        audioDurationSeconds: number;
+        driftSeconds: number;
+    };
+    renderedOutputPath?: string;
+};
 export declare function parseArgs(argv: string[]): CliOptions;
 export declare function discoverTestSuites(testsDir: string, filterNames: string[], excludeTags?: string[]): TestSuite[];
 /** The frame a checkpoint time samples. Shared so selection and lookup agree. */
@@ -154,4 +202,9 @@ export type StreamDurationParity = {
 };
 export declare function checkStreamDurationParity(videoPath: string): Promise<StreamDurationParity | null>;
 export declare function createRegressionTempRoot(suiteId: string, parent?: string): string;
+export declare function runTestSuite(suite: TestSuite, options: {
+    update: boolean;
+    keepTemp: boolean;
+    mode: HarnessMode;
+}): Promise<TestResult>;
 export {};

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

@@ -84,6 +84,7 @@ export interface CaptureStageInput {
         endFrame: number;
     };
     onFrameLanded?: (frame: LandedFrame) => void;
+    interleaveFrames?: boolean;
 }
 export interface CaptureStageResult {
     /** Final worker count after any adaptive retry. */

package/dist/services/renderMediaCollector.d.ts

@@ -6,6 +6,8 @@
  * and placed by the composition hosts it sits inside.
  */
 import { type VideoElement, type ImageElement, type AudioElement } from "@hyperframes/engine";
+/** Ids, as the parsers report them, of videos that are `data-hidden` or sit inside such an element. */
+export declare function collectHiddenVideoIds(html: string): Set<string>;
 export interface RenderMedia {
     videos: VideoElement[];
     audios: AudioElement[];

package/dist/services/renderOrchestrator.d.ts

@@ -29,51 +29,40 @@ export interface RenderConfig {
     /** Segmented capture: keep renders/.hf-segments/<planHash> after a successful render. */
     keepSegments?: boolean;
     /**
-     * Output container format. Defaults to `"mp4"`; existing renders are
-     * unaffected unless this field is set explicitly.
+     * Output container format. Defaults to `"mp4"`; set explicitly for other formats.
      *
-     * - `"mp4"`: H.264 by default, or H.265 + HDR10 when HDR auto-detect
-     *   engages or `hdrMode: "force-hdr"` is set. Opaque. The
-     *   default streaming/social deliverable. Faststart is applied so the
-     *   `moov` atom sits at the file start and the file plays from a
-     *   partial download.
-     * - `"webm"`: VP9 + `yuva420p` pixel format → **true alpha channel**, no
-     *   chroma key. Plays in Chrome, Edge, and Firefox; Safari support for
-     *   alpha-WebM is incomplete. Use this when the output should drop
-     *   straight into a `<video>` over a colored background on the web.
-     *   Audio is muxed as Opus.
-     * - `"mov"`: ProRes 4444 + `yuva444p10le` → **true alpha channel +
-     *   10-bit color**. Sized for editor ingest (Premiere, Final Cut Pro,
-     *   DaVinci Resolve), not direct web playback. Audio is muxed as AAC.
-     * - `"gif"`: animated GIF encoded from captured RGBA frames with a two-pass
-     *   FFmpeg palette (`palettegen` + `paletteuse`). Use for PRs, READMEs,
-     *   and docs where inline autoplay matters more than file size. No audio
-     *   stream; transparency is binary because GIF has no partial alpha.
-     * - `"png-sequence"`: a directory of zero-padded RGBA PNGs
-     *   (`frame_000001.png` …). Lossless alpha, largest on disk, no muxed
-     *   audio (an `audio.m4a` sidecar is written alongside the PNGs when
-     *   the composition has audio elements). Use for After Effects / Nuke
-     *   / Fusion ingest, or when frames need post-processing before
-     *   encoding. `outputPath` is treated as a directory; it is created if
-     *   it doesn't exist.
-     * - `"hls"`: HLS VOD package — the same opaque H.264 + AAC encode as
-     *   `"mp4"`, stream-copied (no re-encode) into a directory of MPEG-TS
-     *   segments: `master.m3u8`, `video.m3u8` + `video_%05d.ts`, and
-     *   `audio.m3u8` + `audio_%05d.ts` when the composition has audio.
-     *   Segments are fixed-length (see {@link RenderConfig.hlsSegmentSeconds})
-     *   and every one starts on an IDR frame, because the encoder's GOP is
-     *   locked to `hlsSegmentSeconds × fps`. Like `"png-sequence"`,
-     *   `outputPath` is treated as a directory. SDR only, software encoder
-     *   only, and not available in distributed / Lambda / Cloud Run mode.
+     * - `"mp4"`: opaque H.264, or H.265 + HDR10 with HDR auto-detection or
+     *   `hdrMode: "force-hdr"`. For streaming/social delivery; faststart puts the
+     *   `moov` atom first so playback can begin during a partial download.
+     * - `"webm"`: VP9 + `yuva420p` with true alpha (no chroma key) and Opus audio.
+     *   For `<video>` overlays in Chrome, Edge and Firefox; Safari's alpha-WebM
+     *   support is incomplete.
+     * - `"mov"`: ProRes 4444 + `yuva444p10le` with true alpha and AAC audio.
+     *   Chrome captures 8-bit RGBA; encoding it as 10-bit ProRes does not add
+     *   capture precision. For editor ingest (Premiere, Final Cut Pro, DaVinci
+     *   Resolve), rather than direct web playback.
+     * - `"gif"`: animated GIF from RGBA captures, using FFmpeg's two-pass
+     *   `palettegen` + `paletteuse`. For inline autoplay in PRs, READMEs and docs
+     *   when file size matters less. No audio; transparency is binary, not partial.
+     * - `"png-sequence"`: zero-padded RGBA PNGs (`frame_000001.png` ...), with
+     *   lossless alpha and the largest disk footprint. No muxed audio; an
+     *   `audio.m4a` sidecar is written when the composition contains audio.
+     *   For After Effects / Nuke / Fusion or post-processing before encoding.
+     *   `outputPath` is a directory, created if it does not exist.
+     * - `"hls"`: HLS VOD using the opaque H.264 + AAC encode from `"mp4"`,
+     *   stream-copied without re-encoding into MPEG-TS in the `outputPath` directory:
+     *   `master.m3u8`, `video.m3u8` + `video_%05d.ts`, and `audio.m3u8` +
+     *   `audio_%05d.ts` when the composition contains audio. Segment length is
+     *   {@link RenderConfig.hlsSegmentSeconds}; the encoder's GOP is locked to
+     *   that length in frames, so each segment starts on an IDR frame.
+     *   SDR and software encoders only; unavailable in distributed rendering,
+     *   including Lambda and Cloud Run.
      *
-     * Alpha output (`"webm"`, `"mov"`, `"png-sequence"`, `"gif"`) automatically
-     * forces screenshot capture (Chrome's BeginFrame compositor does not
-     * preserve alpha on Linux headless-shell) and disables HDR — HDR +
-     * alpha is not a supported combination, a warning is logged and HDR
-     * falls back to SDR. The transparent-background CSS is injected by
-     * the engine's `initTransparentBackground` helper, so authors should
-     * not paint a fullscreen `body` / `#root` background in their
-     * compositions when targeting alpha output.
+     * Alpha formats (`"webm"`, `"mov"`, `"png-sequence"`, `"gif"`) force screenshot
+     * capture because BeginFrame does not preserve alpha on Linux headless-shell.
+     * HDR + alpha is unsupported: a warning is logged and output falls back to SDR.
+     * The engine's `initTransparentBackground` injects transparent-background CSS;
+     * avoid painting a fullscreen `body` / `#root` background for alpha output.
      */
     format?: RenderOutputFormat;
     /** GIF Netscape loop count. 0 means infinite looping. Only used with `format: "gif"`. */
@@ -481,7 +470,7 @@ interface ExtractedVideoReadinessInput {
 }
 export declare function collectVideoMetadataHints(extractedVideos: readonly ExtractedVideoReadinessInput[]): CaptureVideoMetadataHint[];
 export declare function findMissingFrameRanges(totalFrames: number, framesDir: string, frameExt: "jpg" | "png"): FrameRange[];
-export declare function buildMissingFrameRetryBatches(ranges: FrameRange[], maxWorkers: number, workDir: string, attempt: number, rangeStart?: number): WorkerTask[][];
+export declare function buildMissingFrameRetryBatches(ranges: FrameRange[], maxWorkers: number, workDir: string, attempt: number, rangeStart?: number, stride?: number): WorkerTask[][];
 /**
  * The capture mode this render will REPORT, pre-capture.
  *
@@ -596,6 +585,8 @@ export declare function executeDiskCaptureWithAdaptiveRetry(options: {
     createBeforeCaptureHook: () => BeforeCaptureHook | null;
     abortSignal?: AbortSignal;
     onProgress?: (progress: ParallelProgress) => void;
+    /** Workers take frames round-robin so an in-order consumer (the overlapped encoder) is never starved. */
+    interleaveFrames?: boolean;
     cfg: EngineConfig;
     log: ProducerLogger;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.200",
+  "version": "0.8.202",
   "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.200",
-    "@hyperframes/studio-server": "0.8.200",
-    "@hyperframes/lint": "0.8.200",
-    "@hyperframes/engine": "0.8.200",
-    "@hyperframes/parsers": "0.8.200"
+    "@hyperframes/core": "0.8.202",
+    "@hyperframes/engine": "0.8.202",
+    "@hyperframes/lint": "0.8.202",
+    "@hyperframes/studio-server": "0.8.202",
+    "@hyperframes/parsers": "0.8.202"
   },
   "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.200"
+    "@hyperframes/aws-lambda": "0.8.202"
   },
   "engines": {
     "node": ">=22"