@hyperframes/engine 0.8.181 → 0.8.184

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";
@@ -53,7 +53,7 @@ export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCo
 export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioFailureDiagnostic, AudioSubprocessEvidence, 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";
+export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type LandedFrame, type ParallelProgress, } from "./services/parallelCoordinator.js";
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";
@@ -64,7 +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 } from "./services/aacEncode.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";
@@ -75,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,7 +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 } from "./services/aacEncode.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";
@@ -83,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/parallelCoordinator.d.ts

@@ -55,6 +55,13 @@ export interface ParallelProgress {
     workerProgress: Map<number, number>;
     /** Latest lifecycle transition; absent on ordinary completed-frame updates. */
     latestWorkerPhase?: ParallelWorkerPhaseDiagnostic;
+    /** Disk capture only: the frame file this update finished writing, readable from now on. */
+    landedFrame?: LandedFrame;
+}
+/** A captured frame file: `index` is its file index (`frame_<index>`), `path` where it was written. */
+export interface LandedFrame {
+    index: number;
+    path: string;
 }
 export type ParallelWorkerPhase = "browser_launch" | "browser_probe" | "session_init" | "frame_capture" | "frame_encode";
 export interface ParallelWorkerPhaseDiagnostic {

package/dist/services/parallelCoordinator.js

@@ -400,16 +400,18 @@ async function captureFrameRange(session, task, captureOptions, signal, onFrameC
             throw new Error("Parallel worker cancelled");
         const time = (i * captureOptions.fps.den) / captureOptions.fps.num;
         const fileFrameIdx = i - outputOffset;
+        let landedFrame;
         if (onFrameBuffer) {
             const { buffer } = await runCaptureOperation("frame_capture", i, () => captureFrameToBuffer(session, fileFrameIdx, time));
             await onFrameBuffer(i, buffer, session);
         }
         else {
-            await runCaptureOperation("frame_capture", i, () => captureFrame(session, fileFrameIdx, time));
+            const { path } = await runCaptureOperation("frame_capture", i, () => captureFrame(session, fileFrameIdx, time));
+            landedFrame = { index: fileFrameIdx, path };
         }
         framesCaptured++;
         if (onFrameCaptured)
-            onFrameCaptured(task.workerId, i);
+            onFrameCaptured(task.workerId, i, landedFrame);
     }
     return framesCaptured;
 }
@@ -722,7 +724,7 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
     const workerPhases = new Map();
     for (const task of tasks)
         workerProgress.set(task.workerId, 0);
-    const onFrameCaptured = (workerId, _frameIndex) => {
+    const onFrameCaptured = (workerId, _frameIndex, landedFrame) => {
         const current = workerProgress.get(workerId) || 0;
         workerProgress.set(workerId, current + 1);
         if (onProgress) {
@@ -732,6 +734,7 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
                 capturedFrames,
                 activeWorkers: tasks.length,
                 workerProgress: new Map(workerProgress),
+                ...(landedFrame && { landedFrame }),
             });
         }
     };

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

@@ -13,6 +13,7 @@ import { createConcurrencyLimit } from "../utils/concurrencyLimit.js";
 import { parseHTML } from "linkedom";
 import { isPathInside } from "@hyperframes/parsers/asset-paths";
 import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution";
+import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
 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";
@@ -115,6 +116,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() {
@@ -639,8 +646,11 @@ outputDirOverride) {
     }
     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.
@@ -949,12 +959,7 @@ export function codecMayHaveAlpha(codec) {
     return ALPHA_CAPABLE_CODECS.has((codec ?? "").toLowerCase());
 }
 export function decoderForCodec(codec) {
-    const c = (codec ?? "").toLowerCase();
-    if (c === "vp9")
-        return "libvpx-vp9";
-    if (c === "vp8")
-        return "libvpx";
-    return c;
+    return alphaDecoderFor(codec) ?? (codec ?? "").toLowerCase();
 }
 export function resolveFrameFormat(metadata, requested) {
     if (metadata.hasAlpha || codecMayHaveAlpha(metadata.videoCodec))

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

@@ -110,20 +110,6 @@ export declare function probeMediaProfile(filePath: string, options?: {
     signal?: AbortSignal;
 }): Promise<MediaProbeProfile>;
 export declare function extractPngMetadataFromBuffer(buf: Buffer): StillImageMetadata | null;
-/**
- * Does this pix_fmt carry an alpha channel?
- *
- * Exported so the test asserts the shipped predicate rather than a copy of
- * the pattern. Anchored at the start, matching studio-server's
- * mediaMetadata.ts: the previous inline pattern bound its `(^|[^a-z])` anchor
- * to the first alternative only — `|` is looser than concatenation — so the
- * guard was decorative for every other name. It also missed abgr, ya8/ya16
- * and ayuv64, and its `gray[a-z0-9]*a` branch matched only gray8a/gray16a,
- * names FFmpeg renamed to ya8/ya16 in 2013. A `ya8` grayscale-plus-alpha PNG
- * reported hasAlpha:false, resolveFrameFormat picked jpg, and the overlay
- * flattened to an opaque rectangle.
- */
-export declare function pixelFormatHasAlpha(pixelFormat: string): boolean;
 /**
  * Read an ffprobe tag case-insensitively. ffmpeg/libavformat versions disagree
  * on tag casing — VP9 alpha is `alpha_mode` in older builds and `ALPHA_MODE`

package/dist/utils/ffprobe.js

@@ -5,6 +5,7 @@ import { chunkCrc32 } from "./crc32.js";
 import { StringDecoder } from "node:string_decoder";
 import { basename } from "path";
 import { redactTelemetryString } from "@hyperframes/core";
+import { videoStreamHasAlpha } from "@hyperframes/parsers/media-alpha";
 import { urlInputArgs } from "./urlInput.js";
 import { FFPROBE_PATH_ENV, getFfprobeBinary } from "./ffmpegBinaries.js";
 import { ManagedChildProcess } from "./managedChildProcess.js";
@@ -437,22 +438,6 @@ export function extractPngMetadataFromBuffer(buf) {
     }
     return width > 0 && height > 0 ? { width, height, colorSpace: colorSpaceFromCicp } : null;
 }
-/**
- * Does this pix_fmt carry an alpha channel?
- *
- * Exported so the test asserts the shipped predicate rather than a copy of
- * the pattern. Anchored at the start, matching studio-server's
- * mediaMetadata.ts: the previous inline pattern bound its `(^|[^a-z])` anchor
- * to the first alternative only — `|` is looser than concatenation — so the
- * guard was decorative for every other name. It also missed abgr, ya8/ya16
- * and ayuv64, and its `gray[a-z0-9]*a` branch matched only gray8a/gray16a,
- * names FFmpeg renamed to ya8/ya16 in 2013. A `ya8` grayscale-plus-alpha PNG
- * reported hasAlpha:false, resolveFrameFormat picked jpg, and the overlay
- * flattened to an opaque rectangle.
- */
-export function pixelFormatHasAlpha(pixelFormat) {
-    return /^(?:yuva|rgba|argb|bgra|abgr|gbrap|ya|ayuv)/i.test(pixelFormat);
-}
 function extractStillImageMetadata(filePath) {
     try {
         return extractPngMetadataFromBuffer(readFileSync(filePath));
@@ -613,16 +598,7 @@ export async function extractMediaMetadata(filePath) {
         };
         const colorSpace = merged.colorTransfer || merged.colorPrimaries || merged.colorSpace ? merged : null;
         const pixelFormat = videoStream.pix_fmt || "";
-        const alphaMode = readTagCI(videoStream.tags, "alpha_mode");
-        const hasAlpha = pixelFormatHasAlpha(pixelFormat) || alphaMode === "1";
-        // Anchored at the start, matching studio-server's mediaMetadata.ts. The
-        // previous pattern bound its `(^|[^a-z])` anchor to the FIRST alternative
-        // only — `|` is looser than concatenation — so the guard was decorative
-        // for every other name. It also missed abgr, ya8/ya16 and ayuv64, and its
-        // `gray[a-z0-9]*a` branch matched only gray8a/gray16a, names FFmpeg
-        // renamed to ya8/ya16 in 2013. A `ya8` grayscale-plus-alpha PNG reported
-        // hasAlpha:false, resolveFrameFormat picked jpg, and the overlay
-        // flattened to an opaque rectangle.
+        const hasAlpha = videoStreamHasAlpha(videoStream);
         const containerDuration = output?.format.duration ? parseFloat(output.format.duration) : 0;
         const streamDuration = videoStream.duration ? parseFloat(videoStream.duration) : 0;
         const parsedStreamStart = videoStream.start_time ? parseFloat(videoStream.start_time) : 0;

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/package.json

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