@hyperframes/engine 0.8.212 → 0.8.214

package/dist/index.d.ts

@@ -47,7 +47,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, type ProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, 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, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, 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, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, 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, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";

package/dist/index.js

@@ -51,7 +51,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, 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, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";

package/dist/services/audioMixer.js

@@ -5,7 +5,7 @@ import { renameWithRetry } from "@hyperframes/core/rename-retry";
 import { removeScratch } from "@hyperframes/core/remove-scratch";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
-import { extractAudioMetadata } from "../utils/ffprobe.js";
+import { extractAudioMetadata, ffmpegSeekSeconds } from "../utils/ffprobe.js";
 import { isNotMediaPayload } from "../utils/notMediaPayload.js";
 import { urlInputArgs } from "../utils/urlInput.js";
 import { clampAudioGain, clipGain } from "@hyperframes/core/audio-gain";
@@ -579,13 +579,14 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
             removeScratch(cycleDir);
         }
     }
-    const inputSeek = mediaStart >= (metadata?.latestStreamLeadSeconds ?? 0);
-    const start = formatFilterNumber(mediaStart);
+    const ffmpegStart = ffmpegSeekSeconds(metadata ?? {}, mediaStart);
+    const inputSeek = ffmpegStart >= (metadata?.latestStreamLeadSeconds ?? 0);
+    const start = formatFilterNumber(ffmpegStart);
     const timestampTrim = inputSeek
         ? null
-        : `atrim=start=${start}:end=${formatFilterNumber(mediaStart + sourceDuration)},asetpts=PTS-${start}/TB,aresample=async=1:first_pts=0`;
+        : `atrim=start=${start}:end=${formatFilterNumber(ffmpegStart + sourceDuration)},asetpts=PTS-${start}/TB,aresample=async=1:first_pts=0`;
     const fromSidecar = audioSidecarUrl !== undefined && inputSeek && normalizedPlaybackRate === 1;
-    const warmUp = fromSidecar ? Math.min(SIDECAR_WARM_UP_SECONDS, mediaStart) : 0;
+    const warmUp = fromSidecar ? Math.min(SIDECAR_WARM_UP_SECONDS, ffmpegStart) : 0;
     const outputArgs = preparedAudioOutputArgs(metadata, normalizedPlaybackRate, duration, [
         warmUp > 0 ? `atrim=start=${warmUp},asetpts=PTS-STARTPTS` : timestampTrim,
         ...(options?.padToDuration ? ["apad"] : []),
@@ -597,7 +598,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         ...(readsUrl ? FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE : []),
         ...urlInputArgs(readFrom),
         ...(inputSeek
-            ? ["-ss", String(mediaStart - warmUp), "-t", String(sourceDuration + warmUp)]
+            ? ["-ss", String(ffmpegStart - warmUp), "-t", String(sourceDuration + warmUp)]
             : []),
         "-i",
         readFrom,

package/dist/services/videoFrameExtractor.d.ts

@@ -6,7 +6,7 @@
  */
 import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution";
 import { type RateSpec, type FpsInput } from "@hyperframes/core";
-import { resolvePlayableVideoDuration, type VideoMetadata } from "../utils/ffprobe.js";
+import { ffmpegSeekSeconds, resolvePlayableVideoDuration, videoStartOnMediaTimeline, type VideoMetadata } from "../utils/ffprobe.js";
 import { type HdrTransfer } from "../utils/hdr.js";
 import { type EngineConfig } from "../config.js";
 import { type CacheFrameFormat } from "./extractionCache.js";
@@ -276,7 +276,7 @@ export declare function classifyFfmpegSpawnError(error: unknown, stderr?: string
  * the container duration when ffprobe omits the stream duration; keep the
  * explicit fallback here for callers supplying older/manual metadata.
  */
-export { resolvePlayableVideoDuration };
+export { ffmpegSeekSeconds, resolvePlayableVideoDuration, videoStartOnMediaTimeline };
 export interface TimelineExtractionWindow {
     compositionStart: number;
     mediaStart: number;
@@ -332,7 +332,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 isVideoHiddenBeforeStreamStart(videoStartSeconds: 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

@@ -17,7 +17,7 @@ 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, mediaElementTime, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
-import { extractFinalVideoFrameTimestamp, extractMediaMetadata, keyframeGapSeconds, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, writeMetadataCache, } from "../utils/ffprobe.js";
+import { extractFinalVideoFrameTimestamp, extractMediaMetadata, ffmpegSeekSeconds, keyframeGapSeconds, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, videoStartOnMediaTimeline, writeMetadataCache, } from "../utils/ffprobe.js";
 import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPlaneProbe.js";
 import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
@@ -569,7 +569,7 @@ async function runSegmentedExtraction(job) {
                 ...decodeArgs,
                 "-noaccurate_seek",
                 "-ss",
-                String(seek),
+                String(job.ffmpegSeek(seek)),
                 "-i",
                 videoPath,
                 // Read one frame past the segment and keep exactly its own frames.
@@ -678,18 +678,19 @@ outputDirOverride) {
         args.push("-c:v", decoderForCodec(metadata.videoCodec));
     }
     const decodeArgs = [...args];
+    const ffmpegSeek = (mediaTime) => ffmpegSeekSeconds(metadata, mediaTime);
     if (options.finalFrameOnly) {
         // Output-side seek decodes from the start before selecting the final
         // sample. This is intentionally reserved for the one-frame path: input
         // seeking is faster, but valid unindexed transports (notably MPEG-TS with
         // a negative timestamp base) can seek to EOF and emit zero frames.
-        args.push("-i", videoPath, "-ss", String(startTime), "-frames:v", "1");
+        args.push("-i", videoPath, "-ss", String(Math.max(0, ffmpegSeek(startTime))), "-frames:v", "1");
     }
     else {
         // An accurate seek drops the frame on screen at startTime; the fps sampling below needs it.
         if (sampleAtOutputFps)
             args.push("-noaccurate_seek");
-        args.push("-ss", String(startTime), "-i", videoPath, "-t", String(duration));
+        args.push("-ss", String(ffmpegSeek(startTime)), "-i", videoPath, "-t", String(duration));
     }
     const vfFilters = [];
     if (keepsHdrForChrome) {
@@ -702,7 +703,7 @@ outputDirOverride) {
         ? [
             ...(metadata.isVFR
                 ? []
-                : undoTickRoundingOnTheSourceFrameGrid(seek, metadata.videoStreamLeadSeconds ?? 0)),
+                : undoTickRoundingOnTheSourceFrameGrid(seek, videoStartOnMediaTimeline(metadata))),
             "settb=intb/2",
             "setpts=PTS-lte(TB\\,0.001)",
             `fps=${ffmpegFps}:start_time=0:round=up`,
@@ -751,6 +752,7 @@ outputDirOverride) {
         ? runSegmentedExtraction({
             decodeArgs: [...hwaccel, ...decodeArgs],
             filterAndEncodeArgs: (seek) => [...filterArgsFor(seek), ...encodeArgs],
+            ffmpegSeek,
             videoPath,
             startTime,
             fps,
@@ -868,7 +870,7 @@ function resolveSegmentDuration(requested, mediaStart, sourceDuration) {
  * the container duration when ffprobe omits the stream duration; keep the
  * explicit fallback here for callers supplying older/manual metadata.
  */
-export { resolvePlayableVideoDuration };
+export { ffmpegSeekSeconds, resolvePlayableVideoDuration, videoStartOnMediaTimeline };
 function canHoldFinalFramePastEof(video) {
     const timelineDuration = video.end - video.start;
     return !video.loop && Number.isFinite(timelineDuration) && timelineDuration > 0;
@@ -996,11 +998,12 @@ export async function resolveFinalFrameExtractionWindow(videoPath, video, metada
         return window;
     const playableDuration = resolvePlayableVideoDuration(metadata);
     const videoStreamLead = metadata.videoStreamLeadSeconds ?? 0;
-    const finalFrameTimestamp = videoStreamLead +
+    const lastInstantTheBrowserPlays = playableDuration - FINAL_FRAME_LOGICAL_DURATION_SECONDS;
+    const finalFrameTimestamp = Math.min(lastInstantTheBrowserPlays, videoStartOnMediaTimeline(metadata) +
         (await extractFinalVideoFrameTimestamp(videoPath, {
             videoStreamDurationSeconds: playableDuration - videoStreamLead,
             videoStreamStartSeconds: metadata.videoStreamStartSeconds,
-        }, signal));
+        }, signal)));
     if (window.mediaStart < finalFrameTimestamp - 1e-9)
         return window;
     const sourceRemaining = playableDuration - video.mediaStart;
@@ -1624,7 +1627,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                 sourceFps: work.metadata.fps,
                 finalFrameSeconds: storedFinalFrame.seconds,
                 lastPacketSeconds: storedFinalFrame.lastPacketSeconds,
-                streamLeadSeconds: work.metadata.videoStreamLeadSeconds ?? 0,
+                streamLeadSeconds: videoStartOnMediaTimeline(work.metadata),
             });
         if (storedTailFrames !== null) {
             const totalFrames = firstTailFrame + storedTailFrames;
@@ -1866,9 +1869,8 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
     };
 }
 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);
+export function isVideoHiddenBeforeStreamStart(videoStartSeconds, mediaTime) {
+    return ((videoStartSeconds ?? 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);
@@ -1892,7 +1894,7 @@ function getFrameIndexAtTime(extracted, globalTime, videoStart, loop = false, me
     const frameIndex = Math.floor(shownTime * extracted.fps);
     if (frameIndex < 0 || extracted.totalFrames <= 0)
         return null;
-    if (isVideoHiddenBeforeStreamStart(extracted.metadata.videoStreamLeadSeconds, mediaStart + sourceTime)) {
+    if (isVideoHiddenBeforeStreamStart(videoStartOnMediaTimeline(extracted.metadata), mediaStart + sourceTime)) {
         return null;
     }
     if (frameIndex >= extracted.totalFrames) {

package/dist/services/videoFrameInjector.d.ts

@@ -89,7 +89,7 @@ export interface ShownBox {
 }
 /**
  * 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).
+ * graded (directly or through a grade group), 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>>;
 /**

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_ATTR, 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, HF_COLOR_GROUP_ATTR, HF_COLOR_GROUP_TAG, 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
@@ -255,12 +255,12 @@ async function setVideoElementsVisibility(page, videoIds, 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).
+ * graded (directly or through a grade group), 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 boxes = await page.evaluate(async (ids, seekTimes, gradingAttr, gradingCanvasPrefix, groupAttr, groupTag) => {
         const hf = window.__hf;
         if (typeof hf?.seek !== "function")
             return [];
@@ -268,8 +268,13 @@ export async function measureVideoShownBoxes(page, videoIds, times) {
             .__hfWaitForSeekCompletion;
         const largest = new Map();
         const fullSize = new Set();
+        const gradedThroughGroup = (video) => {
+            const groupId = video.getAttribute(groupAttr);
+            const group = groupId ? document.getElementById(groupId) : null;
+            return group?.localName === groupTag && group.hasAttribute(gradingAttr);
+        };
         const keepsFullSize = (video) => {
-            if (video.hasAttribute(gradingAttr))
+            if (video.hasAttribute(gradingAttr) || gradedThroughGroup(video))
                 return true;
             const fit = window.getComputedStyle(video).objectFit;
             return fit === "none" || fit === "scale-down";
@@ -297,7 +302,7 @@ export async function measureVideoShownBoxes(page, videoIds, times) {
                 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);
+    }, [...videoIds], [...times], HF_COLOR_GRADING_ATTR, HF_COLOR_GRADING_CANVAS_ID_PREFIX, HF_COLOR_GROUP_ATTR, HF_COLOR_GROUP_TAG);
     return new Map(boxes);
 }
 /**

package/dist/utils/ffprobe.d.ts

@@ -25,6 +25,7 @@ export interface VideoMetadata {
     videoStreamStartSeconds?: number;
     /** Seconds after the file's media time 0 (its earliest audio/video stream start) at which video begins. */
     videoStreamLeadSeconds?: number;
+    mediaTimeOffsetSeconds?: number;
     width: number;
     height: number;
     fps: number;
@@ -60,6 +61,7 @@ export interface AudioMetadata {
     /** Seconds after the file's media time 0 at which its last audio or video stream starts. */
     latestStreamLeadSeconds?: number;
     audioStreamLeadSeconds?: number;
+    mediaTimeOffsetSeconds?: number;
     audioStreamCount?: number;
     /** The track read for these facts and for the mix, by its place among the audio streams (decodableAudioStream). */
     audioStream: number;
@@ -123,6 +125,8 @@ export declare const PROBE_FACTS_VERSION = "v2";
 export declare function readProbeJson(filePath: string, signal?: AbortSignal): Promise<string>;
 /** What a site stores beside a video: its ffprobe JSON and the final-frame facts a plan would otherwise probe for. */
 export declare function buildProbeFactsText(filePath: string, signal?: AbortSignal): Promise<string>;
+export declare function videoStartOnMediaTimeline(metadata: Pick<VideoMetadata, "videoStreamLeadSeconds" | "mediaTimeOffsetSeconds">): number;
+export declare function ffmpegSeekSeconds(metadata: Pick<VideoMetadata, "mediaTimeOffsetSeconds">, mediaTime: number): number;
 export declare function resolvePlayableVideoDuration(metadata: VideoMetadata): number;
 /**
  * Probe stream capabilities without assuming the caller's element type.

package/dist/utils/ffprobe.js

@@ -333,6 +333,12 @@ export async function buildProbeFactsText(filePath, signal) {
     }
     return JSON.stringify(facts);
 }
+export function videoStartOnMediaTimeline(metadata) {
+    return (metadata.videoStreamLeadSeconds ?? 0) + (metadata.mediaTimeOffsetSeconds ?? 0);
+}
+export function ffmpegSeekSeconds(metadata, mediaTime) {
+    return mediaTime - (metadata.mediaTimeOffsetSeconds ?? 0);
+}
 export function resolvePlayableVideoDuration(metadata) {
     return Number.isFinite(metadata.videoStreamDurationSeconds) &&
         metadata.videoStreamDurationSeconds > 0
@@ -790,6 +796,7 @@ export async function extractMediaMetadata(filePath) {
             videoStreamDurationSeconds: effectiveStreamDuration,
             videoStreamStartSeconds: streamStart,
             videoStreamLeadSeconds: streamLeadSeconds(output, videoStream),
+            mediaTimeOffsetSeconds: mediaTimeOffsetSeconds(output),
             width: videoStream.width || stillImage()?.width || 0,
             height: videoStream.height || stillImage()?.height || 0,
             fps,
@@ -986,11 +993,12 @@ async function probeAudioMetadata(filePath, signal) {
         bitrate: output.format.bit_rate ? parseInt(output.format.bit_rate) : undefined,
         latestStreamLeadSeconds: latestStreamLeadSeconds(output),
         audioStreamLeadSeconds: streamLeadSeconds(output, audioStream),
+        mediaTimeOffsetSeconds: mediaTimeOffsetSeconds(output),
         audioStreamCount: audioStreams.length,
         audioStream: audioStreamIndex,
     };
 }
-/** Chrome's media time 0 is the earliest of these; a stream starting later plays that much in. */
+/** A stream starting after the earliest of these plays that much after it. */
 function audioVideoStreamStarts(output) {
     return (output?.streams ?? [])
         .filter((s) => (s.codec_type === "audio" || s.codec_type === "video") && s.disposition?.attached_pic !== 1)
@@ -1002,6 +1010,12 @@ function streamLeadSeconds(output, stream) {
     const start = parseFloat(stream.start_time ?? "");
     return Number.isFinite(start) && starts.length > 0 ? Math.max(0, start - Math.min(...starts)) : 0;
 }
+const BROWSER_PLAYS_FROM_TIMESTAMP_ZERO = /\b(mp4|webm)\b/;
+function mediaTimeOffsetSeconds(output) {
+    const starts = audioVideoStreamStarts(output);
+    const fromZero = BROWSER_PLAYS_FROM_TIMESTAMP_ZERO.test(output?.format.format_name ?? "");
+    return fromZero && starts.length > 0 ? Math.max(0, Math.min(...starts)) : 0;
+}
 function latestStreamLeadSeconds(output) {
     const starts = audioVideoStreamStarts(output);
     return starts.length > 0 ? Math.max(...starts) - Math.min(...starts) : 0;

package/package.json

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