@hyperframes/engine 0.8.148 → 0.8.150

package/dist/index.d.ts

@@ -49,7 +49,7 @@ export { parseVideoElements, parseImageElements, extractVideoFramesRange, extrac
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
-export { MIXED_AUDIO_FILENAME, parseAudioElements, processCompositionAudio, } from "./services/audioMixer.js";
+export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, } from "./services/audioMixer.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioTrack, AudioVolumeKeyframe, MixResult, } from "./services/audioMixer.types.js";
 export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type ParallelProgress, } from "./services/parallelCoordinator.js";

package/dist/index.js

@@ -53,7 +53,7 @@ export { parseVideoElements, parseImageElements, extractVideoFramesRange, extrac
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
-export { MIXED_AUDIO_FILENAME, parseAudioElements, processCompositionAudio, } from "./services/audioMixer.js";
+export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, } from "./services/audioMixer.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 // ── Parallel rendering ─────────────────────────────────────────────────────────
 export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, } from "./services/parallelCoordinator.js";

package/dist/services/audioFxRender.d.ts

@@ -25,6 +25,20 @@ interface WavData {
      *  the output can be written back in the same format — see `writeWav`. */
     float: boolean;
 }
+/** Where a WAV's samples sit, read from its head alone. */
+export interface WavHeader {
+    format: number;
+    channels: number;
+    sampleRate: number;
+    bits: number;
+    float: boolean;
+    dataOffset: number;
+    dataBytes: number;
+}
+/** A declared size of 0 or 0xFFFFFFFF (live-written, or past 4 GiB), or one past the end, means "to the end"; both WAV readers use it. */
+export declare function resolveDataBytes(declared: number, availableBytes: number): number;
+/** The header of `path`, or null when the head holds no readable `fmt `/`data` pair. */
+export declare function readWavHeader(path: string): WavHeader | null;
 export declare function readWav(path: string): WavData;
 /**
  * Write interleaved samples, preserving the channel count.
@@ -44,6 +58,33 @@ export declare function readWav(path: string): WavData;
  * baker reads float too; before that it was not.
  */
 export declare function writeWav(path: string, samples: Float32Array, sampleRate: number, channels?: number, float?: boolean): void;
+/** Inputs over `aboveBytes` render in windows: Node reads no file past 2 GiB whole, and the page would hold it twice. */
+export interface AudioFxStreamingLimits {
+    aboveBytes: number;
+    segmentSeconds: number;
+    /** Audio rendered ahead of each window and discarded; the least, when the chain needs more. */
+    prerollSeconds: number;
+    /** The most pre-roll a chain's own memory can ask for. */
+    maxPrerollSeconds: number;
+    /** Audio rendered after each window and discarded, for look-ahead. */
+    postrollSeconds: number;
+}
+export interface AudioFxSegment {
+    /** The frames this window contributes to the output. */
+    keepFrom: number;
+    keepTo: number;
+    /** The frames rendered to produce them. */
+    readFrom: number;
+    readTo: number;
+    last: boolean;
+}
+/** Tile `totalFrames` into windows that each carry their pre/post-roll. */
+export declare function planAudioFxSegments(totalFrames: number, sampleRate: number, limits: AudioFxStreamingLimits): AudioFxSegment[];
+type AudioFxEnvelope = {
+    keyframes: AudioVolumeKeyframe[];
+    trackStart: number;
+    baseVolume: number;
+};
 /**
  * Run a chain over `inputWav`, writing `outputWav`. Resolves to the path to use
  * downstream — `outputWav` when the chain did something, `inputWav` untouched
@@ -65,11 +106,8 @@ export declare function applyAudioFxChain(inputWav: string, chain: HfAudioFxChai
     trackId: string;
     signal?: AbortSignal;
     automation?: HfAutomation;
-    envelope?: {
-        keyframes: AudioVolumeKeyframe[];
-        trackStart: number;
-        baseVolume: number;
-    };
+    envelope?: AudioFxEnvelope;
+    streaming?: Partial<AudioFxStreamingLimits>;
 }): Promise<{
     path: string;
     envelopeBaked: boolean;

package/dist/services/audioFxRender.js

@@ -11,7 +11,7 @@
  * dynamics processors and the modulated delays) have no filter that behaves the
  * same way, so preview would quietly stop predicting the render.
  */
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -21,6 +21,7 @@ import { serializeAutomation } from "@hyperframes/core/audio-automation";
 import { acquireBrowser } from "./browserManager.js";
 import { createEnvelopeWalker } from "./audioVolumeEnvelope.js";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";
+import { windowPrerollSeconds } from "./audioFxWarmup.js";
 export class AudioFxRenderError extends Error {
     constructor(message) {
         super(message);
@@ -36,6 +37,8 @@ export class AudioFxRenderError extends Error {
 function readWavChunks(buf) {
     const head = { format: 1, channels: 1, sampleRate: 48000, bits: 16 };
     let data;
+    let dataBody;
+    let dataSize;
     for (const { id, body, size } of riffChunks(buf)) {
         if (id === "fmt ") {
             const format = wavFormatTag(buf, body, size);
@@ -47,7 +50,9 @@ function readWavChunks(buf) {
             head.bits = buf.readUInt16LE(body + 14);
         }
         else if (id === "data") {
-            data = buf.subarray(body, Math.min(buf.length, body + size));
+            data = buf.subarray(body, body + resolveDataBytes(size, buf.length - body));
+            dataBody = body;
+            dataSize = size;
             // The payload is the rest of the file for anything the mixer writes, and
             // reading past it buys nothing: `fmt ` precedes `data` in every WAV these
             // steps produce, and the alternative is walking a several-hundred-megabyte
@@ -55,7 +60,43 @@ function readWavChunks(buf) {
             break;
         }
     }
-    return { ...head, data };
+    return { ...head, data, dataBody, dataSize };
+}
+/** The most `readFileSync` returns in one call. */
+const MAX_WHOLE_FILE_BYTES = 2 ** 31 - 1;
+const HEADER_PROBE_BYTES = 64 * 1024;
+/** A declared size of 0 or 0xFFFFFFFF (live-written, or past 4 GiB), or one past the end, means "to the end"; both WAV readers use it. */
+export function resolveDataBytes(declared, availableBytes) {
+    return declared === 0 || declared === 0xffffffff
+        ? availableBytes
+        : Math.min(declared, availableBytes);
+}
+/** The header of `path`, or null when the head holds no readable `fmt `/`data` pair. */
+export function readWavHeader(path) {
+    const fd = openSync(path, "r");
+    try {
+        const head = Buffer.alloc(HEADER_PROBE_BYTES);
+        const read = readSync(fd, head, 0, head.length, 0);
+        const buf = head.subarray(0, read);
+        if (buf.length < 44 || buf.toString("ascii", 0, 4) !== "RIFF")
+            return null;
+        const { format, channels, sampleRate, bits, dataBody, dataSize } = readWavChunks(buf);
+        if (dataBody === undefined || dataSize === undefined)
+            return null;
+        const dataBytes = resolveDataBytes(dataSize, statSync(path).size - dataBody);
+        return {
+            format,
+            channels,
+            sampleRate,
+            bits,
+            float: format === 3 && bits === 32,
+            dataOffset: dataBody,
+            dataBytes,
+        };
+    }
+    finally {
+        closeSync(fd);
+    }
 }
 export function readWav(path) {
     const buf = readFileSync(path);
@@ -95,30 +136,11 @@ function decodeSamples(data, format, bits, path) {
     }
     throw new AudioFxRenderError(`Unsupported WAV format ${format}/${bits}-bit: ${path}`);
 }
-/**
- * Write interleaved samples, preserving the channel count.
- *
- * 16-bit by default rather than the float32 this used to emit: the very next
- * step in the mixer bakes the volume envelope into the samples, and that baker
- * accepted only 16-bit PCM. Emitting float meant enabling any effect silently
- * downgraded a track's volume automation to the ffmpeg expression path, which is
- * capped at 32 straight segments — so a curved envelope was quantised and a
- * dense one could fall back to rendering at base volume.
- *
- * `float` opts back out, for the ONE input that needs it: a group sub-mix. Its
- * members sum at unity, so the sum can legitimately exceed full scale, and the
- * group's fader is applied downstream — clamping here handed that headroom back
- * one step before the thing that was going to reduce it, which is the same bug
- * the float intermediate exists to avoid. Safe now only because the envelope
- * baker reads float too; before that it was not.
- */
-export function writeWav(path, samples, sampleRate, channels = 1, float = false) {
-    const n = samples.length;
+function wavHeader(bytes, sampleRate, channels, float) {
     const bytesPerSample = float ? 4 : 2;
-    const bytes = n * bytesPerSample;
-    const buf = Buffer.alloc(44 + bytes);
+    const buf = Buffer.alloc(44);
     buf.write("RIFF", 0, "ascii");
-    buf.writeUInt32LE(36 + bytes, 4);
+    buf.writeUInt32LE(Math.min(0xffffffff, 36 + bytes), 4);
     buf.write("WAVE", 8, "ascii");
     buf.write("fmt ", 12, "ascii");
     buf.writeUInt32LE(16, 16);
@@ -129,17 +151,44 @@ export function writeWav(path, samples, sampleRate, channels = 1, float = false)
     buf.writeUInt16LE(channels * bytesPerSample, 32);
     buf.writeUInt16LE(float ? 32 : 16, 34);
     buf.write("data", 36, "ascii");
-    buf.writeUInt32LE(bytes, 40);
+    buf.writeUInt32LE(Math.min(0xffffffff, bytes), 40);
+    return buf;
+}
+function encodeSamples(samples, float) {
+    const n = samples.length;
+    const buf = Buffer.alloc(n * (float ? 4 : 2));
     for (let i = 0; i < n; i++) {
         if (float) {
-            buf.writeFloatLE(samples[i] ?? 0, 44 + i * 4);
+            buf.writeFloatLE(samples[i] ?? 0, i * 4);
             continue;
         }
         // Clamp before scaling: a limiter set to 0 dB or a resonant filter can push
         // past full scale, and wrapping would turn that into a click.
         const v = Math.max(-1, Math.min(1, samples[i] ?? 0));
-        buf.writeInt16LE(Math.round(v * 32767), 44 + i * 2);
+        buf.writeInt16LE(Math.round(v * 32767), i * 2);
     }
+    return buf;
+}
+/**
+ * Write interleaved samples, preserving the channel count.
+ *
+ * 16-bit by default rather than the float32 this used to emit: the very next
+ * step in the mixer bakes the volume envelope into the samples, and that baker
+ * accepted only 16-bit PCM. Emitting float meant enabling any effect silently
+ * downgraded a track's volume automation to the ffmpeg expression path, which is
+ * capped at 32 straight segments — so a curved envelope was quantised and a
+ * dense one could fall back to rendering at base volume.
+ *
+ * `float` opts back out, for the ONE input that needs it: a group sub-mix. Its
+ * members sum at unity, so the sum can legitimately exceed full scale, and the
+ * group's fader is applied downstream — clamping here handed that headroom back
+ * one step before the thing that was going to reduce it, which is the same bug
+ * the float intermediate exists to avoid. Safe now only because the envelope
+ * baker reads float too; before that it was not.
+ */
+export function writeWav(path, samples, sampleRate, channels = 1, float = false) {
+    const body = encodeSamples(samples, float);
+    const buf = Buffer.concat([wavHeader(body.length, sampleRate, channels, float), body]);
     // lgtm[js/insecure-temporary-file] — `path` is always inside a directory the
     // caller made with `mkdtempSync`, never a name assembled directly under
     // `tmpdir()`. Both routes here are covered: the browser host page writes into
@@ -201,14 +250,112 @@ const TRANSFER_BYTES = 8 * 1024 * 1024;
  * moves forward, so restarting each channel at t=0 would hand the second one
  * the tail gain for its whole length.
  */
-function applyEnvelopeToPlanes(planes, sampleRate, gainAt) {
+function applyEnvelopeToPlanes(planes, sampleRate, gainAt, startFrame = 0) {
     const frames = planes[0]?.length ?? 0;
     for (let frame = 0; frame < frames; frame += 1) {
-        const gain = gainAt(frame / sampleRate);
+        const gain = gainAt((startFrame + frame) / sampleRate);
         for (const plane of planes)
             plane[frame] = (plane[frame] ?? 0) * gain;
     }
 }
+const DEFAULT_STREAMING_LIMITS = {
+    aboveBytes: 512 * 1024 * 1024,
+    segmentSeconds: 300,
+    prerollSeconds: 10,
+    maxPrerollSeconds: 300,
+    postrollSeconds: 1,
+};
+/** Frames the audio graph processes at a time; a window starting on one sees the same blocks a whole render does. */
+const RENDER_QUANTUM = 128;
+/** Tile `totalFrames` into windows that each carry their pre/post-roll. */
+export function planAudioFxSegments(totalFrames, sampleRate, limits) {
+    const step = Math.max(1, Math.round(limits.segmentSeconds * sampleRate));
+    const pre = Math.round(limits.prerollSeconds * sampleRate);
+    const post = Math.round(limits.postrollSeconds * sampleRate);
+    const segments = [];
+    for (let keepFrom = 0; keepFrom < totalFrames; keepFrom += step) {
+        const keepTo = Math.min(totalFrames, keepFrom + step);
+        segments.push({
+            keepFrom,
+            keepTo,
+            readFrom: Math.max(0, Math.floor((keepFrom - pre) / RENDER_QUANTUM) * RENDER_QUANTUM),
+            readTo: Math.min(totalFrames, keepTo + post),
+            last: keepTo === totalFrames,
+        });
+    }
+    return segments;
+}
+function readFrames(fd, header, from, to) {
+    const frameBytes = (header.channels * header.bits) / 8;
+    const data = Buffer.alloc((to - from) * frameBytes);
+    for (let filled = 0; filled < data.length;) {
+        const n = readSync(fd, data, filled, data.length - filled, header.dataOffset + from * frameBytes + filled);
+        if (n === 0)
+            break;
+        filled += n;
+    }
+    return decodeSamples(data, header.format, header.bits, "streamed input");
+}
+/** A chain remembers longer than the floor: size the pre-roll to its slowest state, up to the cap. */
+function chainPrerollSeconds(chain, limits, trackId) {
+    const { seconds, capped } = windowPrerollSeconds(chain, limits.prerollSeconds, limits.maxPrerollSeconds);
+    if (capped) {
+        console.warn(`Audio FX for track ${trackId}: the chain remembers longer than the ${limits.maxPrerollSeconds}s pre-roll cap, so its oldest repeats are cut at window seams`);
+    }
+    return seconds;
+}
+async function renderInSegments(openPage, inputWav, header, chain, outputWav, options, limits) {
+    const { sampleRate, channels, float } = header;
+    const totalFrames = Math.floor(header.dataBytes / ((channels * header.bits) / 8));
+    const gainAt = envelopeWalkerFor(options.envelope);
+    const prerollSeconds = chainPrerollSeconds(chain, limits, options.trackId);
+    const inFd = openSync(inputWav, "r");
+    let outFd;
+    try {
+        // Same directory rule as writeWav: the caller's mkdtemp work dir.
+        outFd = openSync(outputWav, "w");
+        writeSync(outFd, wavHeader(0, sampleRate, channels, float));
+        let written = 0;
+        for (const seg of planAudioFxSegments(totalFrames, sampleRate, {
+            ...limits,
+            prerollSeconds,
+        })) {
+            if (options.signal?.aborted) {
+                throw new AudioFxRenderError(`Audio FX cancelled for track ${options.trackId}`);
+            }
+            const planes = deinterleave(readFrames(inFd, header, seg.readFrom, seg.readTo), channels);
+            // A fresh page per window, so the browser never holds more than one window of audio.
+            const page = await openPage();
+            let outPlanes;
+            try {
+                await sendPlanesToPage(page, planes);
+                outPlanes = await readPlanesFromPage(page, await renderPlanesInPage(page, sampleRate, chain, "", seg.readFrom / sampleRate));
+            }
+            finally {
+                await page.close().catch(() => undefined);
+            }
+            const rendered = outPlanes[0]?.length ?? 0;
+            if (rendered === 0) {
+                throw new AudioFxRenderError(`Audio FX produced no samples for track ${options.trackId}`);
+            }
+            // The last window keeps the chain's tail (reverb, delay), as a whole-file render does.
+            const skip = seg.keepFrom - seg.readFrom;
+            const kept = outPlanes.map((plane) => plane.subarray(skip, seg.last ? rendered : seg.keepTo - seg.readFrom));
+            if (gainAt)
+                applyEnvelopeToPlanes(kept, sampleRate, gainAt, seg.keepFrom);
+            const bytes = encodeSamples(interleave(kept), float);
+            writeFileSync(outFd, bytes);
+            written += bytes.length;
+        }
+        writeSync(outFd, wavHeader(written, sampleRate, channels, float), 0, 44, 0);
+    }
+    finally {
+        closeSync(inFd);
+        if (outFd !== undefined)
+            closeSync(outFd);
+    }
+    return gainAt !== null;
+}
 /**
  * Run a chain over `inputWav`, writing `outputWav`. Resolves to the path to use
  * downstream — `outputWav` when the chain did something, `inputWav` untouched
@@ -232,8 +379,24 @@ export async function applyAudioFxChain(inputWav, chain, outputWav, options) {
     if (!existsSync(inputWav)) {
         throw new AudioFxRenderError(`Audio FX input is missing: ${inputWav}`);
     }
-    const { samples, sampleRate, channels, float } = readWav(inputWav);
-    const planes = deinterleave(samples, channels);
+    // Automation is clocked from the file's own start, so a windowed render leaves it to the whole path.
+    const limits = { ...DEFAULT_STREAMING_LIMITS, ...options.streaming };
+    const header = options.automation ? null : readWavHeader(inputWav);
+    const streamed = header !== null && header.dataBytes > limits.aboveBytes;
+    if (streamed) {
+        return withFxBrowser(options, async (openPage) => ({
+            path: outputWav,
+            envelopeBaked: await renderInSegments(openPage, inputWav, header, chain, outputWav, options, limits),
+        }));
+    }
+    if (statSync(inputWav).size > MAX_WHOLE_FILE_BYTES) {
+        const why = options.automation
+            ? "parameter automation is not supported on inputs over 2 GiB"
+            : "the WAV header of an input over 2 GiB could not be read";
+        throw new AudioFxRenderError(`Audio FX for track ${options.trackId}: ${why} (${inputWav})`);
+    }
+    const input = readWav(inputWav);
+    const planes = deinterleave(input.samples, input.channels);
     // 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
@@ -243,32 +406,11 @@ export async function applyAudioFxChain(inputWav, chain, outputWav, options) {
     // never costs a browser.
     if ((planes[0]?.length ?? 0) === 0)
         return { path: inputWav, envelopeBaked: false };
-    // Both resources are taken INSIDE the try that releases them. The lease used
-    // to be acquired above it, with the mkdtemp between — so a failure there
-    // (a full disk, a read-only tmpdir) leaked a pooled browser, and a pool with
-    // no leases left hangs every later render rather than failing one.
-    const hostDir = mkdtempSync(join(tmpdir(), "hf-fx-host-"));
-    let lease = null;
-    try {
-        // Audio processing needs no GPU or special capture mode; a plain sandboxed
-        // browser is enough, and the lease pool reuses one across tracks.
-        // Checked before the lease, not after: an already-cancelled track has no
-        // reason to take a browser out of the pool just to hand it straight back.
-        if (options.signal?.aborted) {
-            throw new AudioFxRenderError(`Audio FX cancelled for track ${options.trackId}`);
-        }
-        lease = await acquireBrowser(["--no-sandbox", "--autoplay-policy=no-user-gesture-required"]);
-        const page = await lease.browser.newPage();
+    return withFxBrowser(options, async (openPage) => {
+        const page = await openPage();
         try {
-            // AudioWorklet is only exposed in a secure context, and about:blank is
-            // not one — the module would fail with an opaque error. A file:// page
-            // qualifies and needs no listening socket.
-            const hostPage = join(hostDir, "audio-fx.html");
-            writeFileSync(hostPage, "<!doctype html><meta charset=utf-8><title>audio fx</title>");
-            await page.goto(pathToFileURL(hostPage).href, { waitUntil: "domcontentloaded" });
-            await page.addScriptTag({ content: getAudioFxRuntimeScript() });
             await sendPlanesToPage(page, planes);
-            const outLengths = await renderPlanesInPage(page, sampleRate, chain, options.automation ? serializeAutomation(options.automation) : "");
+            const outLengths = await renderPlanesInPage(page, input.sampleRate, chain, options.automation ? serializeAutomation(options.automation) : "");
             const outPlanes = await readPlanesFromPage(page, outLengths);
             if (outPlanes.length === 0 || (outPlanes[0]?.length ?? 0) === 0) {
                 throw new AudioFxRenderError(`Audio FX produced no samples for track ${options.trackId}`);
@@ -278,15 +420,32 @@ export async function applyAudioFxChain(inputWav, chain, outputWav, options) {
             // a bake that never happened.
             const gainAt = envelopeWalkerFor(options.envelope);
             if (gainAt)
-                applyEnvelopeToPlanes(outPlanes, sampleRate, gainAt);
+                applyEnvelopeToPlanes(outPlanes, input.sampleRate, gainAt);
             // Same format in as out: a float input is a group sub-mix whose headroom
             // must survive to its fader (see writeWav).
-            writeWav(outputWav, interleave(outPlanes), sampleRate, outPlanes.length, float);
+            writeWav(outputWav, interleave(outPlanes), input.sampleRate, outPlanes.length, input.float);
             return { path: outputWav, envelopeBaked: gainAt !== null };
         }
         finally {
             await page.close().catch(() => undefined);
         }
+    });
+}
+/** Run `body` with a leased browser and a way to open pages on the runtime; both are released in the same try that takes them. */
+async function withFxBrowser(options, body) {
+    const hostDir = mkdtempSync(join(tmpdir(), "hf-fx-host-"));
+    let lease = null;
+    try {
+        // Audio processing needs no GPU or special capture mode; a plain sandboxed
+        // browser is enough, and the lease pool reuses one across tracks.
+        // Checked before the lease, not after: an already-cancelled track has no
+        // reason to take a browser out of the pool just to hand it straight back.
+        if (options.signal?.aborted) {
+            throw new AudioFxRenderError(`Audio FX cancelled for track ${options.trackId}`);
+        }
+        lease = await acquireBrowser(["--no-sandbox", "--autoplay-policy=no-user-gesture-required"]);
+        const { browser } = lease;
+        return await body(() => openFxPage(browser, hostDir));
     }
     catch (err) {
         if (err instanceof AudioFxRenderError)
@@ -298,6 +457,25 @@ export async function applyAudioFxChain(inputWav, chain, outputWav, options) {
         await lease?.release().catch(() => undefined);
     }
 }
+async function openFxPage(browser, hostDir) {
+    const page = await browser.newPage();
+    try {
+        // AudioWorklet is only exposed in a secure context, and about:blank is
+        // not one — the module would fail with an opaque error. A file:// page
+        // qualifies and needs no listening socket.
+        const hostPage = join(hostDir, "audio-fx.html");
+        writeFileSync(hostPage, "<!doctype html><meta charset=utf-8><title>audio fx</title>");
+        await page.goto(pathToFileURL(hostPage).href, {
+            waitUntil: "domcontentloaded",
+        });
+        await page.addScriptTag({ content: getAudioFxRuntimeScript() });
+        return page;
+    }
+    catch (err) {
+        await page.close().catch(() => undefined);
+        throw err;
+    }
+}
 /**
  * Hand the input planes to the page a chunk at a time.
  *
@@ -330,8 +508,8 @@ async function sendPlanesToPage(page, planes) {
 }
 /** Run the chain in the page and return each output plane's sample count. The
  *  samples themselves stay page-side until `readPlanesFromPage` pulls them. */
-async function renderPlanesInPage(page, sampleRate, chain, automationJson) {
-    return (await page.evaluate(async ([rate, chainJson, automation]) => {
+async function renderPlanesInPage(page, sampleRate, chain, automationJson, elapsed = 0) {
+    return (await page.evaluate(async ([rate, chainJson, automation, at]) => {
         const w = window;
         const io = w.__HF_FX_IO;
         if (!w.__HF_AUDIO_FX || !io)
@@ -348,9 +526,9 @@ async function renderPlanesInPage(page, sampleRate, chain, automationJson) {
         // Dropped before the render allocates its own buffers, so the page does
         // not hold two copies of the track at once.
         io.in = [];
-        io.out = await w.__HF_AUDIO_FX.render(inPlanes, rate, chainJson, automation || undefined);
+        io.out = await w.__HF_AUDIO_FX.render(inPlanes, rate, chainJson, automation || undefined, at);
         return io.out.map((plane) => plane.length);
-    }, [sampleRate, JSON.stringify(chain), automationJson]));
+    }, [sampleRate, JSON.stringify(chain), automationJson, elapsed]));
 }
 /** Pull one output plane back over CDP, `TRANSFER_BYTES` at a time. */
 async function readPlaneFromPage(page, index, byteLength) {

package/dist/services/audioFxWarmup.d.ts

@@ -0,0 +1,13 @@
+import { type HfAudioFxChain } from "@hyperframes/core/audio-fx";
+/**
+ * How far ahead of a window a chain must be fed for its state to match a whole render.
+ *
+ * Summed, since the chain is serial: a delay ahead of a reverb hands the reverb every repeat.
+ * Biquads, chorus and pitch shift settle well inside the caller's floor.
+ */
+export declare function chainWarmupSeconds(chain: HfAudioFxChain): number;
+/** The pre-roll a chain gets: its own memory, between `floorSeconds` and `capSeconds`. */
+export declare function windowPrerollSeconds(chain: HfAudioFxChain, floorSeconds: number, capSeconds: number): {
+    seconds: number;
+    capped: boolean;
+};

package/dist/services/audioFxWarmup.js

@@ -0,0 +1,34 @@
+import { delayTailSeconds, reverbRoomSeconds } from "@hyperframes/core/audio-fx-tail";
+import { enabledAudioFxNodes, normalizeAudioFxParams, } from "@hyperframes/core/audio-fx";
+/** Where state stops mattering: -60 dB, i.e. e^-6.9 of what it started as. */
+const DECAY_TO_FLOOR = Math.log(1000);
+const param = (node, key) => Number(normalizeAudioFxParams(node.type, node.params)[key] ?? 0);
+const reverbMemory = (node) => param(node, "wet") > 0 ? reverbRoomSeconds(param(node, "size")) : 0;
+const delayMemory = (node) => param(node, "mix") > 0 ? delayTailSeconds(param(node, "time"), param(node, "feedback")) : 0;
+const releaseMemory = (node) => (DECAY_TO_FLOOR * param(node, "release")) / 1000;
+/** Seconds of input a node still remembers, to -60 dB. */
+const MEMORY = {
+    reverb: reverbMemory,
+    delay: delayMemory,
+    compressor: releaseMemory,
+    limiter: releaseMemory,
+    truepeak: releaseMemory,
+    gate: releaseMemory,
+};
+/**
+ * How far ahead of a window a chain must be fed for its state to match a whole render.
+ *
+ * Summed, since the chain is serial: a delay ahead of a reverb hands the reverb every repeat.
+ * Biquads, chorus and pitch shift settle well inside the caller's floor.
+ */
+export function chainWarmupSeconds(chain) {
+    return enabledAudioFxNodes(chain).reduce((sum, node) => sum + (MEMORY[node.type]?.(node) ?? 0), 0);
+}
+/** The pre-roll a chain gets: its own memory, between `floorSeconds` and `capSeconds`. */
+export function windowPrerollSeconds(chain, floorSeconds, capSeconds) {
+    const needed = chainWarmupSeconds(chain);
+    return {
+        seconds: Math.min(capSeconds, Math.max(floorSeconds, needed)),
+        capped: needed > capSeconds,
+    };
+}

package/dist/services/audioMixer.d.ts

@@ -23,5 +23,14 @@ export declare function buildTrackInputFilter(track: Pick<AudioTrack, "start" |
 export declare function volumeLaneKeyframes(automation: {
     lanes: HfAutomationLane[];
 }, trackStart: number, duration: number): 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
+ * itself has no parsed element to carry it.
+ */
+export declare function parseMasterFxChain(html: string): string | undefined;
 export declare function parseAudioElements(html: string): AudioElement[];
-export declare function processCompositionAudio(elements: AudioElement[], baseDir: string, workDir: string, outputPath: string, totalDuration: number, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">>, compiledDir?: string): Promise<MixResult>;
+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;
+}, compiledDir?: string): Promise<MixResult>;

package/dist/services/audioMixer.js

@@ -15,11 +15,11 @@ 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_FX_ATTR, parseAudioFxChain, } from "@hyperframes/core/audio-fx";
 import { HF_AUDIO_AUTOMATION_ATTR, 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 { resolveAudioGroups } from "@hyperframes/core/audio-groups";
+import { readMasterFxChain, resolveAudioGroups } from "@hyperframes/core/audio-groups";
 import { applyAudioFxChain, AudioFxRenderError } from "./audioFxRender.js";
 /** An MP4-family container records AAC priming as an edit list; a raw .aac plays ~21 ms late.
  * The video mux, the distributed plan and the PNG-sequence sidecar all read this one name. */
@@ -395,6 +395,14 @@ export function volumeLaneKeyframes(automation, trackStart, duration) {
         push(duration, last.v);
     return out;
 }
+/**
+ * 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
+ * itself has no parsed element to carry it.
+ */
+export function parseMasterFxChain(html) {
+    return readMasterFxChain(parseHTML(unwrapTemplate(html)).document);
+}
 export function parseAudioElements(html) {
     const elements = [];
     const { document } = parseHTML(unwrapTemplate(html));
@@ -573,7 +581,7 @@ async function generateSilence(outputPath, duration, signal, config) {
         failure,
     };
 }
-async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config) {
+async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config, floatWav = false) {
     const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const masterOutputGain = config?.audioGain ?? DEFAULT_CONFIG.audioGain;
     if (tracks.length === 0) {
@@ -633,10 +641,7 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
             scriptPath,
             "-map",
             "[out]",
-            "-acodec",
-            "aac",
-            "-b:a",
-            "192k",
+            ...(floatWav ? ["-acodec", "pcm_f32le", "-ar", "48000"] : ["-acodec", "aac", "-b:a", "192k"]),
             "-t",
             String(totalDuration),
             "-y",
@@ -833,6 +838,44 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
         return { success: false, error: formatFfmpegError(result.exitCode, result.stderr) };
     return { success: true, degradedAutomation };
 }
+/**
+ * Sum the tracks to a float WAV, run the master chain over the sum, then AAC-encode.
+ * Groups are already folded into `tracks`, and the sum stays float until the encoder.
+ */
+async function mixThroughMasterBus(tracks, masterChain, outputPath, workDir, totalDuration, signal, config) {
+    const sumPath = join(workDir, "master-sum.wav");
+    const sum = await mixAudioTracks(tracks, sumPath, totalDuration, signal, config, true);
+    if (!sum.success)
+        return { ...sum, outputPath };
+    const fx = await applyAudioFxChain(sumPath, masterChain, join(workDir, "master-fx.wav"), {
+        trackId: "master",
+        signal,
+    });
+    const encoded = await runFfmpeg([
+        "-i",
+        fx.path,
+        "-t",
+        String(totalDuration),
+        "-acodec",
+        "aac",
+        "-b:a",
+        "192k",
+        "-y",
+        outputPath,
+    ], { signal, timeout: config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout });
+    if (!encoded.success) {
+        const failure = ffmpegFailure("mix", encoded);
+        return {
+            success: false,
+            outputPath,
+            durationMs: sum.durationMs + encoded.durationMs,
+            tracksProcessed: 0,
+            error: failure.detail,
+            failures: [failure],
+        };
+    }
+    return { ...sum, outputPath, durationMs: sum.durationMs + encoded.durationMs };
+}
 export async function processCompositionAudio(elements, baseDir, workDir, outputPath, totalDuration, signal, config, compiledDir) {
     const startMs = Date.now();
     const tracks = [];
@@ -1095,13 +1138,16 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     // The producer only surfaces audio failures when `success` is false; mixing
     // the remaining tracks made the omitted cue indistinguishable from a valid
     // render unless someone manually audited that exact audio window.
-    const bail = () => {
+    const removeWorkDir = () => {
         try {
             rmSync(workDir, { recursive: true, force: true });
         }
         catch {
             /* ignore */
         }
+    };
+    const bail = () => {
+        removeWorkDir();
         return {
             success: false,
             outputPath,
@@ -1113,6 +1159,26 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     };
     if (failures.length > 0)
         return bail();
+    // Parsed before any group is mixed, so a malformed master chain fails fast and
+    // as a failure, the way an unreadable group chain does.
+    let masterChain;
+    const masterFxJson = config?.masterFxChain;
+    if (masterFxJson) {
+        try {
+            masterChain = parseAudioFxChain(masterFxJson);
+        }
+        catch (err) {
+            failures.push({
+                stage: "mix",
+                reason: "internal",
+                owner: "user",
+                retryable: false,
+                elementId: "master",
+                detail: boundedDetail(`Master bus chain is unreadable: ${err instanceof Error ? err.message : String(err)}`),
+            });
+            return bail();
+        }
+    }
     // Sub-mix each group into one processed bus (design doc §1.3), then fold it
     // into the flat track list as a single AudioTrack — everything downstream
     // (the final mixAudioTracks call) never has to know groups exist. Group
@@ -1195,8 +1261,10 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             });
         }
         catch (err) {
-            if (err instanceof AudioFxRenderError)
+            if (err instanceof AudioFxRenderError) {
+                removeWorkDir();
                 throw err;
+            }
             failures.push({
                 stage: "mix",
                 reason: "internal",
@@ -1209,12 +1277,15 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     }
     if (failures.length > 0)
         return bail();
-    const mixResult = await mixAudioTracks(tracks, outputPath, totalDuration, signal, config);
+    let mixResult;
     try {
-        rmSync(workDir, { recursive: true, force: true });
+        mixResult =
+            masterChain && tracks.length > 0
+                ? await mixThroughMasterBus(tracks, masterChain, outputPath, workDir, totalDuration, signal, config)
+                : await mixAudioTracks(tracks, outputPath, totalDuration, signal, config);
     }
-    catch {
-        /* ignore */
+    finally {
+        removeWorkDir();
     }
     // A group whose sub-mix had to drop member automation reports it the same
     // way mixAudioTracks reports its own degradation: on a SUCCESSFUL result, so

package/dist/services/frameCapture.js

@@ -7,6 +7,7 @@
  * the page to expose window.__hf, then captures frames deterministically
  * via Chrome's BeginFrame API or Page.captureScreenshot fallback.
  */
+import { CDPSession, } from "puppeteer-core";
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { COMPOSITION_SOURCE_URL, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, } from "@hyperframes/core";
@@ -855,6 +856,15 @@ async function constructCaptureSession(input) {
     const { browser, captureMode } = browserLease;
     const page = await browser.newPage();
     onPageCreated(page);
+    // Cap the existing session's inspection buffer; new sessions have separate buffers.
+    const frame = page.mainFrame();
+    // Frame.client is runtime-only, so keep capture working when it is absent.
+    if ("client" in frame && frame.client instanceof CDPSession) {
+        await frame.client.send("Network.enable", {
+            maxTotalBufferSize: 32 * 1024 * 1024,
+            maxResourceBufferSize: 16 * 1024 * 1024,
+        });
+    }
     // Polyfill esbuild's keepNames helper inside the page.
     //
     // The engine is published as raw TypeScript (`packages/engine/package.json`

package/dist/services/screenshotService.js

@@ -4,6 +4,7 @@
  *
  * BeginFrame-based deterministic screenshot capture and video frame injection.
  */
+import { withVideoFrameSources } from "./videoFrameTransport.js";
 import { COLOR_GRADING_SOURCE_HIDDEN_ATTR } from "@hyperframes/core/color-grading";
 import { HF_COLOR_GRADING_CANVAS_ID_PREFIX, MEDIA_RENDER_ID_ATTR, MEDIA_VISUAL_STYLE_PROPERTIES, RENDER_FRAME_ID_PREFIX, RENDER_FRAME_ID_SUFFIX, renderFrameIdForRenderId, } from "@hyperframes/core";
 export const cdpSessionCache = new WeakMap();
@@ -547,6 +548,9 @@ export async function ensureRenderFrameSiblings(page) {
 export async function injectVideoFramesBatch(page, updates) {
     if (updates.length === 0)
         return [];
+    return withVideoFrameSources(page, updates, (resolved) => injectResolvedVideoFramesBatch(page, resolved));
+}
+async function injectResolvedVideoFramesBatch(page, updates) {
     return await page.evaluate(
     // fallow-ignore-next-line complexity
     async (items, visualProperties, colorGradingSourceHiddenAttr) => {
@@ -690,8 +694,12 @@ export async function injectVideoFramesBatch(page, updates) {
             img.style.zIndex = computedStyle.zIndex;
             img.decoding = "sync";
             if (img.getAttribute("src") !== item.dataUri) {
+                if (item.crossOrigin)
+                    img.crossOrigin = item.crossOrigin;
+                else
+                    img.removeAttribute("crossorigin");
                 img.src = item.dataUri;
-                const source = item.dataUri.startsWith("data:") ? "inline frame" : item.dataUri;
+                const source = item.sourceLabel ?? (item.dataUri.startsWith("data:") ? "inline frame" : item.dataUri);
                 pendingDecodes.push(img.decode().catch((error) => {
                     throw new Error(`Video frame for "${item.videoId}" failed to load (${source}): ${error instanceof Error ? error.message : String(error)}`);
                 }));

package/dist/services/videoFrameTransport.d.ts

@@ -0,0 +1,13 @@
+import { type Page } from "puppeteer-core";
+export interface VideoFrameUpdate {
+    videoId: string;
+    dataUri: string;
+    crossOrigin?: "anonymous";
+    sourceLabel?: string;
+}
+/**
+ * Inline image URLs outlive the Node LRU in Chrome's resource cache. Deliver
+ * their bytes as no-store responses over CDP instead: the page sees short URLs,
+ * and frame requests never wait for the source videos' HTTP connections.
+ */
+export declare function withVideoFrameSources<T>(page: Page, updates: VideoFrameUpdate[], inject: (resolved: VideoFrameUpdate[]) => Promise<T>): Promise<T>;

package/dist/services/videoFrameTransport.js

@@ -0,0 +1,98 @@
+import { randomUUID } from "node:crypto";
+const base64ImagePrefix = /^data:(image\/[\w.+-]+);base64,/;
+const transports = new WeakMap();
+async function createTransport(page) {
+    const pageUrl = new URL(page.url());
+    const origin = /^https?:$/.test(pageUrl.protocol)
+        ? pageUrl.origin
+        : "https://hyperframes-render.invalid";
+    const prefix = `${origin}/__hyperframes_video_frames__/${randomUUID()}/`;
+    const responses = new Map();
+    const client = await page.createCDPSession();
+    client.on("Fetch.requestPaused", (event) => {
+        const frame = responses.get(event.request.url);
+        void fulfillFrame(client, event.requestId, frame);
+    });
+    try {
+        await client.send("Fetch.enable", {
+            patterns: [{ urlPattern: `${prefix}*`, requestStage: "Request" }],
+        });
+    }
+    catch (error) {
+        await client.detach().catch(() => { });
+        throw error;
+    }
+    page.once("close", () => responses.clear());
+    return { prefix, nextId: 0, responses };
+}
+async function fulfillFrame(client, requestId, frame) {
+    try {
+        await client.send("Fetch.fulfillRequest", {
+            requestId,
+            responseCode: frame ? 200 : 404,
+            responseHeaders: [
+                { name: "Content-Type", value: frame?.contentType ?? "text/plain" },
+                { name: "Cache-Control", value: "no-store" },
+                { name: "Access-Control-Allow-Origin", value: "*" },
+            ],
+            body: frame?.body ?? "",
+        });
+    }
+    catch (error) {
+        if (frame)
+            frame.error = error;
+        // A failed protocol response must unblock img.decode, including on page closure.
+        await client.send("Fetch.failRequest", { requestId, errorReason: "Failed" }).catch(() => { });
+    }
+}
+/**
+ * Inline image URLs outlive the Node LRU in Chrome's resource cache. Deliver
+ * their bytes as no-store responses over CDP instead: the page sees short URLs,
+ * and frame requests never wait for the source videos' HTTP connections.
+ */
+export async function withVideoFrameSources(page, updates, inject) {
+    if (!updates.some((update) => base64ImagePrefix.test(update.dataUri)))
+        return inject(updates);
+    let pending = transports.get(page);
+    if (!pending) {
+        pending = createTransport(page);
+        transports.set(page, pending);
+    }
+    let transport;
+    try {
+        transport = await pending;
+    }
+    catch (error) {
+        transports.delete(page);
+        throw error;
+    }
+    const registered = [];
+    try {
+        const resolved = updates.map((update) => {
+            const match = base64ImagePrefix.exec(update.dataUri);
+            if (!match)
+                return update;
+            const frame = {
+                contentType: match[1] ?? "image/png",
+                body: update.dataUri.slice(match[0].length),
+            };
+            const url = `${transport.prefix}${transport.nextId++}`;
+            transport.responses.set(url, frame);
+            registered.push({ url, frame });
+            return {
+                ...update,
+                dataUri: url,
+                crossOrigin: "anonymous",
+                sourceLabel: "inline frame",
+            };
+        });
+        return await inject(resolved);
+    }
+    catch (error) {
+        throw registered.find(({ frame }) => frame.error !== undefined)?.frame.error ?? error;
+    }
+    finally {
+        for (const { url } of registered)
+            transport.responses.delete(url);
+    }
+}

package/package.json

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