@hyperframes/engine 0.8.188 → 0.8.190

package/dist/index.d.ts

@@ -58,6 +58,7 @@ export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndices
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";
+export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThreads.js";
 export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js";
 export type { PageMotionBlurOff } from "./types.js";

package/dist/index.js

@@ -64,6 +64,7 @@ export { createFileServer, } from "./services/fileServer.js";
 // ── Utilities ──────────────────────────────────────────────────────────────────
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";
+export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThreads.js";
 export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";

package/dist/services/audioMixer.d.ts

@@ -31,6 +31,8 @@ export declare function volumeLaneKeyframes(automation: {
  */
 export declare function parseMasterFxChain(html: string): string | undefined;
 export declare function parseAudioElements(html: string): AudioElement[];
+/** Tracks per ffmpeg graph; a larger mix is summed in stages, so there is no cap on the total. */
+export declare const MAX_MIX_INPUTS = 96;
 export declare function processCompositionAudio(elements: AudioElement[], baseDir: string, workDir: string, outputPath: string, totalDuration: number, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">> & {
     /** Serialised master bus chain, from `parseMasterFxChain`. */
     masterFxChain?: string;

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
@@ -273,7 +277,11 @@ function boundedDetail(message, maxLength = 2_000) {
         .replace(/\bfile:\/\/[^\s"'<>]+/gi, "<redacted-path>")
         .replace(/\b[A-Za-z]:[\\/].+?(?=:\s[A-Z]|\s(?:ENOENT|EACCES|EPERM)\b|\r?$)/gm, "<redacted-path>")
         .replace(/(^|[\s"'(])\/.+?(?=:\s[A-Z]|\s(?:ENOENT|EACCES|EPERM)\b|\r?$)/gm, "$1<redacted-path>");
-    return redacted.length <= maxLength ? redacted : `${redacted.slice(0, maxLength - 1)}…`;
+    // Keep both ends: the head names the failure, the tail holds ffmpeg's last words.
+    const head = Math.floor(maxLength / 4);
+    return redacted.length <= maxLength
+        ? redacted
+        : `${redacted.slice(0, head)}…${redacted.slice(-(maxLength - head - 1))}`;
 }
 function probeFailure(message, elementId) {
     const unavailable = /(?:not found|ENOENT|spawn)/i.test(message);
@@ -351,9 +359,10 @@ function ffmpegFailure(stage, result, timeoutMs, elementId) {
         retryable,
         elementId,
         subprocess: audioSubprocessEvidence(result),
-        detail: boundedDetail(result.error?.message
-            ? `${describeFfmpegFailure(result, timeoutMs)}: ${result.error.message}`
-            : describeFfmpegFailure(result, timeoutMs)),
+        detail: boundedDetail(`(ran ${result.durationMs} ms, limit ${timeoutMs} ms) ` +
+            (result.error?.message
+                ? `${describeFfmpegFailure(result, timeoutMs)}: ${result.error.message}`
+                : describeFfmpegFailure(result, timeoutMs))),
     };
 }
 /**
@@ -605,8 +614,14 @@ async function generateSilence(outputPath, duration, signal, config) {
         failure,
     };
 }
-async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config) {
-    const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+/** A mix graph's work grows with the film length (about 11 ms per film second at 96 inputs); so does its deadline. */
+const MIX_TIMEOUT_MS_PER_FILM_SECOND = 100;
+function mixProcessTimeout(config, totalDuration) {
+    const configured = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+    return Math.max(configured, Math.ceil(totalDuration * MIX_TIMEOUT_MS_PER_FILM_SECOND));
+}
+async function mixAudioTracksFlat(tracks, outputPath, totalDuration, signal, config) {
+    const ffmpegProcessTimeout = mixProcessTimeout(config, totalDuration);
     const masterOutputGain = config?.audioGain ?? DEFAULT_CONFIG.audioGain;
     if (tracks.length === 0) {
         const result = await generateSilence(outputPath, totalDuration, signal, config);
@@ -782,8 +797,8 @@ function groupNormalizeOptionUnsupported(stderr) {
  * compensation at all and is preferred; the manual per-own-count fallback
  * only runs when this ffmpeg build's `amix` rejects the option.
  */
-async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal, config) {
-    const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
+async function mixGroupMembersFlat(memberTracks, outputPath, totalDuration, signal, config) {
+    const ffmpegProcessTimeout = mixProcessTimeout(config, totalDuration);
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
@@ -876,6 +891,94 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
     }
     return { success: true, degradedAutomation };
 }
+/** Tracks per ffmpeg graph; a larger mix is summed in stages, so there is no cap on the total. */
+export const MAX_MIX_INPUTS = 96;
+/** Unity-sum `tracks` (the group gain law) slice by slice into one float WAV, with few full-length files at once. */
+async function sumInSlices(tracks, scratchDir, totalDuration, signal, config) {
+    const wavTrack = (id, srcPath) => ({
+        id,
+        srcPath,
+        start: 0,
+        end: totalDuration,
+        mediaStart: 0,
+        duration: totalDuration,
+        volume: 1,
+    });
+    let running = null;
+    let degradedAutomation = false;
+    for (let at = 0; at < tracks.length; at += MAX_MIX_INPUTS) {
+        const id = `sum-${at / MAX_MIX_INPUTS}`;
+        const slicePath = join(scratchDir, `${id}-slice.wav`);
+        const slice = await mixGroupMembersFlat(tracks.slice(at, at + MAX_MIX_INPUTS), slicePath, totalDuration, signal, config);
+        if (!slice.success)
+            return slice;
+        degradedAutomation ||= slice.degradedAutomation === true;
+        if (!running) {
+            running = wavTrack(id, slicePath);
+            continue;
+        }
+        const foldedPath = join(scratchDir, `${id}.wav`);
+        const folded = await mixGroupMembersFlat([running, wavTrack(`${id}-slice`, slicePath)], foldedPath, totalDuration, signal, config);
+        rmSync(running.srcPath, { force: true });
+        rmSync(slicePath, { force: true });
+        if (!folded.success)
+            return folded;
+        running = wavTrack(id, foldedPath);
+    }
+    if (!running)
+        throw new Error("[audioMixer] sumInSlices needs at least one track");
+    return { success: true, track: running, degradedAutomation };
+}
+async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal, config) {
+    if (memberTracks.length <= MAX_MIX_INPUTS) {
+        return mixGroupMembersFlat(memberTracks, outputPath, totalDuration, signal, config);
+    }
+    mkdirSync(dirname(outputPath), { recursive: true });
+    const scratchDir = mkdtempSync(join(dirname(outputPath), ".mix-batches-"));
+    try {
+        const summed = await sumInSlices(memberTracks, scratchDir, totalDuration, signal, config);
+        if (!summed.success)
+            return summed;
+        renameSync(summed.track.srcPath, outputPath);
+        return { success: true, degradedAutomation: summed.degradedAutomation };
+    }
+    finally {
+        rmSync(scratchDir, { recursive: true, force: true });
+    }
+}
+async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config) {
+    if (tracks.length <= MAX_MIX_INPUTS) {
+        return mixAudioTracksFlat(tracks, outputPath, totalDuration, signal, config);
+    }
+    mkdirSync(dirname(outputPath), { recursive: true });
+    const scratchDir = mkdtempSync(join(dirname(outputPath), ".mix-batches-"));
+    try {
+        const summed = await sumInSlices(tracks, scratchDir, totalDuration, signal, config);
+        if (!summed.success) {
+            return {
+                success: false,
+                outputPath,
+                durationMs: 0,
+                tracksProcessed: 0,
+                error: summed.error,
+                failures: [summed.failure],
+            };
+        }
+        const mixed = await mixAudioTracksFlat([summed.track], outputPath, totalDuration, signal, config);
+        return mixed.success
+            ? {
+                ...mixed,
+                tracksProcessed: tracks.length,
+                error: summed.degradedAutomation
+                    ? "Volume automation exceeded this ffmpeg build's expression limits; rendered at base volume"
+                    : mixed.error,
+            }
+            : mixed;
+    }
+    finally {
+        rmSync(scratchDir, { recursive: true, force: true });
+    }
+}
 /**
  * Sum the tracks to a float WAV, run the master chain (if any) over the sum, then AAC-encode.
  * Groups are already folded into `tracks`, and the sum stays float until the encoder.
@@ -944,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",
@@ -990,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",
@@ -1019,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") {
@@ -1058,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)
@@ -1092,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,
@@ -1108,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);
             }
@@ -1148,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

@@ -17,6 +17,7 @@ import { describeFfmpegFailure, ffmpegStatsReader, formatFfmpegError, isExternal
 import { extractAudioMetadata } from "../utils/ffprobe.js";
 import { fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core";
 import { appendVp9CpuUsedArg } from "./vp9Options.js";
+import { appendSoftwareEncoderThreadsArg } from "./softwareEncoderThreads.js";
 import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
 export const ENCODER_PRESETS = {
     draft: { preset: "ultrafast", quality: 28, codec: "h264" },
@@ -213,6 +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);
             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

@@ -0,0 +1,2 @@
+/** 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;

package/dist/services/softwareEncoderThreads.js

@@ -0,0 +1,5 @@
+import { availableParallelism } from "node:os";
+/** 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))));
+}

package/dist/services/streamingEncoder.js

@@ -28,6 +28,7 @@ import { SDR_CAPTURE_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "..
 import { DEFAULT_CONFIG } from "../config.js";
 import { fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core";
 import { appendVp9CpuUsedArg } from "./vp9Options.js";
+import { appendSoftwareEncoderThreadsArg } from "./softwareEncoderThreads.js";
 import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
 import { appendLockedGopArgs, lockedGopCodecParams, resolveLockedGopSize } from "./chunkEncoder.js";
 export function createFrameReorderBuffer(startFrame, endFrame) {
@@ -180,6 +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);
             if (bitrate)
                 args.push("-b:v", bitrate);
             else

package/dist/services/videoFrameExtractor.js

@@ -946,15 +946,10 @@ export function resolveVideoExtractionWindow(video, metadata, timelineEnd) {
 export function resolveVideoExtractionDuration(video, metadata, timelineEnd) {
     return resolveVideoExtractionWindow(video, metadata, timelineEnd).durationSeconds;
 }
-/**
- * Codecs whose bitstream is allowed to carry an alpha channel. Default the
- * extraction path to PNG output for these regardless of `metadata.hasAlpha`
- * so a missed sidecar tag doesn't silently strip transparency. Opaque content
- * encoded in one of these codecs pays a small file-size cost on the cached
- * frames but stays correct on the rare case where alpha IS present and the
- * tag was missed.
- */
+/** Codecs whose bitstream can carry alpha: decoded with the alpha-aware decoder whether or not a tag says so. */
 const ALPHA_CAPABLE_CODECS = new Set(["vp9", "vp8", "prores"]);
+/** Their alpha rides a side channel ffprobe can miss, so frames stay PNG; ProRes alpha shows in its pixel format. */
+const SIDECAR_ALPHA_CODECS = new Set(["vp9", "vp8"]);
 export function codecMayHaveAlpha(codec) {
     return ALPHA_CAPABLE_CODECS.has((codec ?? "").toLowerCase());
 }
@@ -962,7 +957,7 @@ export function decoderForCodec(codec) {
     return alphaDecoderFor(codec) ?? (codec ?? "").toLowerCase();
 }
 export function resolveFrameFormat(metadata, requested) {
-    if (metadata.hasAlpha || codecMayHaveAlpha(metadata.videoCodec))
+    if (metadata.hasAlpha || SIDECAR_ALPHA_CODECS.has((metadata.videoCodec ?? "").toLowerCase()))
         return "png";
     if (requested === "png" || requested === "jpg")
         return requested;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.188",
+  "version": "0.8.190",
   "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.188",
-    "@hyperframes/parsers": "^0.8.188"
+    "@hyperframes/core": "^0.8.190",
+    "@hyperframes/parsers": "^0.8.190"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",