@hyperframes/engine 0.8.172 → 0.8.173

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

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