@hyperframes/engine 0.8.155 → 0.8.157

package/dist/services/audioMixer.d.ts

@@ -8,8 +8,8 @@ export type { AudioElement, MixResult } from "./audioMixer.types.js";
 export declare const MIXED_AUDIO_FILENAME = "audio.m4a";
 /** afade stages after the volume filter (leading comma), or "" when none. Stream time 0 is the clip start. */
 export declare function buildFadeFilters(track: Pick<AudioTrack, "start" | "end" | "fadeIn" | "fadeOut">): string;
-/** One track: trim, volume, afade, delay/pad. asetpts after apad so FFmpeg 5-8 delayed branches do not land at t=0. */
-export declare function buildTrackInputFilter(track: Pick<AudioTrack, "start" | "end" | "fadeIn" | "fadeOut" | "tailSeconds">, index: number, volumeFilter: string, totalDuration: number): string;
+/** One track: trim, volume, afade, delay. Legacy and group mixes also pad each branch. */
+export declare function buildTrackInputFilter(track: Pick<AudioTrack, "start" | "end" | "fadeIn" | "fadeOut" | "tailSeconds">, index: number, volumeFilter: string, totalDuration: number, padToDuration?: boolean): string;
 /**
  * A volume lane as keyframes for the PCM baker.
  *

package/dist/services/audioMixer.js

@@ -250,11 +250,12 @@ export function buildFadeFilters(track) {
     }
     return stages.length ? `,${stages.join(",")}` : "";
 }
-/** One track: trim, volume, afade, delay/pad. asetpts after apad so FFmpeg 5-8 delayed branches do not land at t=0. */
-export function buildTrackInputFilter(track, index, volumeFilter, totalDuration) {
+/** One track: trim, volume, afade, delay. Legacy and group mixes also pad each branch. */
+export function buildTrackInputFilter(track, index, volumeFilter, totalDuration, padToDuration = true) {
     const delayMs = Math.round(track.start * 1000);
     const trimDuration = track.end - track.start + (track.tailSeconds ?? 0);
-    return `[${index}:a]atrim=0:${formatFilterNumber(trimDuration)},${volumeFilter}${buildFadeFilters(track)},adelay=${delayMs}|${delayMs},apad,asetpts=N/SR/TB,atrim=0:${formatFilterNumber(totalDuration)}[a${index}]`;
+    const filters = `[${index}:a]atrim=0:${formatFilterNumber(trimDuration)},${volumeFilter}${buildFadeFilters(track)},adelay=${delayMs}|${delayMs}`;
+    return `${filters}${padToDuration ? `,apad,asetpts=N/SR/TB,atrim=0:${formatFilterNumber(totalDuration)}` : ""}[a${index}]`;
 }
 // Absolute paths are omitted: boundedDetail redacts them to end-of-line and they name the host.
 function missingSourceMessage(elementId, src, baseDir, resolvedPath) {
@@ -598,18 +599,20 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config,
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });
-    const buildFilterComplex = (ignoreAutomation) => {
+    const buildFilterComplex = (ignoreAutomation, useNormalize) => {
         const filterParts = [];
         tracks.forEach((track, i) => {
             const volumeFilter = buildVolumeExpression(track, ignoreAutomation);
-            filterParts.push(buildTrackInputFilter(track, i, volumeFilter, totalDuration));
+            filterParts.push(buildTrackInputFilter(track, i, volumeFilter, totalDuration, !useNormalize));
         });
         const mixInputs = tracks.map((_, i) => `[a${i}]`).join("");
-        const mixFilter = `${mixInputs}amix=inputs=${tracks.length}:duration=longest:dropout_transition=0[mixed]`;
-        // amix divides output by inputs count (default normalize=true). Multiply master
-        // gain by track count so per-track volumes authored in data-volume are preserved.
-        const compensatedGain = masterOutputGain * tracks.length;
-        const postMixGainFilter = `[mixed]volume=${formatFilterNumber(compensatedGain)}[out]`;
+        const mixFilter = `${mixInputs}amix=inputs=${tracks.length}:duration=longest:dropout_transition=0${useNormalize ? ":normalize=0" : ""}[mixed]`;
+        // Older FFmpeg builds lack normalize=0. Their default amix divides by the
+        // active input count, so keep all branches padded and compensate by N.
+        const gain = masterOutputGain * (useNormalize ? 1 : tracks.length);
+        const postMixGainFilter = useNormalize
+            ? `[mixed]volume=${formatFilterNumber(gain)},apad,asetpts=N/SR/TB,atrim=0:${formatFilterNumber(totalDuration)}[out]`
+            : `[mixed]volume=${formatFilterNumber(gain)}[out]`;
         return [...filterParts, mixFilter, postMixGainFilter].join(";");
     };
     // A large track count (100+) makes the inline `-filter_complex <string>`
@@ -623,14 +626,14 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config,
     // alias from nightly builds; older stable builds do not understand the new
     // spelling. Prefer the legacy spelling for broad compatibility and retry
     // only when FFmpeg explicitly says that option is unavailable.
-    const runMix = async (ignoreAutomation) => {
+    const runMix = async (ignoreAutomation, useNormalize) => {
         const inputs = [];
         tracks.forEach((track) => inputs.push("-i", track.srcPath));
         const scriptDir = mkdtempSync(join(outputDir, ".filter-complex-"));
         const scriptPath = join(scriptDir, "graph.txt");
         const fd = openSync(scriptPath, "wx", 0o600);
         try {
-            writeFileSync(fd, buildFilterComplex(ignoreAutomation));
+            writeFileSync(fd, buildFilterComplex(ignoreAutomation, useNormalize));
         }
         finally {
             closeSync(fd);
@@ -660,7 +663,15 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config,
             rmSync(scriptDir, { recursive: true, force: true });
         }
     };
-    let result = await runMix(false);
+    let useNormalize = true;
+    let result = await runMix(false, useNormalize);
+    if (!result.success &&
+        result.failureReason !== "external_interruption" &&
+        !signal?.aborted &&
+        groupNormalizeOptionUnsupported(result.stderr)) {
+        useNormalize = false;
+        result = await runMix(false, useNormalize);
+    }
     // Defense in depth: volume automation is folded into an FFmpeg `volume`
     // expression whose evaluator limits are build-dependent (see
     // MAX_VOLUME_SEGMENTS). If that ever fails the mix, retry once without the
@@ -672,7 +683,7 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config,
         result.failureReason !== "external_interruption" &&
         !signal?.aborted &&
         hasAutomation) {
-        const retry = await runMix(true);
+        const retry = await runMix(true, useNormalize);
         if (retry.success) {
             result = retry;
             degradedAutomation = true;
@@ -731,8 +742,8 @@ function groupNormalizeOptionUnsupported(stderr) {
 }
 /**
  * Sub-mix one group's members into a single PCM WAV at full composition
- * length — the same per-input treatment `mixAudioTracks` gives every track
- * (atrim, volume, adelay, `apad` — RULES 6), writing PCM instead of AAC so the
+ * length. Unlike the main mix, this still pads each member (atrim, volume,
+ * adelay, `apad` — RULES 6), writing PCM instead of AAC so the
  * result can feed straight into `applyAudioFxChain` (which reads raw WAV
  * samples, not a decoded container).
  *

package/dist/services/browserLeasePool.d.ts

@@ -4,6 +4,7 @@ export type BrowserPoolState = "launching" | "ready" | "closing";
 export interface BrowserLaunchFingerprint {
     readonly args: readonly string[];
     readonly executablePath?: string;
+    readonly withoutWaylandDisplay?: boolean;
     readonly browserTimeoutMs: number;
     readonly protocolTimeoutMs: number;
     readonly requestedCaptureMode: CaptureMode;

package/dist/services/browserLeasePool.js

@@ -8,6 +8,7 @@ function fingerprintKey(fingerprint) {
     return JSON.stringify([
         fingerprint.args,
         fingerprint.executablePath ?? null,
+        fingerprint.withoutWaylandDisplay === true,
         fingerprint.browserTimeoutMs,
         fingerprint.protocolTimeoutMs,
         fingerprint.requestedCaptureMode,

package/dist/services/browserManager.d.ts

@@ -33,6 +33,8 @@ export type AcquiredBrowser = BrowserLease;
  * then the CLI browser override, HyperFrames' managed cache, and Puppeteer's cache.
  */
 export declare function resolveHeadlessShellPath(config?: Partial<Pick<EngineConfig, "chromePath">>): string | undefined;
+/** Full Chrome for Testing in Puppeteer's cache (`@puppeteer/browsers install chrome@...`), newest first. */
+export declare function resolveFullChromePath(): string | undefined;
 export declare const ENABLE_BROWSER_POOL: boolean;
 /**
  * Probe the complete HeadlessExperimental.beginFrame runtime contract.
@@ -55,6 +57,8 @@ export declare const _probeBeginFrameSupportForTests: typeof probeBeginFrameSupp
 export declare const _closeBrowserAfterFailedProbeForTests: typeof closeBrowserAfterFailedProbe;
 /** Test-only: reset the cached probe result. */
 export declare function _resetAutoBrowserGpuModeCacheForTests(): void;
+/** True when a `resolvedMode` render must launch without WAYLAND_DISPLAY to reach the GPU. */
+export declare function captureWithoutWaylandDisplay(resolvedMode: "software" | "hardware"): Promise<boolean>;
 /**
  * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
  *
@@ -82,10 +86,13 @@ export declare function _resetAutoBrowserGpuModeCacheForTests(): void;
  * render.
  */
 export declare function resolveBrowserGpuMode(mode: EngineConfig["browserGpuMode"], options?: GpuProbeOptions): Promise<"software" | "hardware">;
-declare function createBrowserLaunchFingerprint(chromeArgs: string[], config?: Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">>): BrowserLaunchFingerprint;
+type BrowserLaunchConfig = Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "chromePath" | "forceScreenshot">> & {
+    withoutWaylandDisplay?: boolean;
+};
+declare function createBrowserLaunchFingerprint(chromeArgs: string[], config?: BrowserLaunchConfig): BrowserLaunchFingerprint;
 /** Test-only export for launch-argument/capture-mode agreement. */
 export declare const _createBrowserLaunchFingerprintForTests: typeof createBrowserLaunchFingerprint;
-export declare function acquireBrowser(chromeArgs: string[], config?: Partial<Pick<EngineConfig, "browserTimeout" | "protocolTimeout" | "enableBrowserPool" | "chromePath" | "forceScreenshot">>): Promise<AcquiredBrowser>;
+export declare function acquireBrowser(chromeArgs: string[], config?: BrowserLaunchConfig & Partial<Pick<EngineConfig, "enableBrowserPool">>): Promise<AcquiredBrowser>;
 export declare function releaseBrowser(browser: Browser, _config?: Partial<Pick<EngineConfig, "enableBrowserPool">>): Promise<void>;
 export declare function forceReleaseBrowser(browser: Browser): void;
 /**

package/dist/services/browserManager.js

@@ -13,7 +13,7 @@ import { homedir } from "os";
 import { chromeMajorCeiling, exceedsChromeCeiling } from "./chromeHostCeiling.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
-import { describeWslGpuAccess } from "./wslHost.js";
+import { describeWslGpuAccess, detectWsl } from "./wslHost.js";
 import { BrowserLeasePool, } from "./browserLeasePool.js";
 export { BrowserLeasePool } from "./browserLeasePool.js";
 let _puppeteer;
@@ -58,6 +58,7 @@ async function probeHardwareWebGlInfo(ppt, options) {
             args: options.args,
             defaultViewport: { width: 64, height: 64 },
             executablePath: options.executablePath,
+            env: options.env,
             timeout: options.browserTimeout,
             waitForInitialPage: false,
         };
@@ -199,6 +200,30 @@ export function resolveHeadlessShellPath(config) {
     const home = homedir();
     return (findCachedHeadlessShell(join(home, ".cache", "hyperframes", "chrome", "chrome-headless-shell")) ?? findCachedHeadlessShell(join(home, ".cache", "puppeteer", "chrome-headless-shell")));
 }
+/** Full Chrome for Testing in Puppeteer's cache (`@puppeteer/browsers install chrome@...`), newest first. */
+export function resolveFullChromePath() {
+    const baseDir = join(homedir(), ".cache", "puppeteer", "chrome");
+    let versions;
+    try {
+        versions = readdirSync(baseDir).sort(compareBrowserVersionsDescending);
+    }
+    catch {
+        return undefined;
+    }
+    for (const version of versions) {
+        const candidates = [
+            join(baseDir, version, "chrome-mac-arm64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+            join(baseDir, version, "chrome-mac-x64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
+            join(baseDir, version, "chrome-linux64", "chrome"),
+            join(baseDir, version, "chrome-win64", "chrome.exe"),
+        ];
+        for (const binary of candidates) {
+            if (existsSync(binary))
+                return binary;
+        }
+    }
+    return undefined;
+}
 // Preserve the producer-era export so re-export shims keep the same public API.
 export const ENABLE_BROWSER_POOL = DEFAULT_CONFIG.enableBrowserPool;
 // Flags only meaningful when Chrome's compositor is driven by
@@ -403,32 +428,51 @@ function formatProbeFailure(err) {
     return `probe failed (${err instanceof Error ? err.message : String(err)})`;
 }
 async function probeAutoBrowserGpuMode(options) {
-    const platform = options.platform ?? process.platform;
-    const browserTimeout = options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout;
-    const executablePath = options.chromePath ?? resolveHeadlessShellPath({});
     const ppt = await getPuppeteerOrNull();
     if (ppt === null) {
         logResolvedBrowserGpuMode("software", "puppeteer unavailable");
         return { mode: "software", cause: "probe-error" };
     }
+    const probed = await probeWebGlMode(ppt, options);
+    if (probed.mode === "hardware")
+        return probed;
+    // Chrome 150+ uses WSLg Wayland EGL, which lacks offscreen configs: https://issues.chromium.org/issues/567222741
+    if (detectWsl(options.wslHost) && process.env.WAYLAND_DISPLAY !== undefined) {
+        const env = envWithoutWaylandDisplay();
+        const retried = await probeWebGlMode(ppt, options, env, "without WAYLAND_DISPLAY: ");
+        if (retried.mode === "hardware")
+            return { mode: "hardware", withoutWaylandDisplay: true };
+    }
+    return { ...probed, ...wslAccess(options) };
+}
+async function probeWebGlMode(ppt, options, env, label = "") {
     try {
         const info = await probeHardwareWebGlInfo(ppt, {
-            args: getHardwareGpuProbeArgs(platform),
-            browserTimeout,
-            executablePath,
+            args: getHardwareGpuProbeArgs(options.platform ?? process.platform),
+            browserTimeout: options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout,
+            executablePath: options.chromePath ?? resolveHeadlessShellPath({}),
             probeLifecycle: options.probeLifecycle,
+            env,
         });
         const resolved = resolveWebGlProbeMode(info);
-        logResolvedBrowserGpuMode(resolved, describeWebGlProbe(info));
-        if (resolved === "hardware")
-            return { mode: "hardware" };
-        return { mode: "software", cause: "no-gpu", ...wslAccess(options) };
+        logResolvedBrowserGpuMode(resolved, label + describeWebGlProbe(info));
+        return resolved === "hardware" ? { mode: "hardware" } : { mode: "software", cause: "no-gpu" };
     }
     catch (err) {
-        logResolvedBrowserGpuMode("software", formatProbeFailure(err));
-        return { mode: "software", cause: "probe-error", ...wslAccess(options) };
+        logResolvedBrowserGpuMode("software", label + formatProbeFailure(err));
+        return { mode: "software", cause: "probe-error" };
     }
 }
+function envWithoutWaylandDisplay() {
+    const { WAYLAND_DISPLAY: _wslg, ...env } = process.env;
+    return env;
+}
+/** True when a `resolvedMode` render must launch without WAYLAND_DISPLAY to reach the GPU. */
+export async function captureWithoutWaylandDisplay(resolvedMode) {
+    if (resolvedMode !== "hardware")
+        return false;
+    return (await _autoBrowserGpuModeCache)?.withoutWaylandDisplay === true;
+}
 function wslAccess(options) {
     const lines = describeWslGpuAccess(options.wslHost);
     return lines ? { wslAccess: lines } : {};
@@ -575,6 +619,7 @@ function createBrowserLaunchFingerprint(chromeArgs, config) {
     return {
         args: chromeArgs,
         executablePath: headlessShell,
+        withoutWaylandDisplay: launchConfig.withoutWaylandDisplay === true,
         browserTimeoutMs: launchConfig.browserTimeout,
         protocolTimeoutMs: launchConfig.protocolTimeout,
         requestedCaptureMode,
@@ -589,6 +634,7 @@ export async function acquireBrowser(chromeArgs, config) {
 // fallow-ignore-next-line complexity
 async function launchBrowser(fingerprint) {
     const ppt = await getPuppeteer();
+    const env = fingerprint.withoutWaylandDisplay ? envWithoutWaylandDisplay() : undefined;
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
     try {
@@ -598,6 +644,7 @@ async function launchBrowser(fingerprint) {
             args: [...fingerprint.args],
             defaultViewport: null,
             executablePath: fingerprint.executablePath,
+            env,
             timeout: fingerprint.browserTimeoutMs,
             protocolTimeout: fingerprint.protocolTimeoutMs,
         });
@@ -622,6 +669,7 @@ async function launchBrowser(fingerprint) {
                     args: stripBeginFrameFlags([...fingerprint.args]),
                     defaultViewport: null,
                     executablePath: fingerprint.executablePath,
+                    env,
                     timeout: fingerprint.browserTimeoutMs,
                     protocolTimeout: fingerprint.protocolTimeoutMs,
                 });

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-v6-";
+export declare const SCHEMA_PREFIX = "hfcache-v7-";
 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-v6-";
+export const SCHEMA_PREFIX = "hfcache-v7-";
 /** 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.js

@@ -15,7 +15,7 @@ import { DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
 import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
-import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
+import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
 import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
 import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
 import { initThreeDProjection, detectCssEffectRisk } from "./threeDProjection.js";
@@ -804,7 +804,8 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
             .catch(() => false));
     const gpuConfig = { ...config, browserGpuMode: resolvedGpuMode };
     const chromeArgs = buildChromeArgs({ width: options.width, height: options.height, captureMode: preMode, requiresWebGpu }, gpuConfig);
-    const browserLease = await acquireBrowser(chromeArgs, config);
+    const withoutWaylandDisplay = await captureWithoutWaylandDisplay(resolvedGpuMode);
+    const browserLease = await acquireBrowser(chromeArgs, { ...config, withoutWaylandDisplay });
     return constructCaptureSessionWithRollback({
         browserLease,
         serverUrl,

package/dist/services/hdrCapture.js

@@ -18,10 +18,7 @@
  *
  * Performance: ~6 fps at 1080x1920 via base64 transfer.
  */
-import { existsSync, readdirSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-import { sigintLaunchOptions } from "./browserManager.js";
+import { resolveFullChromePath, sigintLaunchOptions } from "./browserManager.js";
 // ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
 const PQ_M1 = 0.1593017578125;
 const PQ_M2 = 78.84375;
@@ -159,25 +156,6 @@ export function float16ToPqRgb(rawBuffer, bytesPerRow, width, height) {
     return output;
 }
 // ── Chrome launch ─────────────────────────────────────────────────────────────
-function resolveHeadedChromePath() {
-    const baseDir = join(homedir(), ".cache", "puppeteer", "chrome");
-    if (!existsSync(baseDir))
-        return undefined;
-    const versions = readdirSync(baseDir).sort().reverse();
-    for (const version of versions) {
-        const candidates = [
-            join(baseDir, version, "chrome-mac-arm64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
-            join(baseDir, version, "chrome-mac-x64", "Google Chrome for Testing.app", "Contents", "MacOS", "Google Chrome for Testing"),
-            join(baseDir, version, "chrome-linux64", "chrome"),
-            join(baseDir, version, "chrome-win64", "chrome.exe"),
-        ];
-        for (const binary of candidates) {
-            if (existsSync(binary))
-                return binary;
-        }
-    }
-    return undefined;
-}
 /**
  * Launch a headed Chrome browser with WebGPU enabled.
  */
@@ -197,7 +175,7 @@ export async function launchHdrBrowser(width, height) {
     }
     if (!ppt)
         throw new Error("Neither puppeteer nor puppeteer-core found");
-    const chromePath = resolveHeadedChromePath();
+    const chromePath = resolveFullChromePath();
     if (!chromePath) {
         throw new Error("[HDR] No Chrome binary found. Install: npx @puppeteer/browsers install chrome@stable");
     }

package/dist/services/videoFrameExtractor.d.ts

@@ -53,9 +53,9 @@ export declare function isVideoFrameFormat(value: unknown): value is VideoFrameF
 /**
  * Resolve the frame count produced for a requested extraction duration.
  *
- * CFR extraction uses FFmpeg's fps filter, whose end boundary rounds to the
- * nearest frame. The VFR path normalizes with `-fps_mode cfr -r`, whose end
- * boundary rounds up. Keep this calculation shared by superset slicing and
+ * Both paths sample with FFmpeg's fps filter. A CFR window ends at the nearest
+ * frame boundary; a VFR window rounds up, keeping the slot a trailing still
+ * covers. Keep this calculation shared by superset slicing and
  * producer coverage accounting so a complete VFR extraction cannot be
  * rejected because the two paths disagree by one frame.
  */
@@ -123,8 +123,8 @@ export declare const EXTRACT_CACHE_MIN_AGE_MS: number;
  *     reflects max-across-parallel-workers, not sum.
  *   - hdrPreflightMs includes its probe-time sibling (hdrProbeMs); the
  *     probe-only field is a finer decomposition, not a separate carve-out.
- *   - vfrPreflightCount reports sources classified as VFR and routed through
- *     the one-pass `-fps_mode cfr -r` extraction path. DEFINITION CHANGE:
+ *   - vfrPreflightCount reports sources classified as VFR and extracted with
+ *     a rounded-up frame count. DEFINITION CHANGE:
  *     before the one-pass refactor, vfrPreflightMs timed a per-source
  *     VFR-to-CFR re-encode and could reach seconds; it now times only the
  *     (promise-cached) classification probe and is expected to be ~0.

package/dist/services/videoFrameExtractor.js

@@ -20,7 +20,7 @@ import { extractFinalVideoFrameTimestamp, extractMediaMetadata, } from "../utils
 import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPlaneProbe.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
 import { downloadToTemp, isHttpUrl, safeDownloadUrlIdentity, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
-import { runFfmpeg, runFfmpegPipeline } from "../utils/runFfmpeg.js";
+import { runFfmpeg } from "../utils/runFfmpeg.js";
 import { isFfmpegFilterAvailable } from "../utils/psnrFilterAvailability.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
@@ -41,9 +41,9 @@ export function isVideoFrameFormat(value) {
 /**
  * Resolve the frame count produced for a requested extraction duration.
  *
- * CFR extraction uses FFmpeg's fps filter, whose end boundary rounds to the
- * nearest frame. The VFR path normalizes with `-fps_mode cfr -r`, whose end
- * boundary rounds up. Keep this calculation shared by superset slicing and
+ * Both paths sample with FFmpeg's fps filter. A CFR window ends at the nearest
+ * frame boundary; a VFR window rounds up, keeping the slot a trailing still
+ * covers. Keep this calculation shared by superset slicing and
  * producer coverage accounting so a complete VFR extraction cannot be
  * rejected because the two paths disagree by one frame.
  */
@@ -430,59 +430,6 @@ function chromeGuessForUntaggedMatrix(metadata) {
     const hd = metadata.height >= 720 && !CHROME_BT601_UNTAGGED_CODECS.has(metadata.videoCodec);
     return [`setparams=colorspace=${hd ? "bt709" : "smpte170m"}`];
 }
-/** Pixel formats nut carries as raw video unchanged on ffmpeg 5.1 to 8.1 (yuvj only loses its range). */
-const NUT_RAW_PIXEL_FORMATS = new Set([
-    "yuv420p",
-    "yuvj420p",
-    "yuv422p",
-    "yuvj422p",
-    "yuv444p",
-    "yuvj444p",
-    "yuva420p",
-    "yuva444p",
-    "yuv440p",
-    "yuv411p",
-    "yuv410p",
-    "yuva422p",
-    "yuv420p10le",
-    "yuv422p10le",
-    "yuv444p10le",
-    "yuva420p10le",
-    "yuva444p10le",
-    "yuv420p12le",
-    "nv12",
-    "nv21",
-    "yuyv422",
-    "uyvy422",
-    "gray",
-    "gray10le",
-    "ya8",
-    "gbrp",
-    "gbrap",
-    "gbrp10le",
-    "gbrp12le",
-    "gbrap10le",
-    "rgb24",
-    "bgr24",
-    "rgba",
-    "bgra",
-    "argb",
-    "abgr",
-    "rgb48le",
-    "rgba64le",
-]);
-/** nut drops colour tags, so raw frames get the source's back before any other filter reads them. */
-function restoreSourceColourFilter(metadata) {
-    const tags = [
-        ["range", metadata.colorRange],
-        ["colorspace", metadata.colorSpace?.colorSpace],
-        ["color_primaries", metadata.colorSpace?.colorPrimaries],
-        ["color_trc", metadata.colorSpace?.colorTransfer],
-    ].filter(([, value]) => value && value !== "unknown" && value !== "reserved");
-    return tags.length > 0
-        ? [`setparams=${tags.map(([key, value]) => `${key}=${value}`).join(":")}`]
-        : [];
-}
 /**
  * Longest stretch of output one ffmpeg process extracts. `ffmpegProcessTimeout` bounds a
  * single process, so one process over a long clip timed out however much time the render
@@ -595,8 +542,8 @@ outputDirOverride) {
     const isMacOS = process.platform === "darwin";
     const toneMappedToSdr = options.toneMapHdrToSdr === true && isHdr && (await toneMapsWithZscale());
     const decodeWithVideoToolbox = isHdr && isMacOS && !toneMappedToSdr;
-    const sampleCfrAtOutputFps = !options.finalFrameOnly && !metadata.isVFR;
-    if (options.frameRanges && !sampleCfrAtOutputFps) {
+    const sampleAtOutputFps = !options.finalFrameOnly;
+    if (options.frameRanges && (!sampleAtOutputFps || metadata.isVFR)) {
         throw new Error("frameRanges extraction needs a constant-frame-rate source");
     }
     const args = [];
@@ -625,7 +572,7 @@ outputDirOverride) {
     }
     else {
         // An accurate seek drops the frame on screen at startTime; the fps sampling below needs it.
-        if (sampleCfrAtOutputFps)
+        if (sampleAtOutputFps)
             args.push("-noaccurate_seek");
         args.push("-ss", String(startTime), "-i", videoPath, "-t", String(duration));
     }
@@ -633,7 +580,7 @@ outputDirOverride) {
     if (decodeWithVideoToolbox) {
         vfFilters.push("format=nv12");
     }
-    if (sampleCfrAtOutputFps) {
+    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`);
@@ -663,45 +610,24 @@ outputDirOverride) {
         encodeArgs.push("-compression_level", "1");
     encodeArgs.push("-y", outputPattern);
     const runOptions = { signal, timeout: ffmpegProcessTimeout };
-    const resampleVfrToCfr = !options.finalFrameOnly && metadata.isVFR;
-    if (resampleVfrToCfr)
-        args.push("-fps_mode", "cfr", "-r", ffmpegFps);
-    let processResult;
-    if (resampleVfrToCfr &&
-        vfFilters.length > 0 &&
-        !isHdr &&
-        NUT_RAW_PIXEL_FORMATS.has(metadata.pixelFormat ?? "")) {
-        // ffmpeg <6.1 ignores frame durations in CFR resampling once any -vf is set,
-        // cutting a trailing still short, so the SDR filters run in a second process.
-        processResult = await inExtractionSlot(() => runFfmpegPipeline([...args, "-an", "-sn", "-dn", "-c:v", "rawvideo", "-f", "nut", "pipe:1"], [
-            "-f",
-            "nut",
-            "-i",
-            "pipe:0",
-            "-vf",
-            [...restoreSourceColourFilter(metadata), ...vfFilters].join(","),
-            "-fps_mode",
-            "passthrough",
-            ...encodeArgs,
-        ], runOptions), signal);
-    }
-    else {
-        const filterArgs = vfFilters.length > 0 ? ["-vf", vfFilters.join(",")] : [];
-        const segmentFrames = Math.round(EXTRACTION_SEGMENT_SECONDS * fps);
-        const totalFrames = extractionFrameCountForDuration(duration, normalizedFps, false);
-        processResult =
-            sampleCfrAtOutputFps && (options.frameRanges || totalFrames > segmentFrames)
-                ? await runSegmentedExtraction({
-                    decodeArgs,
-                    filterAndEncodeArgs: [...filterArgs, ...encodeArgs],
-                    videoPath,
-                    startTime,
-                    fps,
-                    segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
-                    runOptions,
-                })
-                : await inExtractionSlot(() => runFfmpeg([...args, ...filterArgs, ...encodeArgs], runOptions), signal);
-    }
+    const filterArgs = vfFilters.length > 0 ? ["-vf", vfFilters.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
+    // 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 processResult = sampleAtOutputFps && (options.frameRanges || boundVfrFrameCount || totalFrames > segmentFrames)
+        ? await runSegmentedExtraction({
+            decodeArgs,
+            filterAndEncodeArgs: [...filterArgs, ...encodeArgs],
+            videoPath,
+            startTime,
+            fps,
+            segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
+            runOptions,
+        })
+        : await inExtractionSlot(() => runFfmpeg([...args, ...filterArgs, ...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)}`);
     }
@@ -1044,11 +970,8 @@ function buildSupersetGroup(groupId, misses, fps) {
         return null;
     if (misses.some(({ work }) => work.finalFrameOnly))
         return null;
-    // VFR normalization (`-fps_mode cfr -r`) establishes its duplicate/drop
-    // phase relative to each seek. A union extraction therefore cannot be
-    // sliced into the same frames as independently sought member ranges, even
-    // when their offsets land on an integral output-frame boundary. Keep VFR
-    // ranges direct until the extractor has a proven absolute timestamp phase.
+    // VFR ranges round their frame counts up, so a union extraction's slices
+    // are not proven to match independently sought member ranges. Keep them direct.
     if (misses.some(({ work }) => work.metadata.isVFR))
         return null;
     const baseStart = Math.min(...misses.map(({ work }) => work.video.mediaStart));

package/dist/utils/runFfmpeg.d.ts

@@ -50,8 +50,3 @@ export declare function formatFfmpegError(exitCode: number | null, stderr: strin
 /** formatFfmpegError, led by the timeout when this process was killed at its deadline. */
 export declare function describeFfmpegFailure(result: Pick<RunFfmpegResult, "exitCode" | "stderr" | "terminationReason">, timeoutMs: number): string;
 export declare function runFfmpeg(args: string[], opts?: RunFfmpegOptions): Promise<RunFfmpegResult>;
-/**
- * Runs `ffmpeg <producerArgs> | ffmpeg <consumerArgs>`. Fails when either side
- * fails and reports the first failure, its stderr last so error tails show it.
- */
-export declare function runFfmpegPipeline(producerArgs: string[], consumerArgs: string[], opts?: RunFfmpegOptions): Promise<RunFfmpegResult>;

package/dist/utils/runFfmpeg.js

@@ -149,38 +149,3 @@ export async function runFfmpeg(args, opts) {
     });
     return toResult(await managed.wait());
 }
-/**
- * Runs `ffmpeg <producerArgs> | ffmpeg <consumerArgs>`. Fails when either side
- * fails and reports the first failure, its stderr last so error tails show it.
- */
-export async function runFfmpegPipeline(producerArgs, consumerArgs, opts) {
-    if (opts?.signal?.aborted)
-        return { ...ABORTED_BEFORE_START };
-    const deadlineAtMs = Date.now() + (opts?.timeout ?? DEFAULT_TIMEOUT);
-    const producer = spawnFfmpeg(producerArgs);
-    const consumer = spawnFfmpeg(consumerArgs);
-    // Either side ending early, or failing to start, must release the other from the pipe.
-    consumer.stdin?.on("error", () => { });
-    for (const event of ["close", "error"]) {
-        consumer.once(event, () => producer.stdout?.destroy());
-        producer.once(event, () => consumer.stdin?.end());
-    }
-    if (consumer.stdin)
-        producer.stdout?.pipe(consumer.stdin);
-    const settleOrder = [];
-    const outcomes = await Promise.all([producer, consumer].map((child) => new ManagedChildProcess(child, {
-        signal: opts?.signal,
-        deadlineAtMs,
-        onStderr: opts?.onStderr,
-    })
-        .wait()
-        .then((outcome) => {
-        settleOrder.push(outcome);
-        return outcome;
-    })));
-    const reported = settleOrder.find((outcome) => !succeeded(outcome)) ?? outcomes[1];
-    const stderr = [...outcomes.filter((outcome) => outcome !== reported), reported]
-        .map((outcome) => outcome.stderr)
-        .join("");
-    return toResult(reported, stderr);
-}

package/package.json

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