@hyperframes/engine 0.8.146 → 0.8.148

package/dist/index.d.ts

@@ -45,7 +45,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
 export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, type StreamingEncoder, type StreamingEncoderOptions, type StreamingEncoderResult, type FrameReorderBuffer, } from "./services/streamingEncoder.js";
-export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/index.js

@@ -49,7 +49,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
 // ── Media processing ───────────────────────────────────────────────────────────
-export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/services/audioFxRender.js

@@ -153,14 +153,7 @@ export function writeWav(path, samples, sampleRate, channels = 1, float = false)
     // in between.
     writeFileSync(path, buf);
 }
-/**
- * Split an interleaved buffer into one array per channel.
- *
- * The graph used to fold everything to mono, which collapsed a stereo bed's
- * width for the render only — and cost ~3 dB through the very mono-to-stereo
- * rematrix that `prepareAudioTrack`'s pan filter exists to avoid. Preview kept
- * the track stereo, so the two diverged the moment any effect was enabled.
- */
+/** Split an interleaved buffer into one array per channel, keeping stereo width as preview does. */
 function deinterleave(samples, channels) {
     if (channels <= 1)
         return [samples];

package/dist/services/audioMixer.d.ts

@@ -1,26 +1,10 @@
-/**
- * Audio Mixer Service
- *
- * Processes and mixes audio tracks using FFmpeg.
- */
 import { type EngineConfig } from "../config.js";
 import type { AudioElement, AudioTrack, MixResult } from "./audioMixer.types.js";
 import { type HfAutomationLane } from "@hyperframes/core/audio-automation";
 import type { AudioVolumeKeyframe } from "./audioMixer.types.js";
 export type { AudioElement, MixResult } from "./audioMixer.types.js";
-/**
- * Filename every caller must use for the mixed-audio artifact.
- *
- * The extension is load-bearing, not cosmetic: FFmpeg picks the muxer from it,
- * and the mix is AAC-encoded. A raw ADTS `.aac` stream has nowhere to record
- * the encoder's priming delay, so those leading samples decode as real silence
- * and shift the whole track ~1024 samples (21.33 ms at 48 kHz) late against a
- * frame-accurate video track. An MP4-family container carries the delay as an
- * edit list, which every decoder then strips, so the mix lands on its authored
- * start. Keep the choice here rather than at each call site: the same file is
- * muxed into the video, shipped in a distributed plan, and handed to users as
- * the PNG-sequence sidecar, and all three have to agree.
- */
+/** An MP4-family container records AAC priming as an edit list; a raw .aac plays ~21 ms late.
+ * The video mux, the distributed plan and the PNG-sequence sidecar all read this one name. */
 export declare const MIXED_AUDIO_FILENAME = "audio.m4a";
 /** afade stages after the volume filter (leading comma), or "" when none. Stream time 0 is the clip start. */
 export declare function buildFadeFilters(track: Pick<AudioTrack, "start" | "end" | "fadeIn" | "fadeOut">): string;

package/dist/services/audioMixer.js

@@ -1,9 +1,4 @@
 // fallow-ignore-file complexity code-duplication
-/**
- * Audio Mixer Service
- *
- * Processes and mixes audio tracks using FFmpeg.
- */
 import { isSelfOrAncestorHidden, memberGroupKey, isMemberGroupHidden } from "./mediaHidden.js";
 import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "fs";
 import { join, dirname, isAbsolute, relative } from "path";
@@ -26,19 +21,8 @@ import { chainTailSeconds } from "@hyperframes/core/audio-fx-tail";
 import { isAudibleVideoElement, MEDIA_RENDER_ID_ATTR, normalizePlaybackRate, normalizeRateSpec, parseStrictFiniteTimingNumber, readElementRateSpec, readMediaStart, sourceTimeAt, timeAtSourceTime, } from "@hyperframes/core";
 import { resolveAudioGroups } from "@hyperframes/core/audio-groups";
 import { applyAudioFxChain, AudioFxRenderError } from "./audioFxRender.js";
-/**
- * Filename every caller must use for the mixed-audio artifact.
- *
- * The extension is load-bearing, not cosmetic: FFmpeg picks the muxer from it,
- * and the mix is AAC-encoded. A raw ADTS `.aac` stream has nowhere to record
- * the encoder's priming delay, so those leading samples decode as real silence
- * and shift the whole track ~1024 samples (21.33 ms at 48 kHz) late against a
- * frame-accurate video track. An MP4-family container carries the delay as an
- * edit list, which every decoder then strips, so the mix lands on its authored
- * start. Keep the choice here rather than at each call site: the same file is
- * muxed into the video, shipped in a distributed plan, and handed to users as
- * the PNG-sequence sidecar, and all three have to agree.
- */
+/** An MP4-family container records AAC priming as an edit list; a raw .aac plays ~21 ms late.
+ * The video mux, the distributed plan and the PNG-sequence sidecar all read this one name. */
 export const MIXED_AUDIO_FILENAME = "audio.m4a";
 function clampVolume(volume) {
     return clampAudioGain(volume);
@@ -87,11 +71,11 @@ function buildAtempoFilter(playbackRate) {
 const RAMP_SLICE_SECONDS = 0.25;
 const MAX_RAMP_SLICES = 240;
 /** Bake a rate lane as consecutive source slices, each stretched by its mean `sourceTimeAt` rate, keeping pitch. */
-function buildRampFilterComplex(lane, duration, tailFilter) {
+function buildRampFilterComplex(lane, duration, headFilter, tailFilter) {
     const slices = Math.min(MAX_RAMP_SLICES, Math.max(1, Math.ceil(duration / RAMP_SLICE_SECONDS)));
     const step = duration / slices;
     const split = Array.from({ length: slices }, (_, i) => `[s${i}]`).join("");
-    const parts = [`[0:a]asplit=${slices}${split}`];
+    const parts = [`[0:a]${headFilter ? `${headFilter},` : ""}asplit=${slices}${split}`];
     for (let i = 0; i < slices; i += 1) {
         const from = sourceTimeAt(lane, i * step);
         const to = sourceTimeAt(lane, (i + 1) * step);
@@ -112,27 +96,17 @@ function buildRampFilterComplex(lane, duration, tailFilter) {
         parts.push(`[cat]${tailFilter}[out]`);
     return parts.join(";");
 }
-function preparedAudioOutputArgs(srcPath, playbackRate, duration = 0) {
-    return stereoOutputArgs(srcPath).then((channelArgs) => {
-        const filters = [];
-        const outputArgs = [];
-        if (channelArgs[0] === "-af" && channelArgs[1]) {
-            filters.push(channelArgs[1]);
-        }
-        else {
-            outputArgs.push(...channelArgs);
-        }
-        if (typeof playbackRate === "object") {
-            const graph = buildRampFilterComplex(playbackRate, duration, filters.join(",") || null);
-            return ["-filter_complex", graph, "-map", "[out]", ...outputArgs];
-        }
-        const atempo = buildAtempoFilter(playbackRate);
-        if (atempo)
-            filters.push(atempo);
-        if (filters.length > 0)
-            outputArgs.push("-af", filters.join(","));
-        return outputArgs;
-    });
+function preparedAudioOutputArgs(metadata, playbackRate, duration, headFilter) {
+    const channelFilter = metadata?.channels === 1 ? STEREO_CHANNEL_FILTER : null;
+    const outputArgs = channelFilter ? [] : ["-ac", "2"];
+    if (typeof playbackRate === "object") {
+        const graph = buildRampFilterComplex(playbackRate, duration, headFilter, channelFilter);
+        return ["-filter_complex", graph, "-map", "[out]", ...outputArgs];
+    }
+    const filters = [headFilter, channelFilter, buildAtempoFilter(playbackRate)].filter(Boolean);
+    if (filters.length > 0)
+        outputArgs.push("-af", filters.join(","));
+    return outputArgs;
 }
 function escapeExpressionCommas(expression) {
     return expression.replace(/\\/g, "\\\\").replace(/,/g, "\\,");
@@ -165,17 +139,6 @@ const VOLUME_SIMPLIFY_EPSILON = 0.005;
 // mono source by 3 dB. Explicitly map front-center into both stereo channels;
 // native stereo sources have FL/FR and pass through unchanged.
 const STEREO_CHANNEL_FILTER = "pan=stereo|FL=FL+FC|FR=FR+FC";
-async function stereoOutputArgs(srcPath) {
-    try {
-        const { channels } = await extractAudioMetadata(srcPath);
-        if (channels === 1)
-            return ["-af", STEREO_CHANNEL_FILTER];
-    }
-    catch {
-        // Preserve the previous FFmpeg conversion path when metadata probing fails.
-    }
-    return ["-ac", "2"];
-}
 /**
  * Reduce a sorted keyframe list to a perceptually-equivalent piecewise-linear
  * envelope with a bounded segment count.
@@ -517,74 +480,27 @@ export function parseAudioElements(html) {
     }
     return elements;
 }
-async function extractAudioFromVideo(videoPath, outputPath, options, signal, config) {
-    const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
-    const outputDir = dirname(outputPath);
-    if (!existsSync(outputDir))
-        mkdirSync(outputDir, { recursive: true });
-    const playbackRate = normalizeRateSpec(options?.playbackRate);
-    const args = [];
-    if (options?.startTime !== undefined)
-        args.push("-ss", String(options.startTime));
-    if (options?.duration !== undefined) {
-        args.push("-t", String(sourceTimeAt(playbackRate, options.duration)));
-    }
-    args.push("-i", videoPath);
-    const outputArgs = await preparedAudioOutputArgs(videoPath, playbackRate, options?.duration);
-    args.push("-vn", "-acodec", "pcm_s16le", "-ar", "48000", ...outputArgs);
-    if (playbackRate !== 1 && options?.duration !== undefined) {
-        args.push("-t", String(options.duration));
-    }
-    args.push("-y", outputPath);
-    const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
-    if (signal?.aborted) {
-        const failure = {
-            stage: "cancelled",
-            reason: "cancelled",
-            owner: "user",
-            retryable: false,
-            detail: "Audio extract cancelled",
-        };
-        return {
-            success: false,
-            outputPath,
-            durationMs: result.durationMs,
-            error: failure.detail,
-            failure,
-        };
-    }
-    if (!result.success) {
-        const failure = ffmpegFailure("extract", result);
-        return {
-            success: false,
-            outputPath,
-            durationMs: result.durationMs,
-            error: failure.detail,
-            failure,
-        };
-    }
-    return { success: true, outputPath, durationMs: result.durationMs };
-}
-async function prepareAudioTrack(srcPath, outputPath, mediaStart, duration, playbackRate = 1, signal, config) {
+/** 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) {
     const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
     const normalizedPlaybackRate = normalizeRateSpec(playbackRate);
-    const outputArgs = await preparedAudioOutputArgs(srcPath, normalizedPlaybackRate, duration);
-    const args = [
-        "-ss",
-        String(mediaStart),
-        "-t",
-        String(sourceTimeAt(normalizedPlaybackRate, duration)),
-        "-i",
-        srcPath,
-        "-acodec",
-        "pcm_s16le",
-        "-ar",
-        "48000",
-        ...outputArgs,
-    ];
+    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);
+    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];
+    args.push("-vn", "-acodec", "pcm_s16le", "-ar", "48000", ...outputArgs);
     if (normalizedPlaybackRate !== 1)
         args.push("-t", String(duration));
     args.push("-y", outputPath);
@@ -595,7 +511,7 @@ async function prepareAudioTrack(srcPath, outputPath, mediaStart, duration, play
             reason: "cancelled",
             owner: "user",
             retryable: false,
-            detail: "Audio prepare cancelled",
+            detail: `Audio ${stage} cancelled`,
         };
         return {
             success: false,
@@ -605,7 +521,7 @@ async function prepareAudioTrack(srcPath, outputPath, mediaStart, duration, play
             failure,
         };
     }
-    const failure = !result.success ? ffmpegFailure("prepare", result) : undefined;
+    const failure = !result.success ? ffmpegFailure(stage, result) : undefined;
     return {
         success: result.success,
         outputPath,
@@ -1024,11 +940,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             let audioSrcPath = srcPath;
             if (element.type === "video") {
                 const extractedPath = join(workDir, `${element.id}-extracted.wav`);
-                const extractResult = await extractAudioFromVideo(srcPath, extractedPath, {
-                    startTime: element.mediaStart,
-                    duration: element.end - element.start,
-                    playbackRate: element.playbackRate,
-                }, effectiveSignal, config);
+                const extractResult = await extractAudioSegment(srcPath, extractedPath, "extract", element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config);
                 if (!extractResult.success) {
                     failures.push(extractResult.failure
                         ? { ...extractResult.failure, elementId: element.id }
@@ -1046,7 +958,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             }
             else {
                 const trimmedPath = join(workDir, `${element.id}-trimmed.wav`);
-                const prepResult = await prepareAudioTrack(srcPath, trimmedPath, element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config);
+                const prepResult = await extractAudioSegment(srcPath, trimmedPath, "prepare", element.mediaStart, element.end - element.start, element.playbackRate, effectiveSignal, config);
                 if (!prepResult.success) {
                     failures.push(prepResult.failure
                         ? { ...prepResult.failure, elementId: element.id }

package/dist/services/audioVolumeEnvelope.d.ts

@@ -11,7 +11,7 @@
  * output (and the golden baselines) only change where a fade is actually applied.
  *
  * The prepared tracks are always `pcm_s16le`, 48 kHz, stereo (see
- * `prepareAudioTrack` / `extractAudioFromVideo`). Anything else is rejected so
+ * `extractAudioSegment`). Anything else is rejected so
  * the caller can fall back to the expression path rather than corrupting audio.
  */
 import type { AudioVolumeKeyframe } from "./audioMixer.types.js";

package/dist/services/audioVolumeEnvelope.js

@@ -11,7 +11,7 @@
  * output (and the golden baselines) only change where a fade is actually applied.
  *
  * The prepared tracks are always `pcm_s16le`, 48 kHz, stereo (see
- * `prepareAudioTrack` / `extractAudioFromVideo`). Anything else is rejected so
+ * `extractAudioSegment`). Anything else is rejected so
  * the caller can fall back to the expression path rather than corrupting audio.
  */
 import { mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";

package/dist/services/frameCapture.d.ts

@@ -20,6 +20,8 @@ export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSum
  * `heldVideoTime` (motion-blur samples only) is the output frame's time: a video on screen at
  * both times shows its frame for `heldVideoTime`, so footage does not smear. */
 export type BeforeCaptureHook = (page: Page, time: number, heldVideoTime?: number) => Promise<void>;
+/** The per-frame wait a capture is in, worded for the stall error a user reads. */
+type CaptureStep = "seeking the timeline" | "decoding CSS background images" | "injecting video frames" | "waiting for page seek handlers" | "loading color-grading LUTs" | "compositing the page" | "capturing the frame";
 export interface CaptureSession {
     browser: Browser;
     /** Exact ownership token for this browser acquisition. */
@@ -202,6 +204,7 @@ export interface CaptureSession {
      * retries via screenshot.
      */
     deFrameTimeouts?: number;
+    captureStep?: CaptureStep;
     /**
      * drawElement init passed every gate but stopped before verification +
      * canvas injection: the session has no video-frame injector yet (probe

package/dist/services/frameCapture.js

@@ -2040,7 +2040,9 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
     assertVfxIntact(session);
     const quantizedTime = quantizeSeekTime(time, fpsToNumber(options.fps), seekOptions?.subFrameDivisions);
     const seekStart = Date.now();
+    session.captureStep = "seeking the timeline";
     const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);
+    session.captureStep = "decoding CSS background images";
     await decodeDynamicCssBackgroundImages(page);
     const seekMs = Date.now() - seekStart;
     // Before-capture hook (e.g. video frame injection) — runs before
@@ -2048,9 +2050,12 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
     // replacements for <video> elements.
     const beforeCaptureStart = Date.now();
     if (session.onBeforeCapture) {
+        session.captureStep = "injecting video frames";
         await session.onBeforeCapture(page, quantizedTime, heldVideoTime);
     }
+    session.captureStep = "waiting for page seek handlers";
     await waitForPendingSeekCompletion(page);
+    session.captureStep = "loading color-grading LUTs";
     await page.evaluate(async () => {
         const runtime = window.__hf?.colorGrading;
         await runtime?.waitForActiveLuts?.();
@@ -2063,6 +2068,7 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
     if (hasPendingComposite &&
         session.captureMode !== "beginframe" &&
         session.captureMode !== "drawelement") {
+        session.captureStep = "compositing the page";
         await page.evaluate(async () => {
             const w = window;
             if (typeof w.__hf_page_composite_prepare === "function") {
@@ -2082,6 +2088,7 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
             }
         });
     }
+    session.captureStep = "capturing the frame";
     return { quantizedTime, seekMs, beforeCaptureMs };
 }
 // ── Static-frame dedup (default-on, opt-out HF_STATIC_DEDUP=false) ─────────────
@@ -3095,12 +3102,14 @@ async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
     const fps = fpsToNumber(session.options.fps);
     const frameTime = quantizeSeekTime(absFrameIndex / fps, fps);
     const eventfulSeekStart = Date.now();
+    session.captureStep = "seeking the timeline";
     await seekPageTimeline(session.page, frameTime, undefined);
     const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
     if (session.onBeforeCapture) {
         // The injector copies a video's own style only when its frame changes: inject at frameTime
         // first so the held frame carries frameTime's style, not the first sample's.
         const injectStart = Date.now();
+        session.captureStep = "injecting video frames";
         await session.onBeforeCapture(session.page, frameTime, frameTime);
         totals.beforeCaptureMs += Date.now() - injectStart;
     }
@@ -3125,6 +3134,7 @@ async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
         accumulator.add(sample.buffer);
     }
     const restoreSeekStart = Date.now();
+    session.captureStep = "seeking the timeline";
     await seekPageTimeline(session.page, frameTime, { suppressEvents: true });
     totals.seekMs += Date.now() - restoreSeekStart;
     const blended = accumulator.finish();
@@ -3396,6 +3406,7 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
     const startTime = Date.now();
     const fps = fpsToNumber(options.fps);
     const quantized = times.map((t) => quantizeTimeToFrame(t, fps));
+    session.captureStep = "capturing the frame";
     const { encodeResults, failedAt, error } = await produceDrawElementFrameBatch(page, quantized, options.width, options.height, options.quality ?? 80);
     // A later batch failure abandons this prefix. Its asynchronous encodes can
     // still reject while session cleanup shuts the worker down.

package/dist/services/videoFrameExtractor.d.ts

@@ -309,6 +309,7 @@ export declare function codecMayHaveAlpha(codec: string | undefined): boolean;
 export declare function decoderForCodec(codec: string | undefined): string;
 export declare function resolveFrameFormat(metadata: VideoMetadata, requested?: VideoFrameFormat): CacheFrameFormat;
 export declare function extractAllVideoFrames(videos: VideoElement[], baseDir: string, options: ExtractionOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "extractCacheDir" | "extractCacheMaxBytes">>, compiledDir?: string): Promise<ExtractionResult>;
+export declare function isVideoHiddenBeforeStreamStart(videoStreamLeadSeconds: number | undefined, mediaTime: number): boolean;
 export declare function getFrameAtTime(extracted: ExtractedFrames, globalTime: number, videoStart: number, loop?: boolean, mediaStart?: number): string | null;
 /**
  * Whether a media source is shorter than its `data-duration` slot by more than

package/dist/services/videoFrameExtractor.js

@@ -742,9 +742,9 @@ outputDirOverride) {
     if (framePaths.size > 0 && duration > 0 && !options.finalFrameOnly && !options.frameRanges) {
         const expectedAtFps = extractionFrameCountForDuration(duration, normalizedFps, metadata.isVFR);
         if (expectedAtFps > 0 && framePaths.size <= expectedAtFps * 0.6) {
-            const correctedDuration = startTime + framePaths.size / fps;
-            if (correctedDuration < metadata.videoStreamDurationSeconds) {
-                metadata.videoStreamDurationSeconds = correctedDuration;
+            const correctedStreamDuration = startTime + framePaths.size / fps - (metadata.videoStreamLeadSeconds ?? 0);
+            if (correctedStreamDuration < metadata.videoStreamDurationSeconds) {
+                metadata.videoStreamDurationSeconds = correctedStreamDuration;
             }
         }
     }
@@ -796,7 +796,7 @@ function resolveSegmentDuration(requested, mediaStart, sourceDuration) {
 export function resolvePlayableVideoDuration(metadata) {
     return Number.isFinite(metadata.videoStreamDurationSeconds) &&
         metadata.videoStreamDurationSeconds > 0
-        ? metadata.videoStreamDurationSeconds
+        ? (metadata.videoStreamLeadSeconds ?? 0) + metadata.videoStreamDurationSeconds
         : metadata.durationSeconds;
 }
 function canHoldFinalFramePastEof(video) {
@@ -925,10 +925,12 @@ export async function resolveFinalFrameExtractionWindow(videoPath, video, metada
     if (!window.ensureFinalFrame)
         return window;
     const playableDuration = resolvePlayableVideoDuration(metadata);
-    const finalFrameTimestamp = await extractFinalVideoFrameTimestamp(videoPath, {
-        videoStreamDurationSeconds: playableDuration,
-        videoStreamStartSeconds: metadata.videoStreamStartSeconds,
-    }, signal);
+    const videoStreamLead = metadata.videoStreamLeadSeconds ?? 0;
+    const finalFrameTimestamp = videoStreamLead +
+        (await extractFinalVideoFrameTimestamp(videoPath, {
+            videoStreamDurationSeconds: playableDuration - videoStreamLead,
+            videoStreamStartSeconds: metadata.videoStreamStartSeconds,
+        }, signal));
     if (window.mediaStart < finalFrameTimestamp - 1e-9)
         return window;
     const sourceRemaining = playableDuration - video.mediaStart;
@@ -1781,6 +1783,11 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         phaseBreakdown: breakdown,
     };
 }
+const BROWSER_SHOWS_UPCOMING_FIRST_FRAME_WITHIN_SECONDS = 1;
+export function isVideoHiddenBeforeStreamStart(videoStreamLeadSeconds, mediaTime) {
+    return ((videoStreamLeadSeconds ?? 0) - mediaTime >=
+        BROWSER_SHOWS_UPCOMING_FIRST_FRAME_WITHIN_SECONDS - 1e-6);
+}
 function getFrameIndexAtTime(extracted, globalTime, videoStart, loop = false, mediaStart = 0, holdLastFrame = false, playbackRate = 1) {
     let localTime = Math.max(0, globalTime - videoStart);
     const normalizedPlaybackRate = normalizeRateSpec(playbackRate);
@@ -1803,6 +1810,9 @@ function getFrameIndexAtTime(extracted, globalTime, videoStart, loop = false, me
     const frameIndex = Math.floor(sourceTime * extracted.fps + 1e-9);
     if (frameIndex < 0 || extracted.totalFrames <= 0)
         return null;
+    if (isVideoHiddenBeforeStreamStart(extracted.metadata.videoStreamLeadSeconds, mediaStart + sourceTime)) {
+        return null;
+    }
     if (frameIndex >= extracted.totalFrames) {
         return loop || holdLastFrame ? extracted.totalFrames - 1 : null;
     }

package/dist/utils/ffprobe.d.ts

@@ -14,6 +14,8 @@ export interface VideoMetadata {
      * timestamps are absolute, so callers crossing those APIs must normalize by
      * this value. Absent only in legacy/manually-constructed metadata. */
     videoStreamStartSeconds?: number;
+    /** Seconds after the file's media time 0 (its earliest audio/video stream start) at which video begins. */
+    videoStreamLeadSeconds?: number;
     width: number;
     height: number;
     fps: number;
@@ -43,6 +45,8 @@ export interface AudioMetadata {
     channels: number;
     audioCodec: string;
     bitrate?: number;
+    /** Seconds after the file's media time 0 at which its last audio or video stream starts. */
+    latestStreamLeadSeconds?: number;
 }
 interface StillImageMetadata {
     width: number;

package/dist/utils/ffprobe.js

@@ -645,6 +645,7 @@ export async function extractMediaMetadata(filePath) {
             durationSeconds: containerDuration,
             videoStreamDurationSeconds: effectiveStreamDuration,
             videoStreamStartSeconds: streamStart,
+            videoStreamLeadSeconds: streamLeadSeconds(output, videoStream),
             width: videoStream.width || stillImage()?.width || 0,
             height: videoStream.height || stillImage()?.height || 0,
             fps,
@@ -784,6 +785,7 @@ export async function extractAudioMetadata(filePath, options) {
             channels: audioStream.channels || 2,
             audioCodec,
             bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined,
+            latestStreamLeadSeconds: latestStreamLeadSeconds(output),
         };
     })();
     if (options?.signal)
@@ -791,6 +793,22 @@ export async function extractAudioMetadata(filePath, options) {
     writeMetadataCache(audioMetadataCache, filePath, identity, probePromise);
     return probePromise;
 }
+/** Chrome's media time 0 is the earliest of these; a stream starting later plays that much in. */
+function audioVideoStreamStarts(output) {
+    return (output?.streams ?? [])
+        .filter((s) => (s.codec_type === "audio" || s.codec_type === "video") && s.disposition?.attached_pic !== 1)
+        .map((s) => parseFloat(s.start_time ?? ""))
+        .filter(Number.isFinite);
+}
+function streamLeadSeconds(output, stream) {
+    const starts = audioVideoStreamStarts(output);
+    const start = parseFloat(stream.start_time ?? "");
+    return Number.isFinite(start) && starts.length > 0 ? Math.max(0, start - Math.min(...starts)) : 0;
+}
+function latestStreamLeadSeconds(output) {
+    const starts = audioVideoStreamStarts(output);
+    return starts.length > 0 ? Math.max(...starts) - Math.min(...starts) : 0;
+}
 function audioStartSeconds(stream, format) {
     const start = parseFloat(stream.start_time ?? format.start_time ?? "");
     return Number.isFinite(start) ? start : 0;

package/package.json

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