@hyperframes/engine 0.8.172 → 0.8.174

package/dist/config.d.ts

@@ -404,6 +404,8 @@ export declare function explainDrawElementDisabled(args: {
     workerEncode: boolean;
     chromeCeiling?: number;
 }): "unsupported_platform" | "old_chrome" | "software_gpu" | "worker_encode_off" | "disabled";
+/** `pageNavigationTimeout` alone, for callers that need the page-load budget without the rest of the config. */
+export declare function resolvePageNavigationTimeout(): number;
 export declare function resolveConfig(overrides?: Partial<EngineConfig>): EngineConfig;
 /**
  * Runtime-resolved companion to the software-GPU screenshot clamp in

package/dist/config.js

@@ -444,6 +444,12 @@ export function explainDrawElementDisabled(args) {
         return "worker_encode_off";
     return "disabled";
 }
+/** `pageNavigationTimeout` alone, for callers that need the page-load budget without the rest of the config. */
+export function resolvePageNavigationTimeout() {
+    const raw = process.env.PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS;
+    const parsed = raw === undefined || raw === "" ? NaN : Number(raw);
+    return Number.isFinite(parsed) ? parsed : DEFAULT_CONFIG.pageNavigationTimeout;
+}
 export function resolveConfig(overrides) {
     const env = (key) => process.env[key];
     const envNum = (key, fallback) => {
@@ -528,7 +534,7 @@ export function resolveConfig(overrides) {
         frameDataUriCacheBytesLimitMb: Math.max(64, envNum("PRODUCER_FRAME_DATA_URI_CACHE_BYTES_MB", memoryAdaptiveCacheBytesMb())),
         playerReadyTimeout: envNum("PRODUCER_PLAYER_READY_TIMEOUT_MS", DEFAULT_CONFIG.playerReadyTimeout),
         renderReadyTimeout: envNum("PRODUCER_RENDER_READY_TIMEOUT_MS", DEFAULT_CONFIG.renderReadyTimeout),
-        pageNavigationTimeout: envNum("PRODUCER_PAGE_NAVIGATION_TIMEOUT_MS", DEFAULT_CONFIG.pageNavigationTimeout),
+        pageNavigationTimeout: resolvePageNavigationTimeout(),
         verifyRuntime: env("PRODUCER_VERIFY_HYPERFRAME_RUNTIME") !== "false",
         runtimeManifestPath: env("PRODUCER_HYPERFRAME_MANIFEST_PATH"),
         extractCacheDir: resolveExtractCacheDirFromEnv(env),

package/dist/index.d.ts

@@ -30,7 +30,7 @@
  *
  */
 export type { HfProtocol, HfMediaElement, HfTransitionMeta, CaptureOptions, CaptureVideoMetadataHint, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, CaptureWarningCode, SubTimelineWaitMemo, SubTimelineWaitOutcome, } from "./types.js";
-export { resolveConfig, validateEngineConfigSnapshot, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, applyConcreteGpuScreenshotClamp, explainDrawElementDisabled, resolveExtractCacheDir, defaultExtractCacheDir, EXTRACT_CACHE_DIR_DISABLED_ALIASES, type EngineConfig, type ExtractCacheDirResolution, } from "./config.js";
+export { resolveConfig, resolvePageNavigationTimeout, validateEngineConfigSnapshot, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, applyConcreteGpuScreenshotClamp, explainDrawElementDisabled, resolveExtractCacheDir, defaultExtractCacheDir, EXTRACT_CACHE_DIR_DISABLED_ALIASES, type EngineConfig, type ExtractCacheDirResolution, } from "./config.js";
 export { SDR_RGB_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "./utils/sdrCaptureColor.js";
 export { DEFAULT_VP9_CPU_USED, MAX_VP9_CPU_USED, MIN_VP9_CPU_USED, normalizeVp9CpuUsed, } from "./services/vp9Options.js";
 export { getCgroupMemoryLimitMb, getSystemTotalMb, isLowMemorySystem, LOW_MEMORY_TOTAL_MB_THRESHOLD, } from "./services/systemMemory.js";

package/dist/index.js

@@ -30,7 +30,7 @@
  *
  */
 // ── Configuration ──────────────────────────────────────────────────────────────
-export { resolveConfig, validateEngineConfigSnapshot, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, applyConcreteGpuScreenshotClamp, explainDrawElementDisabled, resolveExtractCacheDir, defaultExtractCacheDir, EXTRACT_CACHE_DIR_DISABLED_ALIASES, } from "./config.js";
+export { resolveConfig, resolvePageNavigationTimeout, validateEngineConfigSnapshot, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, applyConcreteGpuScreenshotClamp, explainDrawElementDisabled, resolveExtractCacheDir, defaultExtractCacheDir, EXTRACT_CACHE_DIR_DISABLED_ALIASES, } from "./config.js";
 export { SDR_RGB_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "./utils/sdrCaptureColor.js";
 export { DEFAULT_VP9_CPU_USED, MAX_VP9_CPU_USED, MIN_VP9_CPU_USED, normalizeVp9CpuUsed, } from "./services/vp9Options.js";
 export { getCgroupMemoryLimitMb, getSystemTotalMb, isLowMemorySystem, LOW_MEMORY_TOTAL_MB_THRESHOLD, } from "./services/systemMemory.js";

package/dist/services/chunkEncoder.js

@@ -9,7 +9,7 @@ import { closeSync, copyFileSync, existsSync, ftruncateSync, mkdirSync, mkdtempS
 import { join, dirname, extname } from "path";
 import { DEFAULT_CONFIG } from "../config.js";
 import { getCachedGpuEncoder, getGpuEncoderName, buildVideoToolboxRateControlArgs, mapPresetForGpuEncoder, } from "../utils/gpuEncoder.js";
-import { getHdrEncoderColorParams } from "../utils/hdr.js";
+import { getHdrEncoderColorParams, hdrFrameTagsFilter } from "../utils/hdr.js";
 import { withEvenDimensionPad } from "../utils/evenDimensions.js";
 import { SDR_CAPTURE_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "../utils/sdrCaptureColor.js";
 import { describeFfmpegFailure, ffmpegStatsReader, formatFfmpegError, isExternalFfmpegInterruption, runFfmpeg, } from "../utils/runFfmpeg.js";
@@ -325,8 +325,9 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
         }
         // Range conversion: Chrome's full-range capture → limited/TV range; SDR also
         // converts to the BT.709 matrix it is tagged with.
+        const hdrTags = options.hdr ? hdrFrameTagsFilter(options.hdr.transfer) : undefined;
         const sdrFilter = options.hdr ? undefined : SDR_CAPTURE_TO_BT709_FILTER;
-        const captureFilter = sdrFilter ?? "scale=in_range=pc:out_range=tv";
+        const captureFilter = sdrFilter ?? `scale=in_range=pc:out_range=tv,${hdrTags}`;
         if (gpuEncoder === "vaapi") {
             // vaapi already runs `format=nv12,hwupload`; the nv12 conversion aligns
             // odd dimensions before upload, so only prepend the colour conversion.
@@ -340,7 +341,7 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
             // encoder. They hit the same "height not divisible by 2" abort as
             // libx264 on an odd-sized 4:2:0 canvas, so pad odd dimensions up to even
             // on the software side before the encode.
-            const vf = withEvenDimensionPad(sdrFilter ?? "", pixelFormat, options.width, options.height);
+            const vf = withEvenDimensionPad(sdrFilter ?? hdrTags ?? "", pixelFormat, options.width, options.height);
             if (vf)
                 args.push("-vf", vf);
         }

package/dist/services/extractionCache.d.ts

@@ -42,7 +42,7 @@ export declare const GC_MARKER = ".hf-last-gc";
  * Current schema version. Bump it whenever extraction writes different frames for the same key,
  * or warm entries keep serving the old frames across a deploy. Each bump's commit says why.
  */
-export declare const SCHEMA_PREFIX = "hfcache-v7-";
+export declare const SCHEMA_PREFIX = "hfcache-v8-";
 export type CacheFrameFormat = "jpg" | "png";
 export interface CacheKeyInput {
     /** Absolute path to the source video file. Part of the key so moved files

package/dist/services/extractionCache.js

@@ -45,7 +45,7 @@ export const GC_MARKER = ".hf-last-gc";
  * Current schema version. Bump it whenever extraction writes different frames for the same key,
  * or warm entries keep serving the old frames across a deploy. Each bump's commit says why.
  */
-export const SCHEMA_PREFIX = "hfcache-v7-";
+export const SCHEMA_PREFIX = "hfcache-v8-";
 /** Truncated hex chars of SHA-256 used for the entry directory name. */
 const KEY_HEX_CHARS = 16;
 export async function readContentSha256(path, signal) {

package/dist/services/frameCapture.d.ts

@@ -130,6 +130,7 @@ export interface CaptureSession {
     beginFrameIntervalMs: number;
     beginFrameHasDamageCount: number;
     beginFrameNoDamageCount: number;
+    beginFrameSeekPresented?: boolean;
     /** Optional producer config — when set, overrides module-level env var constants. */
     config?: Partial<EngineConfig>;
     /** True if running on SwiftShader (detected at init). Undefined before init. */

package/dist/services/frameCapture.js

@@ -2971,6 +2971,17 @@ async function captureFrameSurface(session, frameIndex, time, seekOptions, heldV
     let screenshotBuffer;
     if (session.captureMode === "beginframe") {
         const frameTimeTicks = session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs;
+        if (!session.beginFrameSeekPresented) {
+            // A session's first capture can return the frame composited during init instead of
+            // this seek, so display the seek once at a tick between the probe and this capture.
+            const client = await getCdpSession(page);
+            await client.send("HeadlessExperimental.beginFrame", {
+                frameTimeTicks: frameTimeTicks - session.beginFrameIntervalMs / 2,
+                interval: session.beginFrameIntervalMs,
+                noDisplayUpdates: false,
+            });
+            session.beginFrameSeekPresented = true;
+        }
         const result = await beginFrameCapture(page, options, frameTimeTicks, session.beginFrameIntervalMs);
         if (result.hasDamage)
             session.beginFrameHasDamageCount++;

package/dist/services/streamingEncoder.js

@@ -22,9 +22,9 @@ import { dirname } from "path";
 import { getCachedGpuEncoder, getGpuEncoderName, buildVideoToolboxRateControlArgs, mapPresetForGpuEncoder, } from "../utils/gpuEncoder.js";
 import { ffmpegStatsReader, formatFfmpegError, isExternalFfmpegInterruption, } from "../utils/runFfmpeg.js";
 import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
-import { getHdrEncoderColorParams } from "../utils/hdr.js";
+import { getHdrEncoderColorParams, hdrFrameTagsFilter } from "../utils/hdr.js";
 import { withEvenDimensionPad } from "../utils/evenDimensions.js";
-import { SDR_CAPTURE_TO_BT709_FILTER, SDR_RGB_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "../utils/sdrCaptureColor.js";
+import { SDR_CAPTURE_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "../utils/sdrCaptureColor.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core";
 import { appendVp9CpuUsedArg } from "./vp9Options.js";
@@ -248,26 +248,25 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
         else {
             args.push("-colorspace:v", "bt709", "-color_primaries:v", "bt709", "-color_trc:v", "bt709", "-color_range", "tv");
         }
-        // Raw HDR input (from WebGPU pipeline) is already PQ-encoded, so only SDR gets a
-        // conversion: raw sRGB or Chrome's BT.601 JPEG screenshots to BT.709 limited range.
-        const sdrFilter = options.rawInputFormat
-            ? SDR_RGB_TO_BT709_FILTER
-            : SDR_CAPTURE_TO_BT709_FILTER;
-        if (options.rawInputFormat && options.hdr) {
-            // No filter needed — PQ data goes straight to encoder
-        }
-        else if (gpuEncoder === "vaapi") {
+        // Raw HDR input (from WebGPU pipeline) is already PQ-encoded and is only tagged; SDR is
+        // converted: raw sRGB or Chrome's BT.601 JPEG screenshots to tagged BT.709 limited range.
+        const frameFilter = options.rawInputFormat && options.hdr
+            ? hdrFrameTagsFilter(options.hdr.transfer)
+            : options.rawInputFormat
+                ? SDR_RGB_TO_TAGGED_BT709_FILTER
+                : SDR_CAPTURE_TO_BT709_FILTER;
+        if (gpuEncoder === "vaapi") {
             // vaapi already runs `format=nv12,hwupload`; the nv12 conversion aligns
             // odd dimensions before upload, so only prepend the colour conversion.
             const vfIdx = args.indexOf("-vf");
             if (vfIdx !== -1) {
-                args[vfIdx + 1] = `${sdrFilter},${args[vfIdx + 1]}`;
+                args[vfIdx + 1] = `${frameFilter},${args[vfIdx + 1]}`;
             }
         }
         else {
             // Pad odd dimensions up to even so 4:2:0 encoders (software and
             // nvenc/videotoolbox/qsv/amf) don't abort with "height not divisible by 2".
-            args.push("-vf", withEvenDimensionPad(sdrFilter, pixelFormat, options.width, options.height));
+            args.push("-vf", withEvenDimensionPad(frameFilter, pixelFormat, options.width, options.height));
         }
         // Fixed timescale for consistent A/V timing across platforms.
         args.push("-video_track_timescale", "90000");

package/dist/services/videoFrameExtractor.js

@@ -437,6 +437,14 @@ function chromeGuessForUntaggedMatrix(metadata) {
  * same absolute times as a single pass, so their frames are byte-identical to it.
  */
 const EXTRACTION_SEGMENT_SECONDS = 120;
+/** Frame times since file start are `PTS*TB + seek`; snapping them to `lead + k/FR` gives every process one grid. */
+function undoTickRoundingOnTheSourceFrameGrid(seek, lead) {
+    const sinceFileStart = `(PTS*TB+${seek}-${lead})`;
+    return [
+        "settb=AVTB",
+        `setpts=if(isnan(FR)\\,PTS\\,(${lead}+round(${sinceFileStart}*FR)/FR-${seek})/TB)`,
+    ];
+}
 // Caps extraction ffmpeg runs across all clips; uncapped, dozens of clips starved each other into timeouts.
 const EXTRACTION_SLOTS = Math.max(1, Math.floor(cpus().length / 2));
 const inExtractionSlot = createConcurrencyLimit(EXTRACTION_SLOTS);
@@ -467,11 +475,12 @@ async function runSegmentedExtraction(job) {
         while (next < segmentCount && !signal.aborted) {
             const index = next++;
             const { firstFrame, frames } = segments[index];
+            const seek = startTime + firstFrame / fps;
             const result = await inExtractionSlot(() => runFfmpeg([
                 ...decodeArgs,
                 "-noaccurate_seek",
                 "-ss",
-                String(startTime + firstFrame / fps),
+                String(seek),
                 "-i",
                 videoPath,
                 // Read one frame past the segment and keep exactly its own frames.
@@ -481,7 +490,7 @@ async function runSegmentedExtraction(job) {
                 String(frames),
                 "-start_number",
                 String(firstFrame + 1),
-                ...filterAndEncodeArgs,
+                ...filterAndEncodeArgs(seek),
             ], { ...job.runOptions, signal }), signal);
             results[index] = result;
             if (!result.success)
@@ -580,11 +589,19 @@ outputDirOverride) {
     if (decodeWithVideoToolbox) {
         vfFilters.push("format=nv12");
     }
-    if (sampleAtOutputFps) {
-        // Each slot takes the last frame starting at or before its time. Ticks of 2 ms or finer
-        // first shift half a tick, absorbing container rounding (WebM/MKV use whole ms).
-        vfFilters.push("settb=intb/2", "setpts=PTS-lte(TB\\,0.001)", `fps=${ffmpegFps}:start_time=0:round=up`);
-    }
+    const samplingAt = vfFilters.length;
+    // Each slot takes the last frame starting at or before its time. Ticks of 2 ms or finer
+    // first shift half a tick, absorbing container rounding (WebM/MKV use whole ms).
+    const samplingFilters = (seek) => sampleAtOutputFps
+        ? [
+            ...(metadata.isVFR
+                ? []
+                : undoTickRoundingOnTheSourceFrameGrid(seek, metadata.videoStreamLeadSeconds ?? 0)),
+            "settb=intb/2",
+            "setpts=PTS-lte(TB\\,0.001)",
+            `fps=${ffmpegFps}:start_time=0:round=up`,
+        ]
+        : [];
     if (options.sdrToHdrTransfer) {
         // Ordering intent: fps sampling runs BEFORE the colorspace remap so only
         // kept frames are converted. The remap is pointwise per-frame, so the
@@ -610,7 +627,11 @@ outputDirOverride) {
         encodeArgs.push("-compression_level", "1");
     encodeArgs.push("-y", outputPattern);
     const runOptions = { signal, timeout: ffmpegProcessTimeout };
-    const filterArgs = vfFilters.length > 0 ? ["-vf", vfFilters.join(",")] : [];
+    const filterArgsFor = (seek) => {
+        const filters = [...vfFilters];
+        filters.splice(samplingAt, 0, ...samplingFilters(seek));
+        return filters.length > 0 ? ["-vf", filters.join(",")] : [];
+    };
     const segmentFrames = Math.round(EXTRACTION_SEGMENT_SECONDS * fps);
     const totalFrames = extractionFrameCountForDuration(duration, normalizedFps, metadata.isVFR);
     // A VFR window rounds its frame count up, and only the segments' `-frames:v` bound
@@ -620,14 +641,14 @@ outputDirOverride) {
     const processResult = sampleAtOutputFps && (options.frameRanges || boundVfrFrameCount || totalFrames > segmentFrames)
         ? await runSegmentedExtraction({
             decodeArgs,
-            filterAndEncodeArgs: [...filterArgs, ...encodeArgs],
+            filterAndEncodeArgs: (seek) => [...filterArgsFor(seek), ...encodeArgs],
             videoPath,
             startTime,
             fps,
             segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
             runOptions,
         })
-        : await inExtractionSlot(() => runFfmpeg([...args, ...filterArgs, ...encodeArgs], runOptions), signal);
+        : await inExtractionSlot(() => runFfmpeg([...args, ...filterArgsFor(startTime), ...encodeArgs], runOptions), signal);
     if (processResult.failureReason === "external_interruption") {
         throw new VideoSourceExtractionError("external_interruption", true, "Video frame extraction interrupted by host lifecycle", `FFmpeg exited with code ${processResult.exitCode}: ${processResult.stderr.slice(-500)}`);
     }

package/dist/utils/hdr.d.ts

@@ -70,6 +70,7 @@ export interface HdrEncoderColorParams {
  * stream is rejected as SDR by most HDR-aware players and CDNs.
  */
 export declare function getHdrEncoderColorParams(transfer: HdrTransfer, mastering?: HdrMasteringMetadata): HdrEncoderColorParams;
+export declare function hdrFrameTagsFilter(transfer: HdrTransfer): string;
 export interface CompositionHdrInfo {
     hasHdr: boolean;
     dominantTransfer: HdrTransfer | null;

package/dist/utils/hdr.js

@@ -64,6 +64,10 @@ export function getHdrEncoderColorParams(transfer, mastering = DEFAULT_HDR10_MAS
         mastering,
     };
 }
+export function hdrFrameTagsFilter(transfer) {
+    const { colorPrimaries, colorTrc, colorspace } = getHdrEncoderColorParams(transfer);
+    return `setparams=color_primaries=${colorPrimaries}:color_trc=${colorTrc}:colorspace=${colorspace}:range=tv`;
+}
 export const HDR_AUTO_PROMOTION_PIPELINE = {
     colorSpace: "BT.2020",
     codec: "HEVC Main10",

package/dist/utils/sdrCaptureColor.d.ts

@@ -1,3 +1,3 @@
 export declare const SDR_RGB_TO_BT709_FILTER = "scale=out_color_matrix=bt709:out_range=tv:flags=neighbor";
-export declare const SDR_CAPTURE_TO_BT709_FILTER = "scale=in_color_matrix=bt601:in_range=pc:flags=neighbor+accurate_rnd,format=gbrp,scale=out_color_matrix=bt709:out_range=tv:flags=neighbor";
 export declare const SDR_RGB_TO_TAGGED_BT709_FILTER = "scale=out_color_matrix=bt709:out_range=tv:flags=neighbor,setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv";
+export declare const SDR_CAPTURE_TO_BT709_FILTER = "scale=in_color_matrix=bt601:in_range=pc:flags=neighbor+accurate_rnd,format=gbrp,scale=out_color_matrix=bt709:out_range=tv:flags=neighbor,setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv";

package/dist/utils/sdrCaptureColor.js

@@ -1,3 +1,3 @@
 export const SDR_RGB_TO_BT709_FILTER = "scale=out_color_matrix=bt709:out_range=tv:flags=neighbor";
-export const SDR_CAPTURE_TO_BT709_FILTER = `scale=in_color_matrix=bt601:in_range=pc:flags=neighbor+accurate_rnd,format=gbrp,${SDR_RGB_TO_BT709_FILTER}`;
 export const SDR_RGB_TO_TAGGED_BT709_FILTER = `${SDR_RGB_TO_BT709_FILTER},setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv`;
+export const SDR_CAPTURE_TO_BT709_FILTER = `scale=in_color_matrix=bt601:in_range=pc:flags=neighbor+accurate_rnd,format=gbrp,${SDR_RGB_TO_TAGGED_BT709_FILTER}`;

package/package.json

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