@hyperframes/engine 0.8.180 → 0.8.183

package/dist/config.d.ts

@@ -165,7 +165,7 @@ export interface EngineConfig {
     streamingEncodeDurationCapEnabled: boolean;
     /** Timeout for FFmpeg frame encoding (ms). Default: 600_000 */
     ffmpegEncodeTimeout: number;
-    /** Timeout for FFmpeg mux/faststart processes (ms). Default: 300_000 */
+    /** FFmpeg mux/faststart timeout (ms); extraction waits this long for each new frame. Default: 300_000 */
     ffmpegProcessTimeout: number;
     /**
      * Inactivity timeout for FFmpeg streaming encode (ms). The timer resets on

package/dist/config.js

@@ -497,7 +497,6 @@ export function resolveConfig(overrides) {
         coresPerWorker: envNum("PRODUCER_CORES_PER_WORKER", DEFAULT_CONFIG.coresPerWorker),
         minParallelFrames: envNum("PRODUCER_MIN_PARALLEL_FRAMES", DEFAULT_CONFIG.minParallelFrames),
         largeRenderThreshold: envNum("PRODUCER_LARGE_RENDER_THRESHOLD", DEFAULT_CONFIG.largeRenderThreshold),
-        chromePath: env("PRODUCER_HEADLESS_SHELL_PATH"),
         disableGpu: envBool("PRODUCER_DISABLE_GPU", DEFAULT_CONFIG.disableGpu),
         browserGpuMode: envBrowserGpuMode(),
         allowSoftwareWebGpu: envBool("PRODUCER_ALLOW_SOFTWARE_WEBGPU", DEFAULT_CONFIG.allowSoftwareWebGpu),

package/dist/index.d.ts

@@ -38,7 +38,7 @@ export { chromeMajorCeiling } from "./services/chromeHostCeiling.js";
 export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool, closeBrowserPool, resolveHeadlessShellPath, resolveBrowserGpuMode, buildChromeArgs, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, WebGpuUnavailableError, ENABLE_BROWSER_POOL, BrowserLeasePool, type GpuProbeLifecycle, type BuildChromeArgsOptions, type BrowserLaunchFingerprint, type BrowserLease, type BrowserPoolState, type CaptureMode, type AcquiredBrowser, } from "./services/browserManager.js";
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, type NavigationTimeoutHintContext, } from "./services/pageNavigationTimeoutErrorHint.js";
-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, } from "./services/frameCapture.js";
+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 { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, type BeginFrameResult, } from "./services/screenshotService.js";
@@ -64,6 +64,7 @@ export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimes
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
 export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, type RunFfmpegOptions, type RunFfmpegResult, } from "./utils/runFfmpeg.js";
+export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChildProcessOutcome, type ManagedProcessTerminationReason, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
@@ -74,7 +75,7 @@ export { diffGpuParityFrames, diffGpuParityPngs, verifyGpuParity, type RgbaFrame
 export { type TransitionFn, TRANSITIONS, crossfade, sampleRgb48le, hdrToLinear, linearToHdr, convertTransfer, } from "./utils/shaderTransitions.js";
 export { initHdrReadback, uploadAndReadbackHdrFrame, float16ToPqRgb, buildHdrChromeArgs, launchHdrBrowser, } from "./services/hdrCapture.js";
 export { captureScreenshotWithAlpha } from "./services/screenshotService.js";
-export { hideVideoElements, showVideoElements, queryVideoElementBounds, queryElementStacking, type VideoElementBounds, type ElementStackingInfo, } from "./services/videoFrameInjector.js";
+export { hideVideoElements, showVideoElements, queryVideoElementBounds, queryElementStacking, measureVideoShownBoxes, type ShownBox, type VideoElementBounds, type ElementStackingInfo, } from "./services/videoFrameInjector.js";
 export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompositionHdr, findHdrAutoPromotion, formatHdrAutoPromotionWarning, sanitizeHdrAutoPromotionAsset, DEFAULT_HDR10_MASTERING, HDR_AUTO_PROMOTION_PIPELINE, type HdrTransfer, type HdrEncoderColorParams, type HdrAutoPromotion, type CompositionHdrInfo, type HdrMasteringMetadata, } from "./utils/hdr.js";
 export type { VideoColorSpace } from "./utils/ffprobe.js";
 export { renderProvenanceArgs, appendRenderProvenanceArgs, readRenderProvenance, PROVENANCE_RENDERER_TAG, PROVENANCE_VERSION_TAG, PROVENANCE_RENDERER_NAME, PROVENANCE_VERSION, type RenderProvenance, } from "./utils/renderProvenance.js";

package/dist/index.js

@@ -40,7 +40,7 @@ export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool,
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, } from "./services/pageNavigationTimeoutErrorHint.js";
 // ── Frame capture pipeline ──────────────────────────────────────────────────────
-export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, } from "./services/frameCapture.js";
+export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, waitForImagesReady, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
@@ -69,6 +69,7 @@ export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimes
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
 export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, } from "./utils/runFfmpeg.js";
+export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
@@ -82,7 +83,7 @@ export { diffGpuParityFrames, diffGpuParityPngs, verifyGpuParity, } from "./util
 export { TRANSITIONS, crossfade, sampleRgb48le, hdrToLinear, linearToHdr, convertTransfer, } from "./utils/shaderTransitions.js";
 export { initHdrReadback, uploadAndReadbackHdrFrame, float16ToPqRgb, buildHdrChromeArgs, launchHdrBrowser, } from "./services/hdrCapture.js";
 export { captureScreenshotWithAlpha } from "./services/screenshotService.js";
-export { hideVideoElements, showVideoElements, queryVideoElementBounds, queryElementStacking, } from "./services/videoFrameInjector.js";
+export { hideVideoElements, showVideoElements, queryVideoElementBounds, queryElementStacking, measureVideoShownBoxes, } from "./services/videoFrameInjector.js";
 export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompositionHdr, findHdrAutoPromotion, formatHdrAutoPromotionWarning, sanitizeHdrAutoPromotionAsset, DEFAULT_HDR10_MASTERING, HDR_AUTO_PROMOTION_PIPELINE, } from "./utils/hdr.js";
 export { renderProvenanceArgs, appendRenderProvenanceArgs, readRenderProvenance, PROVENANCE_RENDERER_TAG, PROVENANCE_VERSION_TAG, PROVENANCE_RENDERER_NAME, PROVENANCE_VERSION, } from "./utils/renderProvenance.js";
 export { DrawElementCaptureError, isDrawElementCaptureError, } from "./services/drawElementCaptureError.js";

package/dist/services/aacEncode.d.ts

@@ -3,11 +3,12 @@
  * 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 }: {
+/** `input`, after `filter`, is audio of exactly `totalDuration`. */
+export declare function encodeAac(input: string, outputPath: string, totalDuration: number, { signal, timeout, filter, segments: count, }: {
     signal?: AbortSignal;
     timeout: number;
+    filter?: string;
+    segments?: number;
 }): Promise<RunFfmpegResult>;

package/dist/services/aacEncode.js

@@ -10,11 +10,11 @@ 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.
+// Encoded around each segment and dropped: rate control settles over ~10 s, and opening cold on
+// quiet sound codes the first loud frame up to 4.5 dB hot, so the first segment opens in silence.
 const PRE_ROLL_FRAMES = 469;
 const POST_ROLL_FRAMES = 8;
-export const AAC_ARGS = ["-acodec", "aac", "-b:a", "192k"];
+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)));
 }
@@ -40,26 +40,33 @@ function planSegments(totalDuration, count) {
     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}`;
+        const firstFrame = cut - PRE_ROLL_FRAMES;
+        const end = k === count - 1 ? "" : `end_sample=${(next + POST_ROLL_FRAMES) * FRAME_SAMPLES}`;
+        const trim = firstFrame < 0
+            ? `${end && `atrim=${end},`}adelay=delays=${-firstFrame * FRAME_SAMPLES}S:all=1`
+            : `atrim=start_sample=${firstFrame * FRAME_SAMPLES}${end && `:${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 });
-    }
+/** `input`, after `filter`, is audio of exactly `totalDuration`. */
+export async function encodeAac(input, outputPath, totalDuration, { signal, timeout, filter, segments: count = aacSegmentCount(totalDuration), }) {
     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], {
+        const results = await Promise.all(segments.map(({ trim, path }) => runFfmpeg([
+            "-i",
+            input,
+            "-af",
+            [filter, `aresample=${SAMPLE_RATE}`, trim].filter(Boolean).join(","),
+            ...AAC_ARGS,
+            "-f",
+            "adts",
+            "-y",
+            path,
+        ], {
             signal,
             timeout,
         })));

package/dist/services/audioMixer.d.ts

@@ -34,4 +34,5 @@ export declare function processCompositionAudio(elements: AudioElement[], baseDi
     /** Serialised master bus chain, from `parseMasterFxChain`. */
     masterFxChain?: string;
     urlByAbsentLocalPath?: ReadonlyMap<string, string>;
+    keepEncoderInputAt?: string;
 }, compiledDir?: string): Promise<MixResult>;

package/dist/services/audioMixer.js

@@ -1,16 +1,17 @@
 // fallow-ignore-file complexity code-duplication
 import { isSelfOrAncestorHidden, memberGroupKey, isMemberGroupHidden } from "./mediaHidden.js";
-import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "fs";
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, renameSync, rmSync, writeFileSync, } from "fs";
 import { join, dirname, isAbsolute, relative } from "path";
 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 { 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 { AAC_ARGS, aacSegmentCount, encodeAac } from "./aacEncode.js";
+import { encodeAac } from "./aacEncode.js";
 import { audioSubprocessEvidence } from "./audioFailureDiagnostic.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import { resolveMediaElementSrc, resolveProjectRelativeSrc } from "./videoFrameExtractor.js";
@@ -492,6 +493,7 @@ export function parseAudioElements(html) {
     }
     return elements;
 }
+const FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE = ["-xerror"];
 /** Decode `duration` s of audio from `mediaStart` in Chrome's media time. Until every stream has
  * started, an input seek snaps audio to the video's first keyframe, so read by timestamp instead. */
 async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, duration, playbackRate = 1, signal, config) {
@@ -501,17 +503,29 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         mkdirSync(outputDir, { recursive: true });
     const normalizedPlaybackRate = normalizeRateSpec(playbackRate);
     const sourceDuration = sourceTimeAt(normalizedPlaybackRate, duration);
-    // A failed probe keeps FFmpeg's default channel conversion and the input seek.
-    const metadata = await extractAudioMetadata(srcPath).catch(() => null);
+    // A failed local probe keeps FFmpeg's default channel conversion and the input seek; a URL probe
+    // is retried once, then fails: a blip must not change how the next, successful read is mixed.
+    const readsUrl = isHttpUrl(srcPath);
+    const metadata = readsUrl
+        ? await extractAudioMetadata(srcPath, { signal }).catch((error) => {
+            if (signal?.aborted)
+                throw error;
+            return extractAudioMetadata(srcPath, { signal });
+        })
+        : await extractAudioMetadata(srcPath).catch(() => null);
     const inputSeek = mediaStart >= (metadata?.latestStreamLeadSeconds ?? 0);
     const start = formatFilterNumber(mediaStart);
     const timestampTrim = inputSeek
         ? null
         : `atrim=start=${start}:end=${formatFilterNumber(mediaStart + sourceDuration)},asetpts=PTS-${start}/TB,aresample=async=1:first_pts=0`;
     const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, timestampTrim);
-    const args = inputSeek
-        ? ["-ss", String(mediaStart), "-t", String(sourceDuration), "-i", srcPath]
-        : ["-i", srcPath];
+    const args = [
+        ...(readsUrl ? FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE : []),
+        ...urlInputArgs(srcPath),
+        ...(inputSeek ? ["-ss", String(mediaStart), "-t", String(sourceDuration)] : []),
+        "-i",
+        srcPath,
+    ];
     args.push("-vn", "-acodec", "pcm_s16le", "-ar", "48000", ...outputArgs);
     if (normalizedPlaybackRate !== 1)
         args.push("-t", String(duration));
@@ -533,7 +547,11 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
             failure,
         };
     }
-    const failure = !result.success ? ffmpegFailure(stage, result) : undefined;
+    let failure = result.success ? undefined : ffmpegFailure(stage, result);
+    const probedLinkFailedToRead = readsUrl && (failure?.reason === "invalid_media" || failure?.reason === "ffmpeg_failed");
+    if (failure && probedLinkFailedToRead) {
+        failure = { ...failure, reason: "download_failed", owner: "system", retryable: true };
+    }
     return {
         success: result.success,
         outputPath,
@@ -585,7 +603,7 @@ async function generateSilence(outputPath, duration, signal, config) {
         failure,
     };
 }
-async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config, floatWav = false) {
+async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config) {
     const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const masterOutputGain = config?.audioGain ?? DEFAULT_CONFIG.audioGain;
     if (tracks.length === 0) {
@@ -647,7 +665,10 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config,
             scriptPath,
             "-map",
             "[out]",
-            ...(floatWav ? ["-acodec", "pcm_f32le", "-ar", "48000"] : AAC_ARGS),
+            "-acodec",
+            "pcm_f32le",
+            "-ar",
+            "48000",
             "-t",
             String(totalDuration),
             "-y",
@@ -858,7 +879,7 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
  */
 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);
+    const sum = await mixAudioTracks(tracks, sumPath, totalDuration, signal, config);
     if (!sum.success)
         return { ...sum, outputPath };
     const encoderInput = masterChain
@@ -882,6 +903,8 @@ async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, tota
             failures: [failure],
         };
     }
+    if (config?.keepEncoderInputAt)
+        renameSync(encoderInput, config.keepEncoderInputAt);
     return { ...sum, outputPath, durationMs: sum.durationMs + encoded.durationMs };
 }
 export async function processCompositionAudio(elements, baseDir, workDir, outputPath, totalDuration, signal, config, compiledDir) {
@@ -932,12 +955,17 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
         }
         try {
             let srcPath = element.src;
+            let readInPlace = false;
             if (!isHttpUrl(srcPath)) {
                 // Same browser-URL path semantics as videos.
                 srcPath = resolveProjectRelativeSrc(element.src, baseDir, compiledDir);
-                srcPath = config?.urlByAbsentLocalPath?.get(srcPath) ?? srcPath;
+                const remoteUrl = config?.urlByAbsentLocalPath?.get(srcPath);
+                if (remoteUrl) {
+                    srcPath = remoteUrl;
+                    readInPlace = true;
+                }
             }
-            if (isHttpUrl(srcPath)) {
+            if (isHttpUrl(srcPath) && !readInPlace) {
                 try {
                     srcPath = await downloadToTemp(srcPath, workDir, undefined, effectiveSignal, undefined, {
                         onTelemetry: writeUrlDownloadTelemetry,
@@ -948,7 +976,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
                     return;
                 }
             }
-            if (!existsSync(srcPath)) {
+            if (!readInPlace && !existsSync(srcPath)) {
                 failures.push({
                     stage: "source",
                     reason: "source_not_found",
@@ -980,7 +1008,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             if (element.end - element.start <= 0) {
                 let metadata;
                 try {
-                    metadata = await extractAudioMetadata(srcPath);
+                    metadata = await extractAudioMetadata(srcPath, readInPlace ? { signal: effectiveSignal } : undefined);
                 }
                 catch (err) {
                     failures.push(probeFailure(err instanceof Error ? err.message : String(err), element.id));
@@ -1291,7 +1319,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     let mixResult;
     try {
         mixResult =
-            (masterChain || aacSegmentCount(totalDuration) > 1) && tracks.length > 0
+            tracks.length > 0
                 ? await mixThroughFloatSum(tracks, masterChain, outputPath, workDir, totalDuration, signal, config)
                 : await mixAudioTracks(tracks, outputPath, totalDuration, signal, config);
     }

package/dist/services/browserManager.js

@@ -10,7 +10,7 @@ import { execSync } from "child_process";
 import { existsSync, readdirSync, statSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-import { chromeMajorCeiling, compareBrowserVersionsDescending, exceedsChromeCeiling, isManagedChromeDir, pickSharedShell, } from "./chromeHostCeiling.js";
+import { browserPathFromEnv, chromeMajorCeiling, compareBrowserVersionsDescending, exceedsChromeCeiling, isManagedChromeDir, pickSharedShell, } from "./chromeHostCeiling.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
 import { describeWslGpuAccess, detectWsl } from "./wslHost.js";
@@ -186,21 +186,13 @@ export function resolveHeadlessShellPath(config) {
     if (config?.chromePath) {
         return config.chromePath;
     }
-    if (process.env.PRODUCER_HEADLESS_SHELL_PATH) {
-        const envPath = process.env.PRODUCER_HEADLESS_SHELL_PATH;
-        if (!existsSync(envPath)) {
-            throw new Error(`[BrowserManager] Chrome binary not found at PRODUCER_HEADLESS_SHELL_PATH="${envPath}". ` +
+    const fromEnv = browserPathFromEnv();
+    if (fromEnv) {
+        if (!existsSync(fromEnv.path)) {
+            throw new Error(`[BrowserManager] Chrome binary not found at ${fromEnv.name}="${fromEnv.path}". ` +
                 "Run `hyperframes browser ensure` to re-download.");
         }
-        return envPath;
-    }
-    if (process.env.HYPERFRAMES_BROWSER_PATH) {
-        const envPath = process.env.HYPERFRAMES_BROWSER_PATH;
-        if (!existsSync(envPath)) {
-            throw new Error(`[BrowserManager] Chrome binary not found at HYPERFRAMES_BROWSER_PATH="${envPath}". ` +
-                "Run `hyperframes browser ensure` to re-download.");
-        }
-        return envPath;
+        return fromEnv.path;
     }
     const ours = join(homedir(), ".cache", "hyperframes", "chrome", "chrome-headless-shell");
     const shared = join(homedir(), ".cache", "puppeteer", "chrome-headless-shell");

package/dist/services/chromeHostCeiling.d.ts

@@ -11,3 +11,8 @@ export declare function shellStarts(binary: string): boolean;
 /** The shared Puppeteer cache's shell: the managed build, else the newest under the host's ceiling that starts.
  * `shell` names a version dir's executable, or undefined when it holds no usable file. */
 export declare function pickSharedShell(versions: readonly string[], shell: (version: string) => string | undefined): string | undefined;
+/** The browser binary an env var names. The CLI and the engine both resolve it here, HYPERFRAMES_BROWSER_PATH first. */
+export declare function browserPathFromEnv(env?: NodeJS.ProcessEnv): {
+    name: "HYPERFRAMES_BROWSER_PATH" | "PRODUCER_HEADLESS_SHELL_PATH";
+    path: string;
+} | undefined;

package/dist/services/chromeHostCeiling.js

@@ -80,3 +80,12 @@ export function pickSharedShell(versions, shell) {
     }
     return undefined;
 }
+/** The browser binary an env var names. The CLI and the engine both resolve it here, HYPERFRAMES_BROWSER_PATH first. */
+export function browserPathFromEnv(env = process.env) {
+    for (const name of ["HYPERFRAMES_BROWSER_PATH", "PRODUCER_HEADLESS_SHELL_PATH"]) {
+        const path = env[name];
+        if (path)
+            return { name, path };
+    }
+    return undefined;
+}

package/dist/services/chunkEncoder.js

@@ -143,7 +143,8 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
             "Stripping HDR metadata and tagging output as SDR/BT.709. Use codec=h265 for HDR output.");
         options = { ...options, hdr: undefined };
     }
-    const args = [...inputArgs, "-r", fpsToFfmpegArg(fps)];
+    // Without -xerror, ffmpeg ends the video at the first frame file it cannot read and still exits 0.
+    const args = ["-xerror", ...inputArgs, "-r", fpsToFfmpegArg(fps)];
     const shouldUseGpu = useGpu && gpuEncoder !== null;
     if (codec === "h264" || codec === "h265") {
         if (shouldUseGpu) {
@@ -363,6 +364,16 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
     return args;
 }
 const framesReader = (onFrames) => onFrames && ffmpegStatsReader(({ frames }) => frames !== undefined && onFrames(frames));
+/** ffmpeg's frame read error, which the encoder summary pushes out of the stderr tail, and where it stopped. */
+function frameReadFailure(stderr, framePattern, startNumber, framesRead, frameCount) {
+    const lines = stderr.match(/^.*(?:Error during demuxing|Could not open file).*$/gm) ?? [];
+    const readError = [...new Set(lines.map((line) => line.trim()))].join("; ");
+    if (!readError)
+        return "";
+    const name = framePattern.replace(/%0(\d+)d/, (_, width) => String(startNumber + framesRead).padStart(Number(width), "0"));
+    const at = framesRead < frameCount ? ` at ${name} (${framesRead} of ${frameCount} read)` : "";
+    return `[FFmpeg] could not read a frame${at}: ${readError}\n`;
+}
 const secondsReader = (onSeconds) => onSeconds && ffmpegStatsReader(({ seconds }) => seconds !== undefined && onSeconds(seconds));
 export async function encodeFramesFromDir(framesDir, framePattern, outputPath, options, signal, config, onFramesEncoded) {
     const startTime = Date.now();
@@ -389,10 +400,14 @@ export async function encodeFramesFromDir(framesDir, framePattern, outputPath, o
     const inputArgs = ["-framerate", fpsToFfmpegArg(options.fps), "-i", inputPath];
     const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder);
     const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
+    let framesRead = 0;
     const result = await runFfmpeg(args, {
         signal,
         timeout: encodeTimeout,
-        onStderr: framesReader(onFramesEncoded),
+        onStderr: framesReader((frames) => {
+            framesRead = frames;
+            onFramesEncoded?.(frames);
+        }),
     });
     if (result.terminationReason === "abort") {
         return {
@@ -411,7 +426,8 @@ export async function encodeFramesFromDir(framesDir, framePattern, outputPath, o
             durationMs: result.durationMs,
             framesEncoded: 0,
             fileSize: 0,
-            error: appendEncodeTimeoutMessage(formatFfmpegError(result.exitCode, result.stderr), result.terminationReason === "deadline", encodeTimeout),
+            error: appendEncodeTimeoutMessage(frameReadFailure(result.stderr, framePattern, 0, framesRead, frameCount) +
+                formatFfmpegError(result.exitCode, result.stderr), result.terminationReason === "deadline", encodeTimeout),
             failureReason: isExternalFfmpegInterruption(result) ? "external_interruption" : undefined,
         };
     }
@@ -534,16 +550,20 @@ export async function encodeFramesChunkedConcat(framesDir, framePattern, outputP
             gpuEncoder = await getCachedGpuEncoder();
         const args = buildEncoderArgs(options, inputArgs, chunkPath, gpuEncoder);
         const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
+        let framesRead = 0;
         const processResult = await runFfmpeg(args, {
             signal,
             timeout: encodeTimeout,
-            onStderr: framesReader(onFramesEncoded && ((frames) => onFramesEncoded(startNumber + frames))),
+            onStderr: framesReader((frames) => {
+                framesRead = frames;
+                onFramesEncoded?.(startNumber + frames);
+            }),
         });
         const chunkResult = {
             success: processResult.success,
             error: processResult.success
                 ? undefined
-                : appendEncodeTimeoutMessage(`Chunk ${i} encode failed: ${processResult.stderr.slice(-400)}`, processResult.terminationReason === "deadline", encodeTimeout),
+                : appendEncodeTimeoutMessage(frameReadFailure(processResult.stderr, framePattern, startNumber, framesRead, framesInChunk) + `Chunk ${i} encode failed: ${processResult.stderr.slice(-400)}`, processResult.terminationReason === "deadline", encodeTimeout),
         };
         if (!chunkResult.success) {
             return {

package/dist/services/frameCapture.d.ts

@@ -416,6 +416,7 @@ export interface SubTimelinePollOptions {
 export declare function pollSubCompositionTimelines(page: Page, timeoutMs: number, { intervalMs, getScriptLoadFailures, scriptFailureGraceMs, onPending, shouldStop, knownUnregisteredIds, }?: SubTimelinePollOptions): Promise<SubTimelineWaitOutcome>;
 /** @internal exported for unit testing only */
 export declare function pollImagesReady(page: Page, timeoutMs: number, intervalMs?: number): Promise<boolean>;
+export declare function waitForImagesReady(page: Page, timeoutMs: number, onUnloaded: (sources: string) => void): Promise<boolean>;
 /** @internal exported for contract testing. */
 export declare function collectMediaReadinessWarnings(page: Page, skipIds: readonly string[], timeoutMs: number): Promise<CaptureWarning[]>;
 export declare function recordSubTimelineWarning(session: CaptureSession, timeoutMs: number): void;

package/dist/services/frameCapture.js

@@ -7,7 +7,6 @@
  * 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";
@@ -860,6 +859,7 @@ async function constructCaptureSession(input) {
     // 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.
+    const { CDPSession } = await import("puppeteer-core");
     if ("client" in frame && frame.client instanceof CDPSession) {
         await frame.client.send("Network.enable", {
             maxTotalBufferSize: 32 * 1024 * 1024,
@@ -1356,6 +1356,22 @@ export async function pollImagesReady(page, timeoutMs, intervalMs = 100) {
     }
     return check();
 }
+export async function waitForImagesReady(page, timeoutMs, onUnloaded) {
+    const ready = await pollImagesReady(page, timeoutMs);
+    if (!ready) {
+        onUnloaded(await page.evaluate(() => Array.from(document.querySelectorAll("img"))
+            .filter((img) => {
+            const src = img.getAttribute("src") || "";
+            if (!src || src.startsWith("data:"))
+                return false;
+            return !(img.complete && img.naturalWidth > 0);
+        })
+            .map((img) => img.src || img.getAttribute("src") || "(no src)")
+            .join(", ")));
+    }
+    await decodeAllImages(page);
+    return ready;
+}
 /** @internal exported for contract testing. */
 export async function collectMediaReadinessWarnings(page, skipIds, timeoutMs) {
     const snapshot = await page.evaluate((skipIdList) => {
@@ -1769,26 +1785,8 @@ export async function initializeSession(session) {
         const skipVideoIds = session.options.skipReadinessVideoIds ?? [];
         const [videosReady] = await Promise.all([
             pollVideosReady(page, skipVideoIds, pageReadyTimeout),
-            pollImagesReady(page, pageReadyTimeout).then(async (ready) => {
-                if (!ready) {
-                    const failedImages = await page.evaluate(() => {
-                        return Array.from(document.querySelectorAll("img"))
-                            .filter((img) => {
-                            const ie = img;
-                            const src = ie.getAttribute("src") || "";
-                            if (!src || src.startsWith("data:"))
-                                return false;
-                            return !(ie.complete && ie.naturalWidth > 0);
-                        })
-                            .map((img) => img.src || img.getAttribute("src") || "(no src)")
-                            .join(", ");
-                    });
-                    console.warn(`[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
-                        `Continuing render. Affected images may appear blank/missing in early frames.`);
-                }
-                await decodeAllImages(page);
-                return ready;
-            }),
+            waitForImagesReady(page, pageReadyTimeout, (failedImages) => console.warn(`[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
+                `Continuing render. Affected images may appear blank/missing in early frames.`)),
             page.evaluate(`document.fonts?.ready`),
             waitForOptionalTailwindReady(page, pageReadyTimeout),
         ]);
@@ -1899,26 +1897,8 @@ export async function initializeSession(session) {
         const bfSkipVideoIds = session.options.skipReadinessVideoIds ?? [];
         const [bfVideosReady] = await Promise.all([
             pollVideosReady(page, bfSkipVideoIds, pageReadyTimeout),
-            pollImagesReady(page, pageReadyTimeout).then(async (ready) => {
-                if (!ready) {
-                    const failedImages = await page.evaluate(() => {
-                        return Array.from(document.querySelectorAll("img"))
-                            .filter((img) => {
-                            const ie = img;
-                            const src = ie.getAttribute("src") || "";
-                            if (!src || src.startsWith("data:"))
-                                return false;
-                            return !(ie.complete && ie.naturalWidth > 0);
-                        })
-                            .map((img) => img.src || img.getAttribute("src") || "(no src)")
-                            .join(", ");
-                    });
-                    console.warn(`[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
-                        `Continuing render. Affected images may appear blank/missing in early frames.`);
-                }
-                await decodeAllImages(page);
-                return ready;
-            }),
+            waitForImagesReady(page, pageReadyTimeout, (failedImages) => console.warn(`[FrameCapture] Some image elements did not load within ${pageReadyTimeout}ms: ${failedImages}. ` +
+                `Continuing render. Affected images may appear blank/missing in early frames.`)),
             page.evaluate(`document.fonts?.ready`),
             waitForOptionalTailwindReady(page, pageReadyTimeout),
         ]);

package/dist/services/referenceResolver.d.ts

@@ -1,38 +1 @@
-/**
- * Node-side resolver for relative `data-start` timing references, shared by
- * every parser that reads media timing out of compiled HTML — video frames
- * (`parseVideoElements`), images (`parseImageElements`), and audio
- * (`parseAudioElements`). Keeping the resolution in ONE place is load-bearing:
- * if audio and video disagree on what `data-start="intro"` means, a relative
- * reference that renders a video at the right time silently drops the audio
- * track (they used to — audio parsed `parseFloat("intro") = NaN`).
- *
- * Mirrors the browser runtime's startResolver so `snapshot`/`render` agree.
- * DOM access is via a minimal structural shape so it works against linkedom
- * (Node) without pulling in lib.dom types.
- */
-/** Minimal structural DOM shape the reference resolver needs. */
-export interface RefResolverEl {
-    getAttribute(name: string): string | null;
-}
-export interface RefResolverDoc {
-    getElementById(id: string): RefResolverEl | null;
-    querySelector(selector: string): RefResolverEl | null;
-}
-/**
- * Resolve an element's absolute start time (seconds) the same way the browser
- * runtime's startResolver does, so `<video data-start="intro">` (a relative
- * reference to another clip's end) renders at the right time instead of
- * producing NaN and compositing blank / dropping audio. Durations come from
- * `data-duration` or `data-end` here; the natural-media-duration fallback isn't
- * known at parse time, so — exactly like the runtime — an unknown-duration
- * reference falls back to the target's start and an unknown target falls back
- * to 0 (never NaN).
- */
-export declare function resolveReferencedStart(doc: RefResolverDoc, el: RefResolverEl, startCache: Map<RefResolverEl, number>, visiting: Set<RefResolverEl>): number;
-/**
- * Duration of a referenced clip, from `data-duration` or `data-end - start`.
- * Returns null when only the natural media duration would settle it (unknown
- * at parse time) — the caller then treats the reference as duration-0.
- */
-export declare function resolveReferencedDuration(doc: RefResolverDoc, el: RefResolverEl, startCache: Map<RefResolverEl, number>, visiting: Set<RefResolverEl>): number | null;
+export * from "@hyperframes/parsers/reference-resolver";

package/dist/services/referenceResolver.js

@@ -1,87 +1,2 @@
-/**
- * Node-side resolver for relative `data-start` timing references, shared by
- * every parser that reads media timing out of compiled HTML — video frames
- * (`parseVideoElements`), images (`parseImageElements`), and audio
- * (`parseAudioElements`). Keeping the resolution in ONE place is load-bearing:
- * if audio and video disagree on what `data-start="intro"` means, a relative
- * reference that renders a video at the right time silently drops the audio
- * track (they used to — audio parsed `parseFloat("intro") = NaN`).
- *
- * Mirrors the browser runtime's startResolver so `snapshot`/`render` agree.
- * DOM access is via a minimal structural shape so it works against linkedom
- * (Node) without pulling in lib.dom types.
- */
-import { parseNumeric, parseStartExpression } from "@hyperframes/core";
-/**
- * Find the element a relative `data-start` reference points at — by `id`
- * first, then by `data-composition-id` (a sub-composition can be referenced).
- * The reference-id grammar (see parseStartExpression) is restricted to
- * `[A-Za-z0-9_.:-]`, none of which need escaping inside a quoted attribute
- * selector, so no CSS.escape (absent in linkedom) is required.
- */
-function findReferenceTargetEl(doc, refId) {
-    return doc.getElementById(refId) ?? doc.querySelector(`[data-composition-id="${refId}"]`);
-}
-/**
- * Resolve an element's absolute start time (seconds) the same way the browser
- * runtime's startResolver does, so `<video data-start="intro">` (a relative
- * reference to another clip's end) renders at the right time instead of
- * producing NaN and compositing blank / dropping audio. Durations come from
- * `data-duration` or `data-end` here; the natural-media-duration fallback isn't
- * known at parse time, so — exactly like the runtime — an unknown-duration
- * reference falls back to the target's start and an unknown target falls back
- * to 0 (never NaN).
- */
-export function resolveReferencedStart(doc, el, startCache, visiting) {
-    const cached = startCache.get(el);
-    if (cached !== undefined)
-        return cached;
-    if (visiting.has(el))
-        return 0; // cycle guard (A -> B -> A)
-    visiting.add(el);
-    try {
-        const expression = parseStartExpression(el.getAttribute("data-start"));
-        if (!expression) {
-            startCache.set(el, 0);
-            return 0;
-        }
-        if (expression.kind === "absolute") {
-            const value = Math.max(0, expression.value);
-            startCache.set(el, value);
-            return value;
-        }
-        const target = findReferenceTargetEl(doc, expression.refId);
-        if (!target) {
-            startCache.set(el, 0);
-            return 0;
-        }
-        const targetStart = resolveReferencedStart(doc, target, startCache, visiting);
-        const targetDuration = resolveReferencedDuration(doc, target, startCache, visiting);
-        const resolved = targetDuration != null && targetDuration > 0
-            ? Math.max(0, targetStart + targetDuration + expression.offset)
-            : Math.max(0, targetStart + expression.offset);
-        startCache.set(el, resolved);
-        return resolved;
-    }
-    finally {
-        visiting.delete(el);
-    }
-}
-/**
- * Duration of a referenced clip, from `data-duration` or `data-end - start`.
- * Returns null when only the natural media duration would settle it (unknown
- * at parse time) — the caller then treats the reference as duration-0.
- */
-export function resolveReferencedDuration(doc, el, startCache, visiting) {
-    const durationAttr = parseNumeric(el.getAttribute("data-duration"));
-    if (durationAttr != null && durationAttr > 0)
-        return durationAttr;
-    const endAttr = parseNumeric(el.getAttribute("data-end"));
-    if (endAttr != null) {
-        const start = resolveReferencedStart(doc, el, startCache, visiting);
-        const delta = endAttr - start;
-        if (Number.isFinite(delta) && delta > 0)
-            return delta;
-    }
-    return null;
-}
+// Kept for existing importers; the resolver lives in @hyperframes/parsers.
+export * from "@hyperframes/parsers/reference-resolver";

package/dist/services/videoFrameExtractor.d.ts

@@ -108,6 +108,10 @@ export interface ExtractionOptions {
     /** Directories the caller rewrites on every render (downloaded media); their sources are cached by content. */
     contentKeyedDirs?: readonly string[];
     urlByAbsentLocalPath?: ReadonlyMap<string, string>;
+    shownBox?: {
+        width: number;
+        height: number;
+    };
 }
 export declare const EXTRACT_CACHE_MIN_AGE_MS: number;
 /**

package/dist/services/videoFrameExtractor.js

@@ -16,7 +16,7 @@ import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution
 import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
-import { extractFinalVideoFrameTimestamp, extractMediaMetadata, } from "../utils/ffprobe.js";
+import { extractFinalVideoFrameTimestamp, extractMediaMetadata, mediaFileIdentity, readMetadataCache, writeMetadataCache, } from "../utils/ffprobe.js";
 import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPlaneProbe.js";
 import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
@@ -115,6 +115,12 @@ const SDR_TO_HDR_COLORSPACE_FILTER = "colorspace=all=bt2020:iall=bt709:range=tv"
 const HDR_TO_SDR_ZSCALE_TRANSFORM_KEY = "hdr2sdr-hable-srgb";
 const HDR_TO_SDR_VIDEOTOOLBOX_TRANSFORM_KEY = "hdr2sdr-videotoolbox-hdr";
 const SDR_CANVAS_PASSTHROUGH_FILTER = "setparams=color_primaries=bt709:color_trc=iec61966-2-1";
+function halveToCoverScaleFilter(box) {
+    const fit = `max(${Math.ceil(box.width)}/iw\\,${Math.ceil(box.height)}/ih)`;
+    const halvings = `floor(log(1/${fit})/log(2))`;
+    const side = (dim) => `if(lt(${fit}\\,0.5)\\,2*ceil(${dim}/pow(2\\,${halvings})/2)\\,${dim})`;
+    return `scale=w=${side("iw")}:h=${side("ih")}:flags=area+accurate_rnd`;
+}
 const SDR_JPEG_AS_BT601_FULL_RANGE_FILTER = "scale=flags=neighbor+accurate_rnd,format=gbrp,scale=out_color_matrix=bt601:out_range=pc:flags=neighbor,format=yuv420p";
 let warnedMissingZscale = false;
 async function toneMapsWithZscale() {
@@ -417,12 +423,23 @@ export function parseImageElements(html) {
     }
     return images;
 }
-/** The first shown frame's colour tags; see {@link firstFrameColourArgs}. */
-async function readFirstFrameColour(videoPath, signal) {
-    const result = await runFfmpeg([...urlInputArgs(videoPath), ...firstFrameColourArgs(videoPath)], {
-        signal,
+const firstFrameColourCache = new Map();
+/** The first shown frame's colour tags (see {@link firstFrameColourArgs}), probed once per source file. */
+function readFirstFrameColour(videoPath) {
+    const identity = mediaFileIdentity(videoPath);
+    const cached = readMetadataCache(firstFrameColourCache, videoPath, identity);
+    if (cached)
+        return cached;
+    // In an extraction slot, so it never adds a decoder; unsignalled, so one cancel cannot cut it short for others.
+    const probe = inExtractionSlot(() => runFfmpeg([...urlInputArgs(videoPath), ...firstFrameColourArgs(videoPath)])).then((result) => {
+        // A failed probe answers this cut only; the next one probes again.
+        if (!result.success && firstFrameColourCache.get(videoPath)?.promise === probe) {
+            firstFrameColourCache.delete(videoPath);
+        }
+        return parseFirstFrameColour(result.stderr);
     });
-    return parseFirstFrameColour(result.stderr);
+    writeMetadataCache(firstFrameColourCache, videoPath, identity, probe);
+    return probe;
 }
 /** Chrome plays untagged VP9 and AV1 as BT.601, H.264 and VP8 as BT.709 from 720 coded lines (assumed for the rest). */
 const CHROME_BT601_UNTAGGED_CODECS = new Set(["vp9", "av1"]);
@@ -434,10 +451,9 @@ function chromeGuessForUntaggedMatrix(metadata) {
     return [`setparams=colorspace=${hd ? "bt709" : "smpte170m"}`];
 }
 /**
- * Longest stretch of output one ffmpeg process extracts. `ffmpegProcessTimeout` bounds a
- * single process, so one process over a long clip timed out however much time the render
- * had left. Longer ranges split into segments that run side by side. Segments sample the
- * same absolute times as a single pass, so their frames are byte-identical to it.
+ * Longest stretch of output one ffmpeg process extracts; longer ranges split into segments
+ * that run side by side. Segments sample the same absolute times as a single pass, so their
+ * frames are byte-identical to it.
  */
 const EXTRACTION_SEGMENT_SECONDS = 120;
 /** Frame times since file start are `PTS*TB + seek`; snapping them to `lead + k/FR` gives every process one grid. */
@@ -624,20 +640,24 @@ outputDirOverride) {
         vfFilters.push(SDR_TO_HDR_COLORSPACE_FILTER);
     }
     if (toneMappedToSdr) {
-        const frameColour = await readFirstFrameColour(videoPath, signal);
+        const frameColour = await readFirstFrameColour(videoPath);
         vfFilters.push(hdrToSdrToneMapFilter(metadata.colorSpace ?? {}, frameColour));
     }
     if (toneMappedToSdr || (!isHdr && !options.sdrToHdrTransfer)) {
         vfFilters.push(...(isHdr ? [] : chromeGuessForUntaggedMatrix(metadata)), SDR_CANVAS_PASSTHROUGH_FILTER);
-        if (format === "jpg")
+        if (format === "jpg") {
+            if (options.shownBox)
+                vfFilters.push(halveToCoverScaleFilter(options.shownBox));
             vfFilters.push(SDR_JPEG_AS_BT601_FULL_RANGE_FILTER);
+        }
     }
     const encodeArgs = ["-q:v", format === "jpg" ? String(Math.ceil((100 - quality) / 3)) : "0"];
     // Render-scoped temp frames are read once; level 1 measured 3-5x faster for ~14% larger files.
     if (format === "png")
         encodeArgs.push("-compression_level", "1");
     encodeArgs.push("-y", outputPattern);
-    const runOptions = { signal, timeout: ffmpegProcessTimeout };
+    // A long 4K run can take far longer than the timeout and still be healthy; only a stall is a hang.
+    const runOptions = { signal, stallTimeout: ffmpegProcessTimeout };
     const filterArgsFor = (seek) => {
         const filters = [...vfFilters];
         filters.splice(samplingAt, 0, ...samplingFilters(seek));
@@ -677,8 +697,8 @@ outputDirOverride) {
         const hdrPrefix = options.sdrToHdrTransfer
             ? `SDR→HDR conversion failed (colorspace filter in extract pass, target ${options.sdrToHdrTransfer}): `
             : "";
-        const timedOut = processResult.terminationReason === "deadline";
-        const timeoutSuffix = timedOut ? ` (timed out after ${ffmpegProcessTimeout} ms)` : "";
+        const timedOut = processResult.terminationReason === "inactivity";
+        const timeoutSuffix = timedOut ? ` (no new frame for ${ffmpegProcessTimeout} ms)` : "";
         const diagnostic = `${hdrPrefix}FFmpeg exited with code ${processResult.exitCode}${timeoutSuffix}: ` +
             processResult.stderr.slice(-500);
         if (timedOut) {
@@ -1562,7 +1582,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
             : join(options.outputDir, group.groupId);
         try {
             rmSync(tempDir, { recursive: true, force: true });
-            // A long union can hit the fixed FFmpeg deadline even when each shorter
+            // A long union can fail even when each shorter
             // member range succeeds. Do not retry the optimization itself; preserve
             // the established grouped→direct fallback and apply bounded retries only
             // to the individual source ranges below.

package/dist/services/videoFrameInjector.d.ts

@@ -83,6 +83,15 @@ export declare function hideVideoElements(page: Page, videoIds: string[]): Promi
  * Restore visibility of video elements after a DOM screenshot.
  */
 export declare function showVideoElements(page: Page, videoIds: string[]): Promise<void>;
+export interface ShownBox {
+    width: number;
+    height: number;
+}
+/**
+ * Seeks to each of `times`; returns each video's largest drawn box in device pixels. Videos that are
+ * graded, sampled by a canvas, `object-fit: none | scale-down` or never laid out get none (full size).
+ */
+export declare function measureVideoShownBoxes(page: Page, videoIds: readonly string[], times: readonly number[]): Promise<Map<string, ShownBox>>;
 /**
  * Query the current bounds, transform, and visibility of video elements.
  * Called after seeking (so GSAP has moved things) but before the screenshot.

package/dist/services/videoFrameInjector.js

@@ -10,7 +10,7 @@ import { promises as fs } from "fs";
 import { touchCacheDir } from "./extractionCache.js";
 import { injectVideoFramesBatch, syncVideoFrameVisibility } from "./screenshotService.js";
 import { DEFAULT_CONFIG } from "../config.js";
-import { HF_COLOR_GRADING_CANVAS_ID_PREFIX, RENDER_FRAME_ID_PREFIX, RENDER_FRAME_ID_SUFFIX, renderFrameIdForRenderId, } from "@hyperframes/core";
+import { HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_CANVAS_ID_PREFIX, RENDER_FRAME_ID_PREFIX, RENDER_FRAME_ID_SUFFIX, renderFrameIdForRenderId, } from "@hyperframes/core";
 /**
  * Two-bound LRU keyed by frame path. Either bound triggers eviction of the
  * oldest entry — entry count protects against pathological many-tiny-frames
@@ -247,6 +247,53 @@ async function setVideoElementsVisibility(page, videoIds, visible) {
     // format has one definition across the engine and the runtime readers.
     videoIds.map((id) => ({ id, frameId: renderFrameIdForRenderId(id) })), HF_COLOR_GRADING_CANVAS_ID_PREFIX, visible);
 }
+/**
+ * Seeks to each of `times`; returns each video's largest drawn box in device pixels. Videos that are
+ * graded, sampled by a canvas, `object-fit: none | scale-down` or never laid out get none (full size).
+ */
+export async function measureVideoShownBoxes(page, videoIds, times) {
+    if (videoIds.length === 0 || times.length === 0)
+        return new Map();
+    const boxes = await page.evaluate(async (ids, seekTimes, gradingAttr, gradingCanvasPrefix) => {
+        const hf = window.__hf;
+        if (typeof hf?.seek !== "function")
+            return [];
+        const waitForSeek = window
+            .__hfWaitForSeekCompletion;
+        const largest = new Map();
+        const fullSize = new Set();
+        const keepsFullSize = (video) => {
+            if (video.hasAttribute(gradingAttr))
+                return true;
+            const fit = window.getComputedStyle(video).objectFit;
+            return fit === "none" || fit === "scale-down";
+        };
+        const measure = (id) => {
+            const video = window.__hfMediaEl?.(id) ?? document.getElementById(id);
+            if (!video || keepsFullSize(video)) {
+                fullSize.add(id);
+                return;
+            }
+            const rect = video.getBoundingClientRect();
+            const box = largest.get(id) ?? { width: 0, height: 0 };
+            box.width = Math.max(box.width, rect.width * window.devicePixelRatio);
+            box.height = Math.max(box.height, rect.height * window.devicePixelRatio);
+            largest.set(id, box);
+        };
+        const pageHasCanvas = () => Array.from(document.querySelectorAll("canvas")).some((canvas) => !canvas.id.startsWith(gradingCanvasPrefix));
+        for (const t of seekTimes) {
+            hf.seek(t);
+            await waitForSeek?.();
+            // A canvas could sample any video, so every video keeps full size.
+            if (pageHasCanvas())
+                return [];
+            for (const id of ids)
+                measure(id);
+        }
+        return Array.from(largest).filter(([id, box]) => !fullSize.has(id) && box.width > 0 && box.height > 0);
+    }, [...videoIds], [...times], HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_CANVAS_ID_PREFIX);
+    return new Map(boxes);
+}
 /**
  * Query the current bounds, transform, and visibility of video elements.
  * Called after seeking (so GSAP has moved things) but before the screenshot.

package/dist/utils/ffprobe.d.ts

@@ -1,3 +1,7 @@
+export interface MediaProbeCacheEntry<T = FFProbeOutput> {
+    identity: string | null;
+    promise: Promise<T>;
+}
 export interface VideoColorSpace {
     /** Color transfer characteristics, e.g. "bt709", "smpte2084", "arib-std-b67" */
     colorTransfer: string;
@@ -48,6 +52,42 @@ export interface AudioMetadata {
     /** Seconds after the file's media time 0 at which its last audio or video stream starts. */
     latestStreamLeadSeconds?: number;
 }
+interface FFProbeStream {
+    codec_type: string;
+    codec_name?: string;
+    /** e.g. "LC", "HE-AAC", "HE-AACv2" — where the SBR marker lives, since
+     *  codec_name is plain "aac" for all of them. */
+    profile?: string;
+    width?: number;
+    height?: number;
+    duration?: string;
+    start_time?: string;
+    nb_frames?: string;
+    nb_read_packets?: string;
+    pix_fmt?: string;
+    r_frame_rate?: string;
+    avg_frame_rate?: string;
+    sample_rate?: string;
+    channels?: number;
+    color_range?: string;
+    color_transfer?: string;
+    color_primaries?: string;
+    color_space?: string;
+    tags?: Record<string, string>;
+    disposition?: {
+        attached_pic?: number;
+    };
+}
+interface FFProbeFormat {
+    duration?: string;
+    start_time?: string;
+    bit_rate?: string;
+    format_name?: string;
+}
+interface FFProbeOutput {
+    streams: FFProbeStream[];
+    format: FFProbeFormat;
+}
 interface StillImageMetadata {
     width: number;
     height: number;
@@ -58,6 +98,9 @@ export interface MediaProbeProfile {
     hasAudioStream: boolean;
     visualKind: "none" | "still" | "moving";
 }
+export declare function mediaFileIdentity(filePath: string): string | null;
+export declare function readMetadataCache<T>(cache: Map<string, MediaProbeCacheEntry<T>>, key: string, identity: string | null): Promise<T> | undefined;
+export declare function writeMetadataCache<T>(cache: Map<string, MediaProbeCacheEntry<T>>, key: string, identity: string | null, promise: Promise<T>): void;
 /**
  * Probe stream capabilities without assuming the caller's element type.
  * File extensions and HTTP MIME are deliberately ignored: extensionless

package/dist/utils/ffprobe.js

@@ -209,7 +209,7 @@ function isPngImageProbe(output) {
     return (formatNames.includes("png_pipe") ||
         output.streams.some((stream) => stream.codec_type === "video" && stream.codec_name?.toLowerCase() === "png"));
 }
-function mediaFileIdentity(filePath) {
+export function mediaFileIdentity(filePath) {
     try {
         const stat = statSync(filePath, { bigint: true });
         return [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
@@ -218,11 +218,11 @@ function mediaFileIdentity(filePath) {
         return null;
     }
 }
-function readMetadataCache(cache, key, identity) {
+export function readMetadataCache(cache, key, identity) {
     const cached = cache.get(key);
     return cached?.identity === identity ? cached.promise : undefined;
 }
-function writeMetadataCache(cache, key, identity, promise) {
+export function writeMetadataCache(cache, key, identity, promise) {
     const entry = { identity, promise };
     cache.set(key, entry);
     void promise.then(() => {

package/dist/utils/notMediaPayload.d.ts

@@ -12,8 +12,8 @@ export declare const NOT_MEDIA_PAYLOAD: "NOT_MEDIA_PAYLOAD";
  *
  * Only a 2xx response reaches this classifier. `downloadToTemp` rejects a
  * 404/410 as `http_not_found` before writing a byte (urlDownloader.ts
- * `classifyHttpFailure`), and every ffprobe input is local — an http src is
- * downloaded first. So the shapes that land here are a soft-404 or
+ * `classifyHttpFailure`), and an authored http src is downloaded first (a cloud-held
+ * project file is read by URL, which the sniff cannot open). So the shapes that land here are a soft-404 or
  * interstitial HTML body, an S3/CloudFront error document, or a JSON API error
  * body, each served with a success status.
  *

package/dist/utils/notMediaPayload.js

@@ -16,8 +16,8 @@ const MAX_LISTED_FINGERPRINTS = 8;
  *
  * Only a 2xx response reaches this classifier. `downloadToTemp` rejects a
  * 404/410 as `http_not_found` before writing a byte (urlDownloader.ts
- * `classifyHttpFailure`), and every ffprobe input is local — an http src is
- * downloaded first. So the shapes that land here are a soft-404 or
+ * `classifyHttpFailure`), and an authored http src is downloaded first (a cloud-held
+ * project file is read by URL, which the sniff cannot open). So the shapes that land here are a soft-404 or
  * interstitial HTML body, an S3/CloudFront error document, or a JSON API error
  * body, each served with a success status.
  *

package/dist/utils/runFfmpeg.d.ts

@@ -8,6 +8,8 @@ import { type ManagedProcessTerminationReason } from "./managedChildProcess.js";
 export interface RunFfmpegOptions {
     signal?: AbortSignal;
     timeout?: number;
+    /** Replaces `timeout`: stop only once this long passes without a new output frame. */
+    stallTimeout?: number;
     onStderr?: (line: string) => void;
 }
 export interface RunFfmpegResult {

package/dist/utils/runFfmpeg.js

@@ -147,11 +147,25 @@ const ABORTED_BEFORE_START = {
 export async function runFfmpeg(args, opts) {
     if (opts?.signal?.aborted)
         return { ...ABORTED_BEFORE_START };
-    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+    const stallTimeout = opts?.stallTimeout;
+    let framesWritten = 0;
+    const readStats = ffmpegStatsReader(({ frames }) => {
+        if (frames === undefined || frames <= framesWritten)
+            return;
+        framesWritten = frames;
+        managed.markActivity();
+    });
     const managed = new ManagedChildProcess(spawnFfmpeg(args), {
         signal: opts?.signal,
-        deadlineAtMs: Date.now() + timeout,
-        onStderr: opts?.onStderr,
+        ...(stallTimeout === undefined
+            ? { deadlineAtMs: Date.now() + (opts?.timeout ?? DEFAULT_TIMEOUT) }
+            : { inactivityTimeoutMs: stallTimeout }),
+        onStderr: stallTimeout === undefined
+            ? opts?.onStderr
+            : (chunk) => {
+                readStats(chunk);
+                opts?.onStderr?.(chunk);
+            },
     });
     return toResult(await managed.wait());
 }

package/package.json

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