@hyperframes/engine 0.9.28-alpha.0 → 0.9.28

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-v8-";
+export declare const SCHEMA_PREFIX = "hfcache-v9-";
 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

@@ -46,7 +46,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-v8-";
+export const SCHEMA_PREFIX = "hfcache-v9-";
 /** 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

@@ -584,10 +584,12 @@ async function leadInSecondsUnlessAborted(videoPath, seek, signal) {
 function stallTimeoutMs(baseMs, skippedSeconds, sourceFps) {
     return baseMs + Math.ceil((skippedSeconds * sourceFps * 1000) / SKIP_DECODE_FPS_FLOOR);
 }
+const KEEP_END_PAST_A_ONE_TICK_FINAL_FRAME_THROUGH_THE_SNAP = "tpad=stop_mode=clone:stop=1";
 /** Frame times since file start are `PTS*TB + seek`; snapping them to `lead + k/FR` gives every process one grid. */
-function undoTickRoundingOnTheSourceFrameGrid(seek, lead) {
+function undoTickRoundingOnTheSourceFrameGrid(seek, lead, sourceFps) {
     const sinceFileStart = `(PTS*TB+${seek}-${lead})`;
     return [
+        ...(sourceFps > 0 ? [KEEP_END_PAST_A_ONE_TICK_FINAL_FRAME_THROUGH_THE_SNAP] : []),
         "settb=AVTB",
         `setpts=if(isnan(FR)\\,PTS\\,(${lead}+round(${sinceFileStart}*FR)/FR-${seek})/TB)`,
     ];
@@ -610,13 +612,14 @@ function framesWrittenReader(onProgress) {
     return (chunk) => read(chunk);
 }
 /** Split runs so no single ffmpeg process extracts more than `segmentFrames` frames. */
-function splitFrameRanges(ranges, segmentFrames) {
+function splitFrameRanges(ranges, segmentFrames, frameLimit) {
     const segments = [];
     for (const range of ranges) {
-        for (let offset = 0; offset < range.frames; offset += segmentFrames) {
+        const frames = Math.min(range.frames, frameLimit - range.firstFrame);
+        for (let offset = 0; offset < frames; offset += segmentFrames) {
             segments.push({
                 firstFrame: range.firstFrame + offset,
-                frames: Math.min(segmentFrames, range.frames - offset),
+                frames: Math.min(segmentFrames, frames - offset),
             });
         }
     }
@@ -710,7 +713,7 @@ function videoFilterChain(input) {
         ? [
             ...(metadata.isVFR
                 ? []
-                : undoTickRoundingOnTheSourceFrameGrid(seek, videoStartOnMediaTimeline(metadata))),
+                : undoTickRoundingOnTheSourceFrameGrid(seek, videoStartOnMediaTimeline(metadata), metadata.fps)),
             "settb=intb/2",
             "setpts=PTS-lte(TB\\,0.001)",
             `fps=${ffmpegFps}:start_time=0:round=up`,
@@ -871,11 +874,14 @@ outputDirOverride) {
         return filters.length > 0 ? ["-vf", filters.join(",")] : [];
     };
     const segmentFrames = Math.round(EXTRACTION_SEGMENT_SECONDS * fps);
-    const totalFrames = extractionFrameCountForDuration(duration, normalizedFps, metadata.isVFR);
+    const windowFrames = extractionFrameCountForDuration(duration, normalizedFps, metadata.isVFR);
+    const framesBeforeSourceEnd = extractionFrameCountForDuration(playableDuration - startTime, normalizedFps, false);
+    const totalFrames = metadata.isVFR ? windowFrames : Math.min(windowFrames, framesBeforeSourceEnd);
     // A VFR window rounds its frame count up, and only the segments' `-frames:v` bound
     // emits that last slot: the fps filter ends a `-t` window at the nearest slot. A
     // decimal rate counts zero frames here and keeps the `-t` window.
     const boundVfrFrameCount = metadata.isVFR && totalFrames > 0;
+    const frameCap = sampleAtOutputFps && totalFrames > 0 ? ["-frames:v", String(totalFrames)] : [];
     const extract = (hwaccel) => sampleAtOutputFps && (options.frameRanges || boundVfrFrameCount || totalFrames > segmentFrames)
         ? runSegmentedExtraction({
             decodeArgs: [...hwaccel, ...decodeArgs],
@@ -886,11 +892,11 @@ outputDirOverride) {
             fps,
             sourceFps: metadata.fps,
             gate: options.tailProbe ? inTailProbeSlot : inExtractionSlot,
-            segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
+            segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames, totalFrames > 0 ? totalFrames : Number.POSITIVE_INFINITY),
             runOptions,
             onProgress: options.onProgress,
         })
-        : inExtractionSlot(async () => runFfmpeg([...hwaccel, ...args, ...filterArgsFor(startTime), ...encodeArgs], {
+        : inExtractionSlot(async () => runFfmpeg([...hwaccel, ...args, ...frameCap, ...filterArgsFor(startTime), ...encodeArgs], {
             ...runOptions,
             onStderr: framesWrittenReader(options.onProgress),
             timeout: stallTimeoutMs(ffmpegProcessTimeout, options.finalFrameOnly

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.9.28-alpha.0",
+  "version": "0.9.28",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -61,8 +61,8 @@
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
     "undici": "7.25.0",
-    "@hyperframes/parsers": "^0.9.28-alpha.0",
-    "@hyperframes/core": "^0.9.28-alpha.0"
+    "@hyperframes/core": "^0.9.28",
+    "@hyperframes/parsers": "^0.9.28"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",