@hyperframes/engine 0.8.188 → 0.8.189

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

@@ -273,7 +273,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 +355,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 +610,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 +793,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 +887,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.

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/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.189",
   "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.189",
+    "@hyperframes/parsers": "^0.8.189"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",