@hyperframes/producer 0.8.199 → 0.8.201

package/README.md

@@ -61,13 +61,13 @@ are rejected before a render starts. This is separate from engine sub-frame
 
 The producer can render HTML compositions to formats that carry a **true alpha channel** — not chroma key. The same composition that renders an opaque MP4 renders a layerable overlay when you set `format`.
 
-| `format`          | Codec / pixel format              | Alpha                   | Audio               | Use case                                                                                |
-| ----------------- | --------------------------------- | ----------------------- | ------------------- | --------------------------------------------------------------------------------------- |
-| `"mp4"` (default) | H.264 (yuv420p) or H.265 + HDR10  | No                      | AAC                 | Streaming, social, default deliverable                                                  |
-| `"webm"`          | VP9 + yuva420p                    | **True alpha**          | Opus                | Web playback as overlay (`<video>` over background); supported in Chrome, Edge, Firefox |
-| `"mov"`           | ProRes 4444 + yuva444p10le        | **True alpha + 10-bit** | AAC                 | Editor ingest (Premiere, Final Cut Pro, DaVinci Resolve)                                |
-| `"png-sequence"`  | Numbered RGBA PNGs in a directory | **Lossless alpha**      | Sidecar `audio.m4a` | After Effects / Nuke / Fusion, or pipelines that post-process frames before encoding    |
-| `"hls"`           | H.264 (yuv420p) in MPEG-TS        | No                      | AAC rendition       | VOD streaming — see [HLS Output](#hls-output)                                           |
+| `format`          | Codec / pixel format              | Alpha              | Audio               | Use case                                                                                |
+| ----------------- | --------------------------------- | ------------------ | ------------------- | --------------------------------------------------------------------------------------- |
+| `"mp4"` (default) | H.264 (yuv420p) or H.265 + HDR10  | No                 | AAC                 | Streaming, social, default deliverable                                                  |
+| `"webm"`          | VP9 + yuva420p                    | **True alpha**     | Opus                | Web playback as overlay (`<video>` over background); supported in Chrome, Edge, Firefox |
+| `"mov"`           | ProRes 4444 + yuva444p10le        | **True alpha**     | AAC                 | Editor ingest (Premiere, Final Cut Pro, DaVinci Resolve)                                |
+| `"png-sequence"`  | Numbered RGBA PNGs in a directory | **Lossless alpha** | Sidecar `audio.m4a` | After Effects / Nuke / Fusion, or pipelines that post-process frames before encoding    |
+| `"hls"`           | H.264 (yuv420p) in MPEG-TS        | No                 | AAC rendition       | VOD streaming — see [HLS Output](#hls-output)                                           |
 
 ### Example
 
@@ -88,7 +88,7 @@ await executeRenderJob(job, "./my-project", "./output.webm");
 The producer captures Chrome screenshots with the page background forced transparent (`html, body, [data-composition-id] { background: transparent !important }`) and the CDP default background override set to RGBA 0,0,0,0. The captured PNGs carry a real alpha channel and that channel is preserved end-to-end:
 
 - VP9 (`webm`) is encoded with `-pix_fmt yuva420p`, `-auto-alt-ref 0`, `-cpu-used 4` by default, and `alpha_mode=1` metadata. Tune the speed/quality tradeoff with `PRODUCER_VP9_CPU_USED` (`-8` to `8`) or local CLI `--vp9-cpu-used`.
-- ProRes 4444 (`mov`) is encoded with `-pix_fmt yuva444p10le`.
+- ProRes 4444 (`mov`) uses `-pix_fmt yuva444p10le` and carries a separate alpha plane. Chrome's RGBA capture, including alpha, is 8 bits per channel; the 10-bit pixel format adds no capture precision.
 - PNG sequences are written without re-encoding (zero-padded `frame_NNNNNN.png`).
 
 This is not chroma keying. There is no green/blue background to remove and no "key" tolerance to tune — pixels that were transparent in the browser are transparent in the output.

package/dist/distributed.js

@@ -96,6 +96,7 @@ import {
   createVideoFrameInjector,
   getEncoderPreset as getEncoderPreset3,
   distributeFrames as distributeFrames2,
+  distributeFramesInterleaved as distributeFramesInterleaved2,
   executeParallelCapture as executeParallelCapture2,
   mergeWorkerFrames,
   getSystemTotalMb,
@@ -1540,6 +1541,7 @@ import {
   parseVideoElements,
   parseImageElements,
   parseAudioElements,
+  isSelfOrAncestorHidden,
   resolveReferencedStart
 } from "@hyperframes/engine";
 function resolveHostEnd(host, hostStart) {
@@ -1600,6 +1602,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,
@@ -1633,8 +1644,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);
@@ -1844,7 +1860,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)}`);
@@ -2311,10 +2327,6 @@ var THREE_D_CONTEXT_PATTERN = /transform-style\s*:\s*preserve-3d|backface-visibi
 function detectThreeDTransformUsage(html) {
   return THREE_D_CONTEXT_PATTERN.test(html);
 }
-var MIX_BLEND_MODE_PATTERN = /mix-blend-mode\s*:/i;
-function detectMixBlendModeUsage(html) {
-  return MIX_BLEND_MODE_PATTERN.test(html);
-}
 var BACKGROUND_IMAGE_DECL_PATTERN = /(?:^|;|\{)\s*background(?:-image)?\s*:[^;}]*(?:\bgradient\s*\(|url\s*\()/i;
 function detectAncestorBackgroundImage(html) {
   const { document: document2 } = parseHTML4(html);
@@ -2467,8 +2479,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,
@@ -3327,7 +3340,6 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
   const renderModeHints = detectRenderModeHints(sanitizedHtml, options.pageMotionBlur);
   const hasShaderTransitions = detectShaderTransitionUsage(sanitizedHtml);
   const usesThreeDTransforms = detectThreeDTransformUsage(sanitizedHtml);
-  const usesMixBlendMode = detectMixBlendModeUsage(sanitizedHtml);
   const hasAncestorBackgroundImage = detectAncestorBackgroundImage(sanitizedHtml);
   const normalizedFontHtml = normalizeSystemFontPrimaryFamilies(
     injectTextRenderingRule(
@@ -3441,7 +3453,6 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
     renderModeHints,
     hasShaderTransitions,
     usesThreeDTransforms,
-    usesMixBlendMode,
     hasAncestorBackgroundImage
   };
 }
@@ -3848,13 +3859,6 @@ async function runCompileStage(input) {
       "[Render] Fast capture: composition uses a CSS 3D rendering context (perspective / preserve-3d / backface-visibility), so disabling drawElementImage for this render. Capture uses the platform's baseline route."
     );
   }
-  if (cfg.useDrawElement && process.env.HF_FAST_CAPTURE_BLEND !== "true" && compiled.usesMixBlendMode) {
-    cfg.useDrawElement = false;
-    deCompileGate = "mix_blend_mode";
-    log.info(
-      "[Render] Fast capture: composition uses mix-blend-mode, so disabling drawElementImage for this render. Capture uses the platform's baseline route."
-    );
-  }
   if (cfg.useDrawElement && process.env.HF_FAST_CAPTURE_ANCESTOR_BG !== "true" && compiled.hasAncestorBackgroundImage) {
     cfg.useDrawElement = false;
     deCompileGate = "ancestor_background_image";
@@ -4148,6 +4152,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,
@@ -5312,10 +5317,11 @@ async function constrainAacTruePeak(input) {
   const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
   return enforceAacTruePeak({
     audioPath: input.audioPath,
+    sourcePath: input.sourcePath,
     targetDurationSeconds: input.targetDurationSeconds,
     signal: input.signal,
-    probeTruePeak: (audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal }),
-    encode: defaultAacEncoder(timeoutMs, input.signal, input.sourcePath)
+    probeTruePeak: input.probeTruePeakDbfs ?? ((audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal })),
+    encode: input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath)
   });
 }
 async function enforceAacTruePeak(input) {
@@ -5325,6 +5331,7 @@ async function enforceAacTruePeak(input) {
     const correctedPath = join9(scratchDir, "audio.m4a");
     const measurements = [];
     let attenuationDb = 0;
+    let sourcePeakDbfs;
     let measuredPath = input.audioPath;
     for (let pass = 0; pass <= MAX_TRUE_PEAK_CORRECTION_PASSES; pass += 1) {
       const truePeakDbfs = await input.probeTruePeak(measuredPath, input.signal);
@@ -5341,7 +5348,11 @@ async function enforceAacTruePeak(input) {
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
       const headroomDb = AAC_TRUE_PEAK_CORRECTION_HEADROOM_DB * 2 ** pass;
-      attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - headroomDb - truePeakDbfs;
+      if (input.sourcePath && sourcePeakDbfs === void 0) {
+        sourcePeakDbfs = await input.probeTruePeak(input.sourcePath, input.signal);
+      }
+      const referenceDbfs = Math.max(truePeakDbfs, (sourcePeakDbfs ?? -Infinity) + attenuationDb);
+      attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - headroomDb - referenceDbfs;
       const result = await input.encode(
         input.audioPath,
         correctedPath,
@@ -5758,7 +5769,7 @@ async function runCaptureStage(input) {
       );
     }
   }
-  const captureOptions = buildCaptureOptions();
+  const captureOptions = { ...buildCaptureOptions(), deFrameFallback: false };
   const remedy = diskCaptureRemedy(cfg, job.config.format ?? "mp4", job.duration ?? 0, workerCount);
   const checkDiskProjection = createDiskCaptureProjection({
     framesDir,
@@ -5779,6 +5790,7 @@ async function runCaptureStage(input) {
       createBeforeCaptureHook: createRenderVideoFrameInjector,
       abortSignal,
       frameRangeStart: frameRange?.startFrame,
+      interleaveFrames: input.interleaveFrames,
       dedupPerfs,
       pageErrorLines: workerPageErrors,
       onProgress: (progress) => {
@@ -6356,9 +6368,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);
@@ -6369,7 +6378,7 @@ async function runEncodeStage(input) {
     encoderOpts,
     chunkedEncodeSize,
     abortSignal,
-    videoEngineCfg,
+    engineCfg,
     onFramesEncoded
   ) : await encodeFramesFromDir(
     framesDir,
@@ -6377,7 +6386,7 @@ async function runEncodeStage(input) {
     videoOnlyPath,
     encoderOpts,
     abortSignal,
-    videoEngineCfg,
+    engineCfg,
     onFramesEncoded
   );
   assertNotAborted();
@@ -6505,16 +6514,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) => join13(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: join13(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`),
+      outputDir: outputDirFor(batchIndex, workerId),
       outputFrameOffset: rangeStart
     }));
     batches.push(batch);
@@ -6572,8 +6607,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) {
@@ -7336,6 +7379,18 @@ function planFrameWeights(input) {
   }
   return weights;
 }
+function withChunkCaptureCost(slices, weights) {
+  const lightest = weights.reduce((least, weight) => Math.min(least, weight), Infinity);
+  return slices.map((slice) => {
+    let sum2 = 0;
+    for (let frame = slice.startFrame; frame < slice.endFrame; frame++) sum2 += weights[frame];
+    const cost = Math.round(sum2 / (slice.endFrame - slice.startFrame) / lightest * 100) / 100;
+    return cost > 1 ? { ...slice, captureCost: cost } : slice;
+  });
+}
+function effectiveChunkFrames(frames, captureCost = 1) {
+  return Math.round(frames * captureCost);
+}
 function buildWeightedChunkSlices(weights, chunkCount, minFrames, maxFrames) {
   if (isUniformFrameCost(weights)) return null;
   const totalFrames = weights.length;
@@ -8660,7 +8715,10 @@ function buildPlanChunkSlices(frameWeights, config, chunkCount, effectiveChunkSi
     MIN_CHUNK_SIZE,
     Math.min(config.targetChunkFrames ?? MAX_CHUNK_SIZE, MAX_CHUNK_SIZE, maxFramesPerChunk)
   ) : null;
-  return weighted ?? buildChunkSlices(frameWeights.length, chunkCount, effectiveChunkSize);
+  return withChunkCaptureCost(
+    weighted ?? buildChunkSlices(frameWeights.length, chunkCount, effectiveChunkSize),
+    frameWeights
+  );
 }
 async function readFontSnapshotSha() {
   const module = await import("@hyperframes/core/fonts/embedded-data");
@@ -9651,7 +9709,12 @@ function parseChunkSlices(value) {
       throw new PlanV2IntegrityError(`meta/chunks.json contains duplicate chunk index ${index}`);
     }
     indexes.add(index);
-    return { index, startFrame, endFrame };
+    if (chunk.captureCost === void 0) return { index, startFrame, endFrame };
+    const captureCost = chunk.captureCost;
+    if (typeof captureCost !== "number" || !Number.isFinite(captureCost) || captureCost <= 1) {
+      throw new PlanV2IntegrityError(`${field}.captureCost must be a number above 1`);
+    }
+    return { index, startFrame, endFrame, captureCost };
   });
 }
 function buildVideoChunkDependencies(executionPlanDir, dimensions) {
@@ -10828,15 +10891,17 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
         deferredVideos.filter((video) => remoteVideoIds.has(video.videoId))
       )
     });
+    const captureFrames = effectiveChunkFrames(framesInChunk, slice.captureCost);
     const chunkWorkerCount = resolveChunkCaptureWorkers(
-      framesInChunk,
-      calculateOptimalWorkers2(framesInChunk, void 0, cfg),
+      captureFrames,
+      calculateOptimalWorkers2(captureFrames, void 0, cfg),
       options?.maxCaptureWorkers
     );
     let session = null;
     let outputKind;
     let framesEncoded = 0;
     let sessionBootMs = 0;
+    let videoExtractMs = 0;
     let captureStageMs = 0;
     let encodeStageMs = 0;
     let captureMode;
@@ -10902,6 +10967,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           session = null;
         }
       }
+      const extractStarted = Date.now();
       const deferredVideoFrames = planVideos ? extractDeferredVideoFramesForChunk({
         planDir,
         planVideos,
@@ -10911,6 +10977,9 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
         cfg,
         remoteSources,
         shownBoxes
+      }).then((frames) => {
+        videoExtractMs = Date.now() - extractStarted;
+        return frames;
       }) : Promise.resolve([]);
       extraction = deferredVideoFrames;
       const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? deferredVideoFrames.then(
@@ -11039,7 +11108,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;
@@ -11128,6 +11198,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       sessionBootMs,
       captureStageMs,
       encodeStageMs,
+      // Wall time of the chunk's own video frame extraction; it overlaps captureStageMs, so do not add them.
+      videoExtractMs,
       workers: chunkWorkerCount,
       captureMode,
       // Device-pixel box each video's frames were extracted to cover; a video not listed kept full size.

package/dist/hyperframe.manifest.json

@@ -1,7 +1,7 @@
 {
   "version": "0.1.0",
   "buildId": "dev",
-  "sha256": "3af46e671fc1165bd676de2c1e16493105979083a615954aa23ef784de92f7ce",
+  "sha256": "74fe41f512dcc9c39366e4f48c8d24e6011f5180f122ab1525d210000618830f",
   "artifacts": {
     "iife": "hyperframe.runtime.iife.js",
     "esm": "hyperframe.runtime.mjs"