@hyperframes/engine 0.9.5 → 0.9.6

package/dist/config.d.ts

@@ -74,6 +74,7 @@ export interface EngineConfig {
      * true. Kill switch: `HF_DE_WORKER_ENCODE=false`.
      */
     enableDrawElementWorkerEncode: boolean;
+    useInPageEncode: boolean;
     /**
      * INTERNAL. Set by resolveConfig when it disabled enablePageSideCompositing
      * solely because drawElement was on. Lets the producer's compile-time gates

package/dist/config.js

@@ -32,6 +32,7 @@ export const DEFAULT_CONFIG = {
     videoLayerPassthrough: false,
     useDrawElement: true,
     enableDrawElementWorkerEncode: true,
+    useInPageEncode: false,
     // Auto-detected per host in `resolveConfig`; defaults off for the raw
     // DEFAULT_CONFIG (used directly by tests and worker-sizing fallbacks).
     lowMemoryMode: false,
@@ -76,6 +77,7 @@ const BOOLEAN_ENGINE_CONFIG_FIELDS = [
     "videoLayerPassthrough",
     "useDrawElement",
     "enableDrawElementWorkerEncode",
+    "useInPageEncode",
     "lowMemoryMode",
     "enablePageSideCompositing",
     "enableChunkedEncode",
@@ -517,6 +519,7 @@ export function resolveConfig(overrides) {
         videoLayerPassthrough: envBool("HF_VIDEO_LAYER_PASSTHROUGH", DEFAULT_CONFIG.videoLayerPassthrough),
         useDrawElement: envBool("PRODUCER_EXPERIMENTAL_FAST_CAPTURE", DEFAULT_CONFIG.useDrawElement),
         enableDrawElementWorkerEncode: envBool("HF_DE_WORKER_ENCODE", DEFAULT_CONFIG.enableDrawElementWorkerEncode),
+        useInPageEncode: envBool("HF_INPAGE_ENCODE", DEFAULT_CONFIG.useInPageEncode),
         lowMemoryMode: resolveLowMemoryMode(),
         enablePageSideCompositing: envBool("HF_PAGE_SIDE_COMPOSITING", DEFAULT_CONFIG.enablePageSideCompositing),
         vp9CpuUsed: envVp9CpuUsed(),

package/dist/index.d.ts

@@ -48,6 +48,8 @@ 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 { spawnChunkStreamingEncoder, buildChunkStreamingArgs, BT709_LIMITED, type ChunkColour, type ChunkStreamingOptions, } from "./services/chunkStreamingEncoder.js";
+export { resolveInPageEncode, type InPageEncodeDecision, type InPageEncodeInput, } from "./services/inPageEncodeEligibility.js";
 export { parseVideoElements, hasGradedCanvas, 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, buildVideoLayerInput, type VideoLayerInput, } from "./services/videoFrameExtractor.js";
 export { qualifyVideoLayer } from "./services/videoLayerPassthrough.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";

package/dist/index.js

@@ -51,6 +51,8 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 // ── Encoding ───────────────────────────────────────────────────────────────────
 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";
+export { spawnChunkStreamingEncoder, buildChunkStreamingArgs, BT709_LIMITED, } from "./services/chunkStreamingEncoder.js";
+export { resolveInPageEncode, } from "./services/inPageEncodeEligibility.js";
 // ── Media processing ───────────────────────────────────────────────────────────
 export { parseVideoElements, hasGradedCanvas, 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, buildVideoLayerInput, } from "./services/videoFrameExtractor.js";
 export { qualifyVideoLayer } from "./services/videoLayerPassthrough.js";

package/dist/services/chunkStreamingEncoder.d.ts

@@ -0,0 +1,16 @@
+import type { Fps } from "@hyperframes/core";
+import type { EngineConfig } from "../config.js";
+import { type StreamingEncoder } from "./streamingEncoder.js";
+export interface ChunkColour {
+    primaries: number;
+    transfer: number;
+    matrix: number;
+    fullRange: boolean;
+}
+export declare const BT709_LIMITED: ChunkColour;
+export interface ChunkStreamingOptions {
+    fps: Fps;
+    colour?: ChunkColour;
+}
+export declare function buildChunkStreamingArgs(options: ChunkStreamingOptions, outputPath: string): string[];
+export declare function spawnChunkStreamingEncoder(outputPath: string, options: ChunkStreamingOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>): StreamingEncoder;

package/dist/services/chunkStreamingEncoder.js

@@ -0,0 +1,30 @@
+import { fpsToFfmpegArg } from "@hyperframes/core";
+import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
+import { spawnFfmpegStream } from "./streamingEncoder.js";
+export const BT709_LIMITED = {
+    primaries: 1,
+    transfer: 1,
+    matrix: 1,
+    fullRange: false,
+};
+export function buildChunkStreamingArgs(options, outputPath) {
+    const { primaries, transfer, matrix, fullRange } = options.colour ?? BT709_LIMITED;
+    const vui = [
+        `colour_primaries=${primaries}`,
+        `transfer_characteristics=${transfer}`,
+        `matrix_coefficients=${matrix}`,
+        `video_full_range_flag=${fullRange ? 1 : 0}`,
+    ].join(":");
+    const args = ["-f", "h264", "-framerate", fpsToFfmpegArg(options.fps), "-i", "-"];
+    args.push("-c:v", "copy", "-bsf:v", `h264_metadata=${vui}`);
+    args.push(...["-colorspace:v", "bt709", "-color_primaries:v", "bt709", "-color_trc:v", "bt709"], ...["-color_range", fullRange ? "pc" : "tv"], ...["-video_track_timescale", "90000", "-avoid_negative_ts", "make_zero"]);
+    appendRenderProvenanceArgs(args, outputPath);
+    args.push("-y", outputPath);
+    return args;
+}
+export function spawnChunkStreamingEncoder(outputPath, options, signal, config) {
+    return spawnFfmpegStream(outputPath, buildChunkStreamingArgs(options, outputPath), {
+        signal,
+        config,
+    });
+}

package/dist/services/frameCapture.js

@@ -18,7 +18,7 @@ import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERT
 import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, } from "./pageMotionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
-import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, capturesAlpha, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
+import { beginFrameCapture, forgetBeginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, capturesAlpha, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
 import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, forcePreservedDrawingBuffer, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
 import { initThreeDProjection, scanCssEffects } from "./threeDProjection.js";
 import { planRiskFrames, scanCssEffectLiveFrames, riskSessionFits, withFramesAfterCallback, MAX_RISK_FRAME_FRACTION, } from "./riskFrames.js";
@@ -3299,6 +3299,7 @@ async function captureFrameSurface(session, frameIndex, time, seekOptions, heldV
                 interval: session.beginFrameIntervalMs,
                 noDisplayUpdates: false,
             });
+            forgetBeginFrameCapture(page);
             session.beginFrameSeekPresented = true;
         }
         const result = await beginFrameCapture(page, options, frameTimeTicks, session.beginFrameIntervalMs);

package/dist/services/inPageEncodeEligibility.d.ts

@@ -0,0 +1,19 @@
+export interface InPageEncodeInput {
+    enabled: boolean;
+    captureMode: "drawelement" | "screenshot" | "beginframe";
+    format: string;
+    codec: string;
+    hdr: boolean;
+    transparent: boolean;
+    workers: number;
+    hls: boolean;
+    videoLayer: boolean;
+    encoderSupported: boolean;
+}
+export type InPageEncodeDecision = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: string;
+};
+export declare function resolveInPageEncode(input: InPageEncodeInput): InPageEncodeDecision;

package/dist/services/inPageEncodeEligibility.js

@@ -0,0 +1,15 @@
+export function resolveInPageEncode(input) {
+    const blocker = [
+        [!input.enabled, "disabled"],
+        [input.captureMode !== "drawelement", "capture is not drawElement"],
+        [input.format !== "mp4", "output is not mp4"],
+        [input.codec !== "h264", "codec is not h264"],
+        [input.hdr, "hdr"],
+        [input.transparent, "transparent"],
+        [input.workers !== 1, "parallel workers"],
+        [input.hls, "hls"],
+        [input.videoLayer, "video layer passthrough"],
+        [!input.encoderSupported, "page encoder unsupported"],
+    ].find(([blocked]) => blocked);
+    return blocker ? { eligible: false, reason: blocker[1] } : { eligible: true };
+}

package/dist/services/screenshotService.d.ts

@@ -32,6 +32,7 @@ export interface BeginFrameResult {
  * the safe direction (screenshot capture always works).
  */
 export declare function probeBeginFrameLiveness(page: Page, timeoutMs: number, frameTimeTicks?: number, intervalMs?: number): Promise<boolean>;
+export declare function forgetBeginFrameCapture(page: Page): void;
 export declare function beginFrameCapture(page: Page, options: CaptureOptions, frameTimeTicks: number, interval: number): Promise<BeginFrameResult>;
 /**
  * True if the page's actual rendered content is taller than the requested

package/dist/services/screenshotService.js

@@ -81,11 +81,14 @@ frameTimeTicks, intervalMs) {
  * Requires chrome-headless-shell with --enable-begin-frame-control and
  * --deterministic-mode flags.
  */
-// Cache the last valid screenshot buffer per page for hasDamage=false frames.
-// When Chrome reports no visual change, we reuse the previous frame rather than
-// attempting Page.captureScreenshot (which times out in beginFrame mode since
-// the compositor is paused).
+// The last buffer beginFrameCapture returned per page. A screenshot BeginFrame always
+// reports damage, so a frame is reused only when a screenshot-less BeginFrame right after
+// the seek reports none. Any BeginFrame sent elsewhere moves the display past this buffer:
+// call forgetBeginFrameCapture first.
 const lastFrameCache = new WeakMap();
+export function forgetBeginFrameCapture(page) {
+    lastFrameCache.delete(page);
+}
 const PENDING_FRAME_RETRIES = 5;
 async function sendBeginFrame(client, params) {
     for (let attempt = 0;; attempt++) {
@@ -115,14 +118,30 @@ export async function beginFrameCapture(page, options, frameTimeTicks, interval)
         quality: isPng ? undefined : (options.quality ?? 80),
         optimizeForSpeed: true,
     };
-    const result = await sendBeginFrame(client, { frameTimeTicks, interval, screenshot });
+    // With a cached buffer, a screenshot-less BeginFrame first draws the seek and reports
+    // whether it changed anything. The screenshot after it is not displayed: a displayed
+    // screenshot frame leaves damage the next probe would report, and a settle frame to
+    // absorb it would draw page changes that nothing captures.
+    const cached = lastFrameCache.get(page);
+    let screenshotTicks = frameTimeTicks;
+    if (cached) {
+        const probe = await sendBeginFrame(client, { frameTimeTicks, interval });
+        if (!probe.hasDamage)
+            return { buffer: cached, hasDamage: false };
+        screenshotTicks = frameTimeTicks + interval / 2;
+    }
+    const result = await sendBeginFrame(client, {
+        frameTimeTicks: screenshotTicks,
+        interval,
+        screenshot,
+        noDisplayUpdates: cached !== undefined,
+    });
     let buffer;
     if (result.screenshotData) {
         buffer = Buffer.from(result.screenshotData, "base64");
         lastFrameCache.set(page, buffer);
     }
     else {
-        const cached = lastFrameCache.get(page);
         if (cached) {
             buffer = cached;
         }

package/dist/services/streamingEncoder.d.ts

@@ -109,3 +109,8 @@ export declare function buildStreamingArgs(options: StreamingEncoderOptions, out
  * Spawn a streaming FFmpeg encoder that accepts frame buffers on stdin.
  */
 export declare function spawnStreamingEncoder(outputPath: string, options: StreamingEncoderOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>): Promise<StreamingEncoder>;
+export declare function spawnFfmpegStream(outputPath: string, args: string[], { signal, config, checkFrame, }: {
+    signal?: AbortSignal;
+    config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>;
+    checkFrame?: (frame: Buffer, index: number) => void;
+}): StreamingEncoder;

package/dist/services/streamingEncoder.js

@@ -302,15 +302,29 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null, nvenc
  * Spawn a streaming FFmpeg encoder that accepts frame buffers on stdin.
  */
 export async function spawnStreamingEncoder(outputPath, options, signal, config) {
-    const outputDir = dirname(outputPath);
-    if (!existsSync(outputDir))
-        mkdirSync(outputDir, { recursive: true });
     let gpuEncoder = null;
     if (options.useGpu) {
         gpuEncoder = await getCachedGpuEncoder();
     }
     const nvencPresets = gpuEncoder === "nvenc" ? await getCachedNvencPresets() : undefined;
     const args = buildStreamingArgs(options, outputPath, gpuEncoder, nvencPresets);
+    const checksJpeg = !options.rawInputFormat && (options.imageFormat ?? "jpeg") === "jpeg";
+    return spawnFfmpegStream(outputPath, args, {
+        signal,
+        config,
+        checkFrame: checksJpeg
+            ? (frame, index) => {
+                const error = jpegInputError(frame);
+                if (error)
+                    throw new Error(`Invalid JPEG input at frame ${index}: ${error}`);
+            }
+            : undefined,
+    });
+}
+export function spawnFfmpegStream(outputPath, args, { signal, config, checkFrame, }) {
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir))
+        mkdirSync(outputDir, { recursive: true });
     const ffmpeg = spawn(getFfmpegBinary(), args, {
         stdio: ["pipe", "pipe", "pipe"],
         // See runFfmpeg.ts: keeps a console window off the user's desktop on Windows.
@@ -412,11 +426,7 @@ export async function spawnStreamingEncoder(outputPath, options, signal, config)
             // so without this copy the pipe would read partially-overwritten data
             // and flicker.
             const copy = Buffer.from(buffer);
-            if (!options.rawInputFormat && (options.imageFormat ?? "jpeg") === "jpeg") {
-                const error = jpegInputError(copy);
-                if (error)
-                    throw new Error(`Invalid JPEG input at frame ${inputFrameIndex}: ${error}`);
-            }
+            checkFrame?.(copy, inputFrameIndex);
             const accepted = stdin.write(copy);
             inputFrameIndex++;
             // Reset inactivity timer immediately ONLY on `accepted === true`. `true`

package/package.json

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