@hyperframes/engine 0.8.189 → 0.8.190-hdr.1

package/dist/services/audioMixer.js

@@ -11,6 +11,8 @@ import { clampFadesToDuration, readElementFades } from "@hyperframes/core/audio-
 import { downloadToTemp, isHttpUrl, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { describeFfmpegFailure, runFfmpeg } from "../utils/runFfmpeg.js";
+import { cpus } from "node:os";
+import { createConcurrencyLimit } from "../utils/concurrencyLimit.js";
 import { encodeAac } from "./aacEncode.js";
 import { audioSubprocessEvidence } from "./audioFailureDiagnostic.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
@@ -129,6 +131,8 @@ function legacyFilterScriptOptionIsUnsupported(stderr) {
  * no audio). 32 segments keeps a wide safety margin and is far more resolution
  * than a piecewise-linear volume envelope needs.
  */
+// Caps the ffmpeg runs that prepare clips; all of a long mix's clips at once starved the host (200 clips, 200 ffmpeg).
+const inPrepareSlot = createConcurrencyLimit(Math.max(2, Math.floor(cpus().length / 2)));
 const MAX_VOLUME_SEGMENTS = 32;
 /**
  * Volume delta below which a keyframe is collinear enough to drop. Kept tight
@@ -1043,7 +1047,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
         else
             signal.addEventListener("abort", () => internalController.abort(), { once: true });
     }
-    await Promise.all(elements.map(async (element, index) => {
+    await Promise.all(elements.map((element, index) => inPrepareSlot(async () => {
         if (effectiveSignal.aborted) {
             failures.push({
                 stage: "cancelled",
@@ -1089,12 +1093,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 });
                 return;
             }
-            // STUDIO-5433: an audio src that resolved to a text document (an
-            // unresolved nested-composition preview URL, or a 403/404 body served
-            // with a 200) never reaches the probe below when the element carries an
-            // authored duration or `loop`. It then fails inside ffmpeg as
-            // `prepare/ffmpeg_failed` with owner "system" — an authoring bug paged
-            // as a platform fault, after every frame has already been captured.
+            // A src that resolved to a text document is an authoring error, not an ffmpeg failure.
             if (await isNotMediaPayload(srcPath)) {
                 failures.push({
                     stage: "source",
@@ -1118,7 +1117,8 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 }
                 const effectiveDuration = timeAtSourceTime(normalizeRateSpec(element.playbackRate), metadata.durationSeconds - element.mediaStart);
                 element.end =
-                    element.start + (effectiveDuration > 0 ? effectiveDuration : metadata.durationSeconds);
+                    element.start +
+                        (effectiveDuration > 0 ? effectiveDuration : metadata.durationSeconds);
             }
             let audioSrcPath = srcPath;
             if (element.type === "video") {
@@ -1157,24 +1157,14 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 }
                 audioSrcPath = trimmedPath;
             }
-            // Apply the track's FX chain to the dry, trimmed audio, before volume
-            // automation is baked in: effects should see the raw signal, and the
-            // envelope belongs on their output. A missing or broken chain is fatal
-            // for the whole mix rather than a per-track warning — quietly rendering
-            // the dry signal ships a mix that sounds plausible and is wrong.
+            // The FX chain runs on the dry trimmed audio, before the envelope. A broken chain fails the mix.
             const chain = element.fxChain ? parseAudioFxChain(element.fxChain) : undefined;
             const automation = element.automation
                 ? resolveAutomation(parseAutomation(element.automation), chain)
                 : null;
-            // Computed before the chain runs, not after: the FX pass bakes the
-            // envelope into its float output so the duck lands before the ±1 clamp
-            // in writeWav, instead of after it.
-            //
-            // A volume lane supersedes keyframes probed from the timeline: the two
-            // would fight, and the lane is the explicit one. `lint` warns when a
-            // track carries both.
-            //
-            // With clip gain ahead of the chain, the lane carries its share of the capped product.
+            // Computed before the chain so the FX pass bakes the envelope in ahead of the ±1 clamp.
+            // A volume lane supersedes probed keyframes. With clip gain ahead of the chain, the lane
+            // carries its share of the capped product.
             const gainBeforeFx = chain !== undefined && enabledAudioFxNodes(chain).length > 0;
             const laneKeyframes = automation
                 ? volumeLaneKeyframes(automation, element.start, element.end - element.start, element.volume ?? 1, gainBeforeFx)
@@ -1191,11 +1181,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             let bakedEnvelope = false;
             let tailSeconds = 0;
             if (chain) {
-                // The chain is serialised into the attribute, the same way colour
-                // grading carries its config, so there is no side-car file to find,
-                // resolve or lose.
-                // The rendered WAV is longer than the input by exactly this much, so
-                // the mix has to be told to let it through.
+                // The rendered WAV is longer than the input by the chain's tail; the mix lets it through.
                 tailSeconds = chainTailSeconds(chain, automation ?? undefined);
                 const fxResult = await applyAudioFxChain(audioSrcPath, chain, join(workDir, `${element.id}-fx.wav`), {
                     trackId: element.id,
@@ -1207,11 +1193,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 audioSrcPath = fxResult.path;
                 bakedEnvelope = fxResult.envelopeBaked;
             }
-            // Primary volume-automation path for a track the FX pass did not bake:
-            // multiply the envelope into the PCM samples (sample-accurate, no
-            // keyframe ceiling). If the WAV isn't the expected 16-bit PCM, fall
-            // back to the ffmpeg expression path by leaving the keyframes on the
-            // track for buildVolumeExpression to handle.
+            // Bake the envelope into the PCM samples; a non-16-bit WAV falls back to the ffmpeg expression.
             if (envelope && !bakedEnvelope) {
                 bakedEnvelope = applyVolumeEnvelopeToWav(audioSrcPath, envelope.keyframes, envelope.trackStart, envelope.baseVolume);
             }
@@ -1247,7 +1229,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 detail: boundedDetail(`Audio processing failed for element ${element.id}: ${err instanceof Error ? err.message : String(err)}`),
             });
         }
-    })).catch((err) => {
+    }, effectiveSignal))).catch((err) => {
         // Promise.all rejected on the first fatal failure without waiting for its
         // siblings; abort them so their ffmpeg stops before workDir disappears.
         internalController.abort();

package/dist/services/browserManager.js

@@ -244,7 +244,6 @@ const BEGINFRAME_ONLY_FLAGS = new Set([
 function stripBeginFrameFlags(args) {
     return args.filter((a) => !BEGINFRAME_ONLY_FLAGS.has(a));
 }
-const BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS = 10;
 const BEGINFRAME_PROBE_TIMEOUT_MS = 2000;
 const BEGINFRAME_PROBE_CLEANUP_TIMEOUT_MS = 250;
 async function awaitBeforeDeadline(operation, deadline, label) {
@@ -325,7 +324,8 @@ async function probeBeginFrameSupport(browser, timeoutMs = BEGINFRAME_PROBE_TIME
         let bytes = Buffer.alloc(0);
         let isPng = false;
         let attempts = 0;
-        for (attempts = 1; attempts <= BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS; attempts += 1) {
+        while (!isPng && Date.now() < deadline) {
+            attempts += 1;
             const response = await awaitBeforeDeadline(client.send("HeadlessExperimental.beginFrame", {
                 frameTimeTicks: 1000 + (attempts - 1) * 33,
                 interval: 33,
@@ -339,13 +339,13 @@ async function probeBeginFrameSupport(browser, timeoutMs = BEGINFRAME_PROBE_TIME
                     bytes[1] === 0x50 &&
                     bytes[2] === 0x4e &&
                     bytes[3] === 0x47;
-            if (isPng)
+            if (isPng || Date.now() + 10 >= deadline)
                 break;
             await awaitBeforeDeadline(new Promise((resolveDelay) => setTimeout(resolveDelay, 10)), deadline, `screenshot retry delay ${attempts}`);
         }
         if (!isPng) {
             throw new Error(`beginFrame screenshot returned ${bytes.length} bytes after ` +
-                `${BEGINFRAME_SCREENSHOT_PROBE_ATTEMPTS} attempts with signature ` +
+                `${attempts} attempts in ${Date.now() - started}ms with signature ` +
                 `${bytes.length >= 4 ? bytes.subarray(0, 4).toString("hex") : "<empty>"}`);
         }
         await awaitBeforeDeadline(client.detach(), deadline, "CDP detach").catch(() => { });

package/dist/services/chunkEncoder.js

@@ -214,7 +214,7 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
         else {
             const encoderName = codec === "h264" ? "libx264" : "libx265";
             args.push("-c:v", encoderName, "-preset", preset);
-            appendSoftwareEncoderThreadsArg(args);
+            appendSoftwareEncoderThreadsArg(args, encoderName);
             if (bitrate)
                 args.push("-b:v", bitrate);
             else

package/dist/services/frameCapture.js

@@ -9,7 +9,8 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { COMPOSITION_SOURCE_URL, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, } from "@hyperframes/core";
+import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, } from "@hyperframes/core";
+import { holdRenderFrameVideos } from "./renderFrameVideoHold.js";
 import { DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
 import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
@@ -902,6 +903,9 @@ async function constructCaptureSession(input) {
     // Media elements are addressed by a document-unique render id, not by the
     // per-file element id. Install the resolvers before any page script runs.
     await installMediaRenderIdBridge(page);
+    if (options.skipReadinessVideoIds?.length) {
+        await page.evaluateOnNewDocument(holdRenderFrameVideos, options.skipReadinessVideoIds, MEDIA_RENDER_ID_ATTR);
+    }
     // Fast capture: record accelerated canvases (webgl/webgl2/webgpu) and force
     // preserveDrawingBuffer before any page script can create a context — their
     // paint records freeze at the first frame, so captureDrawElementFrame

package/dist/services/pageMotionBlur.js

@@ -33,15 +33,17 @@ async function readPageMotionBlur(page) {
         const got = typeof report === "function" ? report() : null;
         if (!got || typeof got !== "object")
             return null;
+        const tier = Reflect.get(got, "tier");
         return {
             state: String(Reflect.get(got, "state")),
             code: String(Reflect.get(got, "reasonCode")),
             movers: Number(Reflect.get(got, "movers")),
             failedFrames: Number(Reflect.get(got, "failedFrames")) || 0,
+            tier: typeof tier === "string" ? tier : null,
         };
     });
 }
-const formatPageMotionBlur = (r) => `[motion-blur] ${r.state} reasonCode=${r.code} movers=${r.movers} failedFrames=${r.failedFrames}`;
+const formatPageMotionBlur = (r) => `[motion-blur] ${r.state} reasonCode=${r.code} movers=${r.movers} failedFrames=${r.failedFrames}${r.tier ? ` tier=${r.tier}` : ""}`;
 /** One line saying what the page's blur did for this session; null when the page never asked for blur. */
 export async function describePageMotionBlur(page) {
     const r = await readPageMotionBlur(page);

package/dist/services/renderFrameVideoHold.d.ts

@@ -0,0 +1,2 @@
+/** In-page, before any script: holds replaced videos at preload none from parse (Chrome ignores a later none). */
+export declare function holdRenderFrameVideos(ids: readonly string[], renderIdAttr: string): void;

package/dist/services/renderFrameVideoHold.js

@@ -0,0 +1,19 @@
+/** In-page, before any script: holds replaced videos at preload none from parse (Chrome ignores a later none). */
+export function holdRenderFrameVideos(ids, renderIdAttr) {
+    const held = new Set(ids);
+    window.__HF_RENDER_FRAME_VIDEO_IDS = ids;
+    const hold = (el) => {
+        if (el instanceof HTMLVideoElement && held.has(el.getAttribute(renderIdAttr) || el.id))
+            el.preload = "none";
+    };
+    new MutationObserver((records) => {
+        for (const record of records)
+            for (const node of record.addedNodes) {
+                if (node.nodeType !== 1)
+                    continue;
+                hold(node);
+                for (const video of node.querySelectorAll("video"))
+                    hold(video);
+            }
+    }).observe(document, { childList: true, subtree: true });
+}

package/dist/services/softwareEncoderThreads.d.ts

@@ -1,2 +1,3 @@
+export declare const X265_MAX_THREADS = 16;
 /** x264/x265 bitstreams depend on the thread count, so it comes from the CPU quota, never ffmpeg's host-core guess. */
-export declare function appendSoftwareEncoderThreadsArg(args: string[], parallelism?: number): void;
+export declare function appendSoftwareEncoderThreadsArg(args: string[], encoder: "libx264" | "libx265", parallelism?: number): void;

package/dist/services/softwareEncoderThreads.js

@@ -1,5 +1,7 @@
 import { availableParallelism } from "node:os";
+export const X265_MAX_THREADS = 16;
 /** x264/x265 bitstreams depend on the thread count, so it comes from the CPU quota, never ffmpeg's host-core guess. */
-export function appendSoftwareEncoderThreadsArg(args, parallelism = availableParallelism()) {
-    args.push("-threads", String(Math.max(1, Math.floor(parallelism))));
+export function appendSoftwareEncoderThreadsArg(args, encoder, parallelism = availableParallelism()) {
+    const cap = encoder === "libx265" ? X265_MAX_THREADS : Infinity;
+    args.push("-threads", String(Math.min(cap, Math.max(1, Math.floor(parallelism)))));
 }

package/dist/services/streamingEncoder.js

@@ -181,7 +181,7 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
         else {
             const encoderName = codec === "h264" ? "libx264" : "libx265";
             args.push("-c:v", encoderName, "-preset", preset);
-            appendSoftwareEncoderThreadsArg(args);
+            appendSoftwareEncoderThreadsArg(args, encoderName);
             if (bitrate)
                 args.push("-b:v", bitrate);
             else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.189",
+  "version": "0.8.190-hdr.1",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.189",
-    "@hyperframes/parsers": "^0.8.189"
+    "@hyperframes/core": "^0.8.190-hdr.1",
+    "@hyperframes/parsers": "^0.8.190-hdr.1"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",