@hyperframes/engine 0.8.168 → 0.8.170

package/dist/config.d.ts

@@ -5,7 +5,7 @@
  * env var sprawl with a structured interface. Env vars still work as
  * fallbacks for backward compatibility during migration.
  */
-import { type DistributedFps } from "@hyperframes/core";
+import { type DistributedFps } from "@hyperframes/core/distributed-fps";
 /**
  * Full engine configuration. All fields are wired through the config
  * object; env vars serve as backward-compatible fallbacks resolved

package/dist/config.js

@@ -6,7 +6,7 @@
  * fallbacks for backward compatibility during migration.
  */
 import { tmpdir } from "node:os";
-import { DISTRIBUTED_FPS } from "@hyperframes/core";
+import { DISTRIBUTED_FPS } from "@hyperframes/core/distributed-fps";
 import { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
 import { join } from "node:path";
 import { getSystemTotalMb, isLowMemorySystem, LOW_MEMORY_TOTAL_MB_THRESHOLD, } from "./services/systemMemory.js";

package/dist/services/__fixtures__/loopback.d.ts

@@ -0,0 +1,5 @@
+import type { Server } from "node:http";
+import { type Browser } from "puppeteer-core";
+/** Listens on a free loopback port and returns the server's origin. */
+export declare function listenOnLoopback(server: Server): Promise<string>;
+export declare function launchTestChrome(executablePath: string | undefined): Promise<Browser>;

package/dist/services/__fixtures__/loopback.js

@@ -0,0 +1,16 @@
+import puppeteer from "puppeteer-core";
+/** Listens on a free loopback port and returns the server's origin. */
+export async function listenOnLoopback(server) {
+    await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("No test server address");
+    return `http://127.0.0.1:${address.port}`;
+}
+export function launchTestChrome(executablePath) {
+    return puppeteer.launch({
+        executablePath,
+        headless: true,
+        args: ["--no-sandbox", "--disable-dev-shm-usage"],
+    });
+}

package/dist/services/aacEncode.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AAC for the mixed 48 kHz audio. One encoder is single-threaded (about 60x real time),
+ * so long audio is encoded as frame-aligned segments in parallel and their frames joined.
+ */
+import { type RunFfmpegResult } from "../utils/runFfmpeg.js";
+export declare const AAC_ARGS: string[];
+export declare function aacSegmentCount(totalDuration: number): number;
+export declare function splitAdtsFrames(bytes: Buffer): Buffer[];
+/** `input` is a 48 kHz WAV of exactly `totalDuration`. */
+export declare function encodeAac(input: string, outputPath: string, totalDuration: number, { signal, timeout }: {
+    signal?: AbortSignal;
+    timeout: number;
+}): Promise<RunFfmpegResult>;

package/dist/services/aacEncode.js

@@ -0,0 +1,102 @@
+/**
+ * AAC for the mixed 48 kHz audio. One encoder is single-threaded (about 60x real time),
+ * so long audio is encoded as frame-aligned segments in parallel and their frames joined.
+ */
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { runFfmpeg } from "../utils/runFfmpeg.js";
+const SAMPLE_RATE = 48_000;
+const FRAME_SAMPLES = 1024;
+const MIN_SEGMENT_SECONDS = 60;
+// Fixed rather than the core count, so the bytes (and the planHash) do not depend on the machine.
+const MAX_SEGMENTS = 8;
+// Encoded on each side of a segment and dropped. The encoder's rate control takes about
+// 10 s to settle (its error is higher until then), so a segment starts 10 s before its cut.
+const PRE_ROLL_FRAMES = 469;
+const POST_ROLL_FRAMES = 8;
+export const AAC_ARGS = ["-acodec", "aac", "-b:a", "192k"];
+export function aacSegmentCount(totalDuration) {
+    return Math.max(1, Math.min(MAX_SEGMENTS, Math.floor(totalDuration / MIN_SEGMENT_SECONDS)));
+}
+export function splitAdtsFrames(bytes) {
+    const frames = [];
+    for (let at = 0; at < bytes.length;) {
+        const length = ((bytes[at + 3] & 0x03) << 11) | (bytes[at + 4] << 3) | (bytes[at + 5] >> 5);
+        if (bytes[at] !== 0xff || (bytes[at + 1] & 0xf0) !== 0xf0 || length < 7) {
+            throw new Error(`Not an ADTS frame at byte ${at}`);
+        }
+        frames.push(bytes.subarray(at, at + length));
+        at += length;
+    }
+    return frames;
+}
+/**
+ * Packet g of the stream covers samples [(g-1)*1024, (g+1)*1024); packet 0 is the
+ * encoder delay. Segment k encodes from `firstFrame` and keeps its packets [keepFrom, keepTo).
+ */
+function planSegments(totalDuration, count) {
+    // Round to whole samples first: 147.52 * 48000 is 7080960.000000001 in floating point.
+    const packets = Math.ceil(Math.round(totalDuration * SAMPLE_RATE) / FRAME_SAMPLES) + 1;
+    const cuts = Array.from({ length: count + 1 }, (_, k) => Math.round((k * packets) / count));
+    return cuts.slice(0, -1).map((cut, k) => {
+        const next = cuts[k + 1];
+        const firstFrame = Math.max(0, cut - PRE_ROLL_FRAMES);
+        const end = k === count - 1 ? "" : `:end_sample=${(next + POST_ROLL_FRAMES) * FRAME_SAMPLES}`;
+        const trim = `atrim=start_sample=${firstFrame * FRAME_SAMPLES}${end}`;
+        return { trim, keepFrom: cut - firstFrame, keepTo: next - firstFrame };
+    });
+}
+/** `input` is a 48 kHz WAV of exactly `totalDuration`. */
+export async function encodeAac(input, outputPath, totalDuration, { signal, timeout }) {
+    const count = aacSegmentCount(totalDuration);
+    if (count === 1) {
+        const args = ["-i", input, "-t", String(totalDuration), ...AAC_ARGS, "-y", outputPath];
+        return runFfmpeg(args, { signal, timeout });
+    }
+    const dir = mkdtempSync(join(dirname(outputPath), ".aac-segments-"));
+    try {
+        const segments = planSegments(totalDuration, count).map((segment, k) => ({
+            ...segment,
+            path: join(dir, `${k}.aac`),
+        }));
+        const results = await Promise.all(segments.map(({ trim, path }) => runFfmpeg(["-i", input, "-af", trim, ...AAC_ARGS, "-f", "adts", "-y", path], {
+            signal,
+            timeout,
+        })));
+        const failed = results.find((result) => !result.success);
+        if (failed)
+            return failed;
+        const joined = join(dir, "joined.aac");
+        const frames = segments.flatMap(({ path, keepFrom, keepTo }) => {
+            const segmentFrames = splitAdtsFrames(readFileSync(path));
+            if (segmentFrames.length < keepTo) {
+                throw new Error(`AAC segment ${path} has ${segmentFrames.length} frames, needs ${keepTo}`);
+            }
+            return segmentFrames.slice(keepFrom, keepTo);
+        });
+        writeFileSync(joined, Buffer.concat(frames));
+        // ADTS carries neither the encoder delay nor the last packet's short duration: the offset
+        // restores the delay, and setts ends the stream at totalDuration as one encoder would.
+        const offset = String(-FRAME_SAMPLES / SAMPLE_RATE);
+        const end = `setts=duration='if(gte((PTS+DURATION)*TB,${totalDuration}),round(${totalDuration}/TB-PTS),DURATION)'`;
+        const muxed = await runFfmpeg([
+            "-itsoffset",
+            offset,
+            "-f",
+            "aac",
+            "-i",
+            joined,
+            "-c",
+            "copy",
+            "-bsf:a",
+            end,
+            "-y",
+            outputPath,
+        ], { signal, timeout });
+        const slowest = Math.max(...results.map((result) => result.durationMs));
+        return { ...muxed, durationMs: slowest + muxed.durationMs };
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/services/audioMixer.js

@@ -10,6 +10,7 @@ import { clampFadesToDuration, readElementFades } from "@hyperframes/core/audio-
 import { downloadToTemp, isHttpUrl, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { formatFfmpegError, runFfmpeg } from "../utils/runFfmpeg.js";
+import { AAC_ARGS, aacSegmentCount, encodeAac } from "./aacEncode.js";
 import { audioSubprocessEvidence } from "./audioFailureDiagnostic.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import { resolveMediaElementSrc, resolveProjectRelativeSrc } from "./videoFrameExtractor.js";
@@ -646,7 +647,7 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config,
             scriptPath,
             "-map",
             "[out]",
-            ...(floatWav ? ["-acodec", "pcm_f32le", "-ar", "48000"] : ["-acodec", "aac", "-b:a", "192k"]),
+            ...(floatWav ? ["-acodec", "pcm_f32le", "-ar", "48000"] : AAC_ARGS),
             "-t",
             String(totalDuration),
             "-y",
@@ -852,30 +853,24 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
     return { success: true, degradedAutomation };
 }
 /**
- * Sum the tracks to a float WAV, run the master chain over the sum, then AAC-encode.
+ * 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.
  */
-async function mixThroughMasterBus(tracks, masterChain, outputPath, workDir, totalDuration, signal, config) {
+async function mixThroughFloatSum(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",
+    const encoderInput = masterChain
+        ? (await applyAudioFxChain(sumPath, masterChain, join(workDir, "master-fx.wav"), {
+            trackId: "master",
+            signal,
+        })).path
+        : sumPath;
+    const encoded = await encodeAac(encoderInput, outputPath, totalDuration, {
         signal,
+        timeout: config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout,
     });
-    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 {
@@ -1295,8 +1290,8 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     let mixResult;
     try {
         mixResult =
-            masterChain && tracks.length > 0
-                ? await mixThroughMasterBus(tracks, masterChain, outputPath, workDir, totalDuration, signal, config)
+            (masterChain || aacSegmentCount(totalDuration) > 1) && tracks.length > 0
+                ? await mixThroughFloatSum(tracks, masterChain, outputPath, workDir, totalDuration, signal, config)
                 : await mixAudioTracks(tracks, outputPath, totalDuration, signal, config);
     }
     finally {

package/dist/services/frameCapture.d.ts

@@ -427,6 +427,10 @@ export declare function recordSubTimelineWarning(session: CaptureSession, timeou
  * PRINFRA-300 (blank hook scene, zero diagnostics, "fixed" by re-render).
  */
 export declare function buildLiveMapWarning(libraries: readonly string[]): CaptureWarning;
+/** Out-of-band videos a poster now sizes, so dropping their media cannot move layout. */
+export declare function releasableVideoIds(options: CaptureOptions): string[];
+/** FFmpeg supplies these videos' frames, so their own players would only hold decoders and buffers in every worker. */
+export declare function releaseInjectedVideoMedia(page: Page, videoIds: readonly string[]): Promise<void>;
 export declare function applyVideoMetadataHints(page: Page, hints: readonly CaptureVideoMetadataHint[] | undefined): Promise<void>;
 /** Thrown once a VFX chain fails: the frames it paints would render without the effect. */
 export declare class VfxFailureError extends Error {

package/dist/services/frameCapture.js

@@ -1529,6 +1529,28 @@ async function decodeAllImages(page) {
         }));
     });
 }
+/** Out-of-band videos a poster now sizes, so dropping their media cannot move layout. */
+export function releasableVideoIds(options) {
+    const hinted = new Set((options.videoMetadataHints ?? []).map((hint) => hint.id));
+    return (options.skipReadinessVideoIds ?? []).filter((id) => hinted.has(id));
+}
+/** FFmpeg supplies these videos' frames, so their own players would only hold decoders and buffers in every worker. */
+export async function releaseInjectedVideoMedia(page, videoIds) {
+    if (videoIds.length === 0)
+        return;
+    await page.evaluate((ids) => {
+        for (const id of ids) {
+            const video = window.__hfMediaEl?.(id) ?? document.getElementById(id);
+            if (!(video instanceof HTMLVideoElement))
+                continue;
+            video.pause();
+            for (const source of video.querySelectorAll("source"))
+                source.remove();
+            video.removeAttribute("src");
+            video.load();
+        }
+    }, [...videoIds]);
+}
 export async function applyVideoMetadataHints(page, hints) {
     if (!hints || hints.length === 0)
         return;
@@ -1763,6 +1785,7 @@ export async function initializeSession(session) {
         assertVfxIntact(session);
         recordSubTimelineWarning(session, pageReadyTimeout);
         await applyVideoMetadataHints(page, session.options.videoMetadataHints);
+        await releaseInjectedVideoMedia(page, releasableVideoIds(session.options));
         logInitPhase("applyVideoMetadataHints complete");
         // Run independent readiness checks in parallel — videos, images, fonts,
         // and Tailwind don't depend on each other's completion.
@@ -1893,6 +1916,7 @@ export async function initializeSession(session) {
         assertVfxIntact(session);
         recordSubTimelineWarning(session, pageReadyTimeout);
         await applyVideoMetadataHints(page, session.options.videoMetadataHints);
+        await releaseInjectedVideoMedia(page, releasableVideoIds(session.options));
         logInitPhase("applyVideoMetadataHints complete");
         // Run independent readiness checks in parallel — videos, images, fonts,
         // and Tailwind don't depend on each other's completion.
@@ -2498,6 +2522,7 @@ export async function createStaticVerificationPage(session) {
             knownUnregisteredIds: session.subTimelineWaitMemo.unregisteredIds,
         });
         await applyVideoMetadataHints(page, session.options.videoMetadataHints);
+        await releaseInjectedVideoMedia(page, releasableVideoIds(session.options));
         const skipVideoIds = session.options.skipReadinessVideoIds ?? [];
         await Promise.all([
             pollVideosReady(page, skipVideoIds, pageReadyTimeout),

package/package.json

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