@hyperframes/engine 0.8.186 → 0.8.189

package/dist/index.d.ts

@@ -41,6 +41,7 @@ export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, type N
 export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, type CaptureSession, isTransientBrowserError, isMemoryExhaustionError, type BeforeCaptureHook, type DiscardWarmupInnerCapture, type StaticVerificationOutcome, VfxFailureError, waitForImagesReady, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, type CaptureFailureKind, type CaptureWorkerDiagnostic, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, type ChromeMemoryStats, } from "./services/chromeMemorySampler.js";
+export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
 export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, type BeginFrameResult, } from "./services/screenshotService.js";
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
 export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
@@ -57,6 +58,8 @@ 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";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";

package/dist/index.js

@@ -44,6 +44,7 @@ export { createCaptureSession, initializeSession, closeCaptureSession, captureFr
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
+export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
 export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, } from "./services/screenshotService.js";
 // ── Encoding ───────────────────────────────────────────────────────────────────
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
@@ -63,6 +64,8 @@ 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";
 export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, probeMediaProfile, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";

package/dist/services/aacEncode.js

@@ -57,6 +57,8 @@ export async function encodeAac(input, outputPath, totalDuration, { signal, time
             path: join(dir, `${k}.aac`),
         }));
         const results = await Promise.all(segments.map(({ trim, path }) => runFfmpeg([
+            "-cpuflags",
+            "0",
             "-i",
             input,
             "-af",

package/dist/services/audioFxRender.d.ts

@@ -107,6 +107,7 @@ export declare function applyAudioFxChain(inputWav: string, chain: HfAudioFxChai
     signal?: AbortSignal;
     automation?: HfAutomation;
     envelope?: AudioFxEnvelope;
+    inputGain?: number;
     streaming?: Partial<AudioFxStreamingLimits>;
 }): Promise<{
     path: string;

package/dist/services/audioFxRender.js

@@ -258,6 +258,11 @@ function applyEnvelopeToPlanes(planes, sampleRate, gainAt, startFrame = 0) {
             plane[frame] = (plane[frame] ?? 0) * gain;
     }
 }
+/** The clip's `data-volume`, ahead of the chain where an editor puts clip gain. */
+function applyInputGain(planes, gain = 1) {
+    if (gain !== 1)
+        applyEnvelopeToPlanes(planes, 1, () => gain);
+}
 const DEFAULT_STREAMING_LIMITS = {
     aboveBytes: 512 * 1024 * 1024,
     segmentSeconds: 300,
@@ -324,6 +329,7 @@ async function renderInSegments(openPage, inputWav, header, chain, outputWav, op
                 throw new AudioFxRenderError(`Audio FX cancelled for track ${options.trackId}`);
             }
             const planes = deinterleave(readFrames(inFd, header, seg.readFrom, seg.readTo), channels);
+            applyInputGain(planes, options.inputGain);
             // A fresh page per window, so the browser never holds more than one window of audio.
             const page = await openPage();
             let outPlanes;
@@ -397,6 +403,7 @@ export async function applyAudioFxChain(inputWav, chain, outputWav, options) {
     }
     const input = readWav(inputWav);
     const planes = deinterleave(input.samples, input.channels);
+    applyInputGain(planes, options.inputGain);
     // An empty track has nothing to process — and an OfflineAudioContext of zero
     // length throws, which is fatal for the WHOLE render rather than this track:
     // the error travels past the mixer's per-track failure collector. ffmpeg

package/dist/services/audioMixer.d.ts

@@ -18,11 +18,12 @@ export declare function buildTrackInputFilter(track: Pick<AudioTrack, "start" |
  * sampled, or the bake would quietly straighten it.
  *
  * Times come out in composition seconds, which is what the baker subtracts the
- * track start from. Returns null when the track has no volume lane.
+ * track start from. Values are `gainedVolume` of the track's `data-volume`.
+ * Returns null when the track has no volume lane.
  */
 export declare function volumeLaneKeyframes(automation: {
     lanes: HfAutomationLane[];
-}, trackStart: number, duration: number): AudioVolumeKeyframe[] | null;
+}, trackStart: number, duration: number, gain: number, gainAhead?: boolean): AudioVolumeKeyframe[] | null;
 /**
  * The top-level root's `data-fx-chain`. It belongs to the composition, not to a clip,
  * so `processCompositionAudio` takes it beside the tracks: a track the render adds
@@ -30,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

@@ -6,11 +6,11 @@ import { parseHTML } from "linkedom";
 import { extractAudioMetadata } from "../utils/ffprobe.js";
 import { isNotMediaPayload } from "../utils/notMediaPayload.js";
 import { urlInputArgs } from "../utils/urlInput.js";
-import { clampAudioGain } from "@hyperframes/core/audio-gain";
+import { clampAudioGain, clipGain } from "@hyperframes/core/audio-gain";
 import { clampFadesToDuration, readElementFades } from "@hyperframes/core/audio-fade";
 import { downloadToTemp, isHttpUrl, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
 import { DEFAULT_CONFIG } from "../config.js";
-import { formatFfmpegError, runFfmpeg } from "../utils/runFfmpeg.js";
+import { describeFfmpegFailure, runFfmpeg } from "../utils/runFfmpeg.js";
 import { encodeAac } from "./aacEncode.js";
 import { audioSubprocessEvidence } from "./audioFailureDiagnostic.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
@@ -18,8 +18,8 @@ import { resolveMediaElementSrc, resolveProjectRelativeSrc } from "./videoFrameE
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
 import { applyVolumeEnvelopeToWav } from "./audioVolumeEnvelope.js";
-import { HF_AUDIO_FX_ATTR, parseAudioFxChain, } from "@hyperframes/core/audio-fx";
-import { HF_AUDIO_AUTOMATION_ATTR, parseAutomation, resolveAutomation, sampleAutomationLane, VOLUME_TARGET, } from "@hyperframes/core/audio-automation";
+import { enabledAudioFxNodes, HF_AUDIO_FX_ATTR, parseAudioFxChain, } from "@hyperframes/core/audio-fx";
+import { gainedVolume, gainedVolumePoints, HF_AUDIO_AUTOMATION_ATTR, isBentSegment, volumeSegmentSampleCount, parseAutomation, resolveAutomation, sampleAutomationLane, VOLUME_TARGET, } from "@hyperframes/core/audio-automation";
 import { chainTailSeconds } from "@hyperframes/core/audio-fx-tail";
 import { isAudibleVideoElement, MEDIA_RENDER_ID_ATTR, normalizePlaybackRate, normalizeRateSpec, parseStrictFiniteTimingNumber, readElementRateSpec, readMediaStart, sourceTimeAt, timeAtSourceTime, } from "@hyperframes/core";
 import { readMasterFxChain, resolveAudioGroups } from "@hyperframes/core/audio-groups";
@@ -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);
@@ -315,7 +319,7 @@ function downloadFailure(error, elementId) {
         detail: boundedDetail(`Download failed for audio element ${elementId}: ${message}`),
     };
 }
-function ffmpegFailure(stage, result, elementId) {
+function ffmpegFailure(stage, result, timeoutMs, elementId) {
     const stderr = result.stderr ?? "";
     let reason = "ffmpeg_failed";
     let owner = "system";
@@ -351,13 +355,12 @@ function ffmpegFailure(stage, result, elementId) {
         retryable,
         elementId,
         subprocess: audioSubprocessEvidence(result),
-        detail: boundedDetail(result.error?.message
-            ? `${formatFfmpegError(result.exitCode, stderr)}: ${result.error.message}`
-            : formatFfmpegError(result.exitCode, stderr)),
+        detail: boundedDetail(`(ran ${result.durationMs} ms, limit ${timeoutMs} ms) ` +
+            (result.error?.message
+                ? `${describeFfmpegFailure(result, timeoutMs)}: ${result.error.message}`
+                : describeFfmpegFailure(result, timeoutMs))),
     };
 }
-/** Extra samples per second inside a segment the baker cannot draw straight. */
-const CURVED_SEGMENT_SAMPLES_PER_SEC = 30;
 /**
  * A volume lane as keyframes for the PCM baker.
  *
@@ -366,36 +369,38 @@ const CURVED_SEGMENT_SAMPLES_PER_SEC = 30;
  * sampled, or the bake would quietly straighten it.
  *
  * Times come out in composition seconds, which is what the baker subtracts the
- * track start from. Returns null when the track has no volume lane.
+ * track start from. Values are `gainedVolume` of the track's `data-volume`.
+ * Returns null when the track has no volume lane.
  */
-export function volumeLaneKeyframes(automation, trackStart, duration) {
+export function volumeLaneKeyframes(automation, trackStart, duration, gain, gainAhead = false) {
     const lane = automation.lanes.find((l) => l.target === VOLUME_TARGET);
     if (!lane || lane.points.length === 0)
         return null;
+    const points = gainedVolumePoints(lane, gain, gainAhead);
     const out = [];
     const push = (t, v) => {
         out.push({ time: trackStart + t, volume: v });
     };
     // The envelope holds its first value before the first point, rather than
     // falling back to `data-volume`.
-    const first = lane.points[0];
+    const first = points[0];
     if (first.t > 0)
         push(0, first.v);
-    for (let i = 0; i < lane.points.length; i += 1) {
-        const a = lane.points[i];
+    for (let i = 0; i < points.length; i += 1) {
+        const a = points[i];
         push(a.t, a.v);
-        const b = lane.points[i + 1];
-        if (!b || !a.curve)
+        const b = points[i + 1];
+        if (!b || !isBentSegment(a))
             continue;
-        const steps = Math.max(2, Math.ceil((b.t - a.t) * CURVED_SEGMENT_SAMPLES_PER_SEC));
+        const steps = volumeSegmentSampleCount(b.t - a.t);
         for (let k = 1; k < steps; k += 1) {
             const t = a.t + ((b.t - a.t) * k) / steps;
-            push(t, sampleAutomationLane(lane, t));
+            push(t, gainedVolume(sampleAutomationLane(lane, t), gain, gainAhead));
         }
     }
     // Hold the last value to the clip's end, so the baker does not ramp away
     // from it toward whatever it would otherwise assume.
-    const last = lane.points[lane.points.length - 1];
+    const last = points[points.length - 1];
     if (duration > last.t)
         push(duration, last.v);
     return out;
@@ -547,7 +552,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
             failure,
         };
     }
-    let failure = result.success ? undefined : ffmpegFailure(stage, result);
+    let failure = result.success ? undefined : ffmpegFailure(stage, result, ffmpegProcessTimeout);
     const probedLinkFailedToRead = readsUrl && (failure?.reason === "invalid_media" || failure?.reason === "ffmpeg_failed");
     if (failure && probedLinkFailedToRead) {
         failure = { ...failure, reason: "download_failed", owner: "system", retryable: true };
@@ -594,7 +599,9 @@ async function generateSilence(outputPath, duration, signal, config) {
             failure,
         };
     }
-    const failure = !result.success ? ffmpegFailure("silence", result) : undefined;
+    const failure = !result.success
+        ? ffmpegFailure("silence", result, ffmpegProcessTimeout)
+        : undefined;
     return {
         success: result.success,
         outputPath,
@@ -603,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);
@@ -732,7 +745,7 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
         };
     }
     if (!result.success) {
-        const failure = ffmpegFailure("mix", result);
+        const failure = ffmpegFailure("mix", result, ffmpegProcessTimeout);
         return {
             success: false,
             outputPath,
@@ -780,20 +793,21 @@ 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 });
-    const buildInputFilters = (ignoreKeyframes) => memberTracks.map((track, i) => {
+    const buildInputFilters = (ignoreKeyframes, padMembers) => memberTracks.map((track, i) => {
         const volumeFilter = buildVolumeExpression(track, ignoreKeyframes);
-        return buildTrackInputFilter(track, i, volumeFilter, totalDuration);
+        return buildTrackInputFilter(track, i, volumeFilter, totalDuration, padMembers);
     });
     const mixInputs = memberTracks.map((_, i) => `[a${i}]`).join("");
     const runOnce = async (useNormalize, ignoreKeyframes = false) => {
-        const inputFilters = buildInputFilters(ignoreKeyframes);
+        const inputFilters = buildInputFilters(ignoreKeyframes, !useNormalize);
+        const padUnitySumOnceToFilm = `[mixed];[mixed]apad,asetpts=N/SR/TB,atrim=0:${formatFilterNumber(totalDuration)}`;
         const mixFilter = useNormalize
-            ? `${mixInputs}amix=inputs=${memberTracks.length}:duration=longest:dropout_transition=0:normalize=0[out]`
+            ? `${mixInputs}amix=inputs=${memberTracks.length}:duration=longest:dropout_transition=0:normalize=0${padUnitySumOnceToFilm}[out]`
             : // Every member is padded and trimmed to totalDuration above, and
                 // dropout_transition=0 keeps all N inputs active for that whole span.
                 // amix's default normalize therefore divides by exactly N throughout;
@@ -868,11 +882,99 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
         }
     }
     if (signal?.aborted || !result.success) {
-        const failure = ffmpegFailure("mix", result);
+        const failure = ffmpegFailure("mix", result, ffmpegProcessTimeout);
         return { success: false, error: failure.detail, failure };
     }
     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.
@@ -893,7 +995,7 @@ async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, tota
         timeout: config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout,
     });
     if (!encoded.success) {
-        const failure = ffmpegFailure("mix", encoded);
+        const failure = ffmpegFailure("mix", encoded, config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout);
         return {
             success: false,
             outputPath,
@@ -1060,8 +1162,9 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             // 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.
+            const chain = element.fxChain ? parseAudioFxChain(element.fxChain) : undefined;
             const automation = element.automation
-                ? resolveAutomation(parseAutomation(element.automation), element.fxChain ? parseAudioFxChain(element.fxChain) : undefined)
+                ? 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
@@ -1070,9 +1173,13 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             // 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.
+            const gainBeforeFx = chain !== undefined && enabledAudioFxNodes(chain).length > 0;
             const laneKeyframes = automation
-                ? volumeLaneKeyframes(automation, element.start, element.end - element.start)
+                ? volumeLaneKeyframes(automation, element.start, element.end - element.start, element.volume ?? 1, gainBeforeFx)
                 : null;
+            const tweened = !laneKeyframes && (element.volumeKeyframes?.length ?? 0) > 0;
             const envelopeKeyframes = laneKeyframes ?? element.volumeKeyframes;
             const envelope = envelopeKeyframes && envelopeKeyframes.length > 0
                 ? {
@@ -1083,11 +1190,10 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 : null;
             let bakedEnvelope = false;
             let tailSeconds = 0;
-            if (element.fxChain) {
+            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.
-                const chain = parseAudioFxChain(element.fxChain);
                 // The rendered WAV is longer than the input by exactly this much, so
                 // the mix has to be told to let it through.
                 tailSeconds = chainTailSeconds(chain, automation ?? undefined);
@@ -1096,6 +1202,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                     signal: effectiveSignal,
                     ...(automation ? { automation } : {}),
                     ...(envelope ? { envelope } : {}),
+                    ...(gainBeforeFx ? { inputGain: clipGain(element.volume ?? 1, tweened) } : {}),
                 });
                 audioSrcPath = fxResult.path;
                 bakedEnvelope = fxResult.envelopeBaked;
@@ -1116,7 +1223,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                 mediaStart: element.mediaStart,
                 duration: element.end - element.start,
                 // Gain is already in the samples when baked, so mix at unity.
-                volume: bakedEnvelope ? 1.0 : (element.volume ?? 1.0),
+                volume: bakedEnvelope || (gainBeforeFx && !tweened) ? 1.0 : (element.volume ?? 1.0),
                 volumeKeyframes: bakedEnvelope ? undefined : (envelopeKeyframes ?? undefined),
                 ...(element.fadeIn ? { fadeIn: element.fadeIn } : {}),
                 ...(element.fadeOut ? { fadeOut: element.fadeOut } : {}),
@@ -1260,7 +1367,9 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             const automation = meta.automation
                 ? resolveAutomation(parseAutomation(meta.automation), meta.fxChain ? parseAudioFxChain(meta.fxChain) : undefined)
                 : null;
-            const laneKeyframes = automation ? volumeLaneKeyframes(automation, 0, totalDuration) : null;
+            const laneKeyframes = automation
+                ? volumeLaneKeyframes(automation, 0, totalDuration, meta.volume)
+                : null;
             const envelope = laneKeyframes && laneKeyframes.length > 0
                 ? { keyframes: laneKeyframes, trackStart: 0, baseVolume: meta.volume }
                 : null;

package/dist/services/chunkEncoder.js

@@ -5,6 +5,7 @@
  * Encodes captured frames into video using FFmpeg.
  * Supports CPU (libx264) and GPU encoding.
  */
+import { frameSequencePath } from "./extractedFrameIndex.js";
 import { closeSync, copyFileSync, existsSync, ftruncateSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, statSync, writeFileSync, writeSync, } from "fs";
 import { join, dirname, extname } from "path";
 import { DEFAULT_CONFIG } from "../config.js";
@@ -16,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" },
@@ -212,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
@@ -396,7 +399,7 @@ export async function encodeFramesFromDir(framesDir, framePattern, outputPath, o
     if (options.useGpu) {
         gpuEncoder = await getCachedGpuEncoder();
     }
-    const inputPath = join(framesDir, framePattern);
+    const inputPath = frameSequencePath(framesDir, framePattern);
     const inputArgs = ["-framerate", fpsToFfmpegArg(options.fps), "-i", inputPath];
     const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder);
     const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
@@ -534,7 +537,7 @@ export async function encodeFramesChunkedConcat(framesDir, framePattern, outputP
                 ? ".mov"
                 : ".mp4";
         const chunkPath = join(chunkDir, `chunk_${String(i).padStart(4, "0")}${ext}`);
-        const inputPath = join(framesDir, framePattern);
+        const inputPath = frameSequencePath(framesDir, framePattern);
         const inputArgs = [
             "-framerate",
             fpsToFfmpegArg(options.fps),

package/dist/services/extractedFrameIndex.d.ts

@@ -1,5 +1,6 @@
 export type ExtractedFrameFormat = "jpg" | "png";
 export declare const FRAME_FILENAME_PREFIX = "frame_";
+export declare function frameSequencePath(dir: string, framePattern: string): string;
 export declare class ExtractedFrameSequenceError extends Error {
     constructor(message: string);
 }

package/dist/services/extractedFrameIndex.js

@@ -1,6 +1,9 @@
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
 export const FRAME_FILENAME_PREFIX = "frame_";
+export function frameSequencePath(dir, framePattern) {
+    return join(dir.replaceAll("%", "%%"), framePattern);
+}
 export class ExtractedFrameSequenceError extends Error {
     constructor(message) {
         super(message);

package/dist/services/mediaRenderIdBridge.d.ts

@@ -4,14 +4,14 @@
  * The pipeline addresses media by id, but element ids are only unique within
  * one composition FILE and the render document inlines many, so
  * `document.getElementById` silently resolves duplicates to whichever element
- * comes first. The producer stamps a document-unique `data-hf-render-id`
+ * comes first. The compiler stamps a document-unique `data-hf-render-id`
  * (core's mediaRenderIds.ts); these helpers are the single place that knows to
  * prefer it, so every capture stage addresses the same element.
  *
  * Installed via `evaluateOnNewDocument` so it exists before any page script.
- * Every call site keeps a `getElementById` fallback for documents that were
- * never compiled by the producer (snapshot, check, and direct engine callers),
- * where the authored id already is the identity.
+ * Every call site keeps a `getElementById` fallback for uncompiled documents
+ * passed directly to the engine. CLI captures and producer renders both carry
+ * document-unique IDs from the compiler.
  *
  * `__hfMediaId` mirrors core's `readMediaRenderId`, which is the definition of
  * this rule; the copy exists only because code serialized into `page.evaluate`

package/dist/services/mediaRenderIdBridge.js

@@ -4,14 +4,14 @@
  * The pipeline addresses media by id, but element ids are only unique within
  * one composition FILE and the render document inlines many, so
  * `document.getElementById` silently resolves duplicates to whichever element
- * comes first. The producer stamps a document-unique `data-hf-render-id`
+ * comes first. The compiler stamps a document-unique `data-hf-render-id`
  * (core's mediaRenderIds.ts); these helpers are the single place that knows to
  * prefer it, so every capture stage addresses the same element.
  *
  * Installed via `evaluateOnNewDocument` so it exists before any page script.
- * Every call site keeps a `getElementById` fallback for documents that were
- * never compiled by the producer (snapshot, check, and direct engine callers),
- * where the authored id already is the identity.
+ * Every call site keeps a `getElementById` fallback for uncompiled documents
+ * passed directly to the engine. CLI captures and producer renders both carry
+ * document-unique IDs from the compiler.
  *
  * `__hfMediaId` mirrors core's `readMediaRenderId`, which is the definition of
  * this rule; the copy exists only because code serialized into `page.evaluate`

package/dist/services/screenshotService.js

@@ -556,6 +556,7 @@ async function injectResolvedVideoFramesBatch(page, updates) {
     async (items, visualProperties, colorGradingSourceHiddenAttr) => {
         const injectedIds = [];
         const pendingDecodes = [];
+        const imagesToPublish = [];
         const replacementLayoutProperties = new Set([
             "width",
             "height",
@@ -692,6 +693,8 @@ async function injectResolvedVideoFramesBatch(page, updates) {
             img.style.objectFit = computedStyle.objectFit;
             img.style.objectPosition = computedStyle.objectPosition;
             img.style.zIndex = computedStyle.zIndex;
+            // Publish after full decode so raster cannot race it with a reduced JPEG decode.
+            img.style.setProperty("visibility", "hidden", "important");
             img.decoding = "sync";
             if (img.getAttribute("src") !== item.dataUri) {
                 if (item.crossOrigin)
@@ -705,7 +708,7 @@ async function injectResolvedVideoFramesBatch(page, updates) {
                 }));
             }
             img.style.opacity = String(computedOpacity);
-            img.style.visibility = "visible";
+            imagesToPublish.push(img);
             // Hide the native <video> with visibility only — never clobber inline
             // opacity, so subsequent reads (and queryElementStacking) see the real
             // GSAP-controlled value.
@@ -716,6 +719,8 @@ async function injectResolvedVideoFramesBatch(page, updates) {
         if (pendingDecodes.length > 0) {
             await Promise.all(pendingDecodes);
         }
+        for (const img of imagesToPublish)
+            img.style.visibility = "visible";
         if (injectedIds.length > 0) {
             const redraw = window
                 .__hf?.colorGrading?.redraw;
@@ -757,7 +762,7 @@ export async function syncVideoFrameVisibility(page, activeVideoIds) {
             const img = video.nextElementSibling;
             const hasImg = img && img.classList.contains("__render_frame__");
             const ancestorHidden = isVisualAncestorHidden(video);
-            const visible = active.has(video.id) && !ancestorHidden;
+            const visible = active.has(window.__hfMediaId?.(video) || video.id) && !ancestorHidden;
             if (visible) {
                 // Active video: show injected <img>, hide native <video>.
                 // Do NOT clobber inline opacity here — GSAP-controlled opacity must

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

@@ -27,7 +27,7 @@ import { isFfmpegFilterAvailable } from "../utils/psnrFilterAvailability.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import { FRAME_FILENAME_PREFIX, gcExtractionCache, gcSweepDue, lookupCacheEntry, partialCacheEntryDir, publishCacheEntry, readContentSha256, readKeyStat, rehydrateCacheEntry, touchCacheEntry, } from "./extractionCache.js";
-import { framePathsFromDirectory } from "./extractedFrameIndex.js";
+import { framePathsFromDirectory, frameSequencePath } from "./extractedFrameIndex.js";
 export { resolveProjectRelativeSrc };
 /**
  * The single source of truth for the source-video frame-extraction allow-list.
@@ -571,7 +571,7 @@ outputDirOverride) {
     }
     const format = resolveFrameFormat(metadata, options.format);
     const framePattern = `${FRAME_FILENAME_PREFIX}%05d.${format}`;
-    const outputPattern = join(videoOutputDir, framePattern);
+    const outputPattern = frameSequencePath(videoOutputDir, framePattern);
     // Forced-SDR extraction tone-maps HDR with zscale, the Studio proxy policy. A macOS ffmpeg
     // without zscale falls back to VideoToolbox, whose frames stay HDR and are tone-mapped by
     // Chrome instead (darker), and the render warns once.
@@ -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.186",
+  "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.186",
-    "@hyperframes/parsers": "^0.8.186"
+    "@hyperframes/core": "^0.8.189",
+    "@hyperframes/parsers": "^0.8.189"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",