@hyperframes/engine 0.8.155 → 0.8.156

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/browserManager.d.ts

@@ -25,6 +25,8 @@ interface GpuProbeOptions {
     platform?: NodeJS.Platform;
     probeLifecycle?: GpuProbeLifecycle;
     wslHost?: WslHostFacts;
+    /** Finds full Chrome for the WSL fallback; tests pass a fake. */
+    findFullChrome?: () => string | undefined;
 }
 export type AcquiredBrowser = BrowserLease;
 /**
@@ -33,6 +35,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 +59,11 @@ export declare const _probeBeginFrameSupportForTests: typeof probeBeginFrameSupp
 export declare const _closeBrowserAfterFailedProbeForTests: typeof closeBrowserAfterFailedProbe;
 /** Test-only: reset the cached probe result. */
 export declare function _resetAutoBrowserGpuModeCacheForTests(): void;
+/**
+ * The browser a render launches for `resolvedMode`: under WSL, the full Chrome
+ * the GPU probe fell back to; otherwise the headless shell.
+ */
+export declare function resolveCaptureBrowserPath(resolvedMode: "software" | "hardware", config?: Partial<Pick<EngineConfig, "chromePath">>): Promise<string | undefined>;
 /**
  * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
  *

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;
@@ -199,6 +199,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,35 +427,56 @@ 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, executablePath, options);
+    if (probed.mode === "hardware" || !detectWsl(options.wslHost))
+        return probed;
+    return probeWslFullChrome(ppt, executablePath, options, probed);
+}
+// heygen-com/hyperframes#5548: under WSL, chrome-headless-shell can fail EGL
+// setup on Mesa's D3D12 driver while full Chrome (--headless=new) gets the GPU.
+async function probeWslFullChrome(ppt, shellPath, options, shellOutcome) {
+    const fullChrome = (options.findFullChrome ?? resolveFullChromePath)();
+    let route = { state: "missing" };
+    if (fullChrome) {
+        const viaFullChrome = fullChrome === shellPath
+            ? shellOutcome
+            : await probeWebGlMode(ppt, fullChrome, options, "full Chrome: ");
+        if (viaFullChrome.mode === "hardware")
+            return { mode: "hardware", browserPath: fullChrome };
+        route = { state: viaFullChrome.cause ?? "no-gpu", path: fullChrome };
+    }
+    return { ...shellOutcome, wslAccess: describeWslGpuAccess(options.wslHost, route) ?? undefined };
+}
+async function probeWebGlMode(ppt, executablePath, options, label = "") {
     try {
         const info = await probeHardwareWebGlInfo(ppt, {
-            args: getHardwareGpuProbeArgs(platform),
-            browserTimeout,
+            args: getHardwareGpuProbeArgs(options.platform ?? process.platform),
+            browserTimeout: options.browserTimeout ?? DEFAULT_CONFIG.browserTimeout,
             executablePath,
             probeLifecycle: options.probeLifecycle,
         });
         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 wslAccess(options) {
-    const lines = describeWslGpuAccess(options.wslHost);
-    return lines ? { wslAccess: lines } : {};
+/**
+ * The browser a render launches for `resolvedMode`: under WSL, the full Chrome
+ * the GPU probe fell back to; otherwise the headless shell.
+ */
+export async function resolveCaptureBrowserPath(resolvedMode, config) {
+    const probed = resolvedMode === "hardware" ? await _autoBrowserGpuModeCache : undefined;
+    return probed?.browserPath ?? resolveHeadlessShellPath(config);
 }
 /**
  * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.

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, resolveCaptureBrowserPath, 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";
@@ -786,7 +786,10 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
     // boolean `forceScreenshot === false` is otherwise ambiguous between
     // default and explicit opt-out).
     const effectiveForceScreenshot = applyConcreteGpuScreenshotClamp(forceScreenshot, resolvedGpuMode, config);
+    const browserPath = await resolveCaptureBrowserPath(resolvedGpuMode, config);
+    const wslFullChromeHasNoBeginFrame = browserPath !== headlessShell;
     const preMode = headlessShell &&
+        !wslFullChromeHasNoBeginFrame &&
         isLinux &&
         !effectiveForceScreenshot &&
         !supersampling &&
@@ -804,7 +807,7 @@ 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 browserLease = await acquireBrowser(chromeArgs, { ...config, chromePath: browserPath });
     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/services/wslHost.d.ts

@@ -17,8 +17,14 @@ export interface WslHostFacts {
     renderNodeAccess(path: string): RenderNodeAccess;
 }
 export declare function detectWsl(host?: WslHostFacts): boolean;
+export type FullChromeRoute = {
+    state: "missing";
+} | {
+    state: "no-gpu" | "probe-error";
+    path: string;
+};
 /**
  * Indented lines saying what we checked on the WSL GPU path and what to try,
  * or null outside WSL. Says nothing about the render mode: callers own that.
  */
-export declare function describeWslGpuAccess(host?: WslHostFacts): string[] | null;
+export declare function describeWslGpuAccess(host?: WslHostFacts, fullChrome?: FullChromeRoute): string[] | null;

package/dist/services/wslHost.js

@@ -57,11 +57,24 @@ export function detectWsl(host = realHost) {
 const RENDER_NODE = "/dev/dri/renderD128";
 const NATIVE_WINDOWS = "render from native Windows (project copied to a Windows drive, run from PowerShell), " +
     "where Chrome uses the GPU through Direct3D.";
+function routeToGpu(fullChrome) {
+    const viaFullChrome = fullChrome.state === "missing"
+        ? [
+            "  Under WSL, Chrome's headless shell often cannot reach the GPU while full Chrome can. " +
+                "Install full Chrome with `npx @puppeteer/browsers install chrome@stable --path " +
+                "~/.cache/puppeteer` and HyperFrames will try it when the headless shell finds no GPU " +
+                "(or point HYPERFRAMES_BROWSER_PATH at a full Chrome).",
+        ]
+        : fullChrome.state === "no-gpu"
+            ? [`  Full Chrome (${fullChrome.path}) found no hardware GPU either.`]
+            : [`  Full Chrome (${fullChrome.path}) could not finish its GPU check either.`];
+    return [...viaFullChrome, `  Or ${NATIVE_WINDOWS}`];
+}
 /**
  * Indented lines saying what we checked on the WSL GPU path and what to try,
  * or null outside WSL. Says nothing about the render mode: callers own that.
  */
-export function describeWslGpuAccess(host = realHost) {
+export function describeWslGpuAccess(host = realHost, fullChrome = { state: "missing" }) {
     if (!detectWsl(host))
         return null;
     const access = host.renderNodeAccess(RENDER_NODE);
@@ -69,21 +82,21 @@ export function describeWslGpuAccess(host = realHost) {
         return [
             `  Your Linux user cannot read and write ${RENDER_NODE} and is not in its group ` +
                 `("${access.group}"), which can stop Mesa from reaching the GPU.`,
-            `  Fix: run \`sudo usermod -aG ${access.group} $USER\`, then \`wsl --shutdown\` from ` +
-                "Windows, reopen WSL and render again.",
-            `  Or ${NATIVE_WINDOWS}`,
+            `  First run \`sudo usermod -aG ${access.group} $USER\`, then \`wsl --shutdown\` from ` +
+                "Windows and reopen WSL. On its own that may not be enough:",
+            ...routeToGpu(fullChrome),
         ];
     }
     if (access.state === "denied") {
         return [
             `  Your Linux user is in the "${access.group}" group but still cannot read and write ` +
                 `${RENDER_NODE}; check its permissions with \`ls -l ${RENDER_NODE}\`.`,
-            `  Or ${NATIVE_WINDOWS}`,
+            ...routeToGpu(fullChrome),
         ];
     }
     const seen = access.state === "missing" ? "does not exist" : "is readable and writable";
     return [
         `  ${RENDER_NODE} ${seen}, so file permissions are not the cause.`,
-        `  To use the GPU, ${NATIVE_WINDOWS}`,
+        ...routeToGpu(fullChrome),
     ];
 }

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.156",
   "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.156",
+    "@hyperframes/core": "^0.8.156"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",