@hyperframes/engine 0.8.153 → 0.8.155

package/dist/services/browserManager.d.ts

@@ -6,6 +6,7 @@
  */
 import type { Browser, LaunchOptions, Page, PuppeteerNode } from "puppeteer-core";
 import { type EngineConfig } from "../config.js";
+import { type WslHostFacts } from "./wslHost.js";
 import { type BrowserLaunchFingerprint, type BrowserLease, type CaptureMode } from "./browserLeasePool.js";
 export { BrowserLeasePool } from "./browserLeasePool.js";
 export type { BrowserLaunchFingerprint, BrowserLease, BrowserPoolState, CaptureMode, } from "./browserLeasePool.js";
@@ -23,6 +24,7 @@ interface GpuProbeOptions {
     browserTimeout?: number;
     platform?: NodeJS.Platform;
     probeLifecycle?: GpuProbeLifecycle;
+    wslHost?: WslHostFacts;
 }
 export type AcquiredBrowser = BrowserLease;
 /**

package/dist/services/browserManager.js

@@ -13,6 +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 { BrowserLeasePool, } from "./browserLeasePool.js";
 export { BrowserLeasePool } from "./browserLeasePool.js";
 let _puppeteer;
@@ -366,6 +367,7 @@ let _autoBrowserGpuModeCache;
 export function _resetAutoBrowserGpuModeCacheForTests() {
     _autoBrowserGpuModeCache = undefined;
     _unverifiedHardwareGpuWarned = false;
+    _wslSoftwareNoteLogged = false;
 }
 async function getPuppeteerOrNull() {
     try {
@@ -418,13 +420,19 @@ async function probeAutoBrowserGpuMode(options) {
         });
         const resolved = resolveWebGlProbeMode(info);
         logResolvedBrowserGpuMode(resolved, describeWebGlProbe(info));
-        return resolved === "hardware" ? { mode: "hardware" } : { mode: "software", cause: "no-gpu" };
+        if (resolved === "hardware")
+            return { mode: "hardware" };
+        return { mode: "software", cause: "no-gpu", ...wslAccess(options) };
     }
     catch (err) {
         logResolvedBrowserGpuMode("software", formatProbeFailure(err));
-        return { mode: "software", cause: "probe-error" };
+        return { mode: "software", cause: "probe-error", ...wslAccess(options) };
     }
 }
+function wslAccess(options) {
+    const lines = describeWslGpuAccess(options.wslHost);
+    return lines ? { wslAccess: lines } : {};
+}
 /**
  * Resolve `browserGpuMode` to a concrete `"software" | "hardware"` answer.
  *
@@ -455,15 +463,22 @@ export function resolveBrowserGpuMode(mode, options = {}) {
     if (mode === "software")
         return Promise.resolve(mode);
     _autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options);
-    if (mode === "auto")
-        return _autoBrowserGpuModeCache.then((probed) => probed.mode);
+    if (mode === "auto") {
+        return _autoBrowserGpuModeCache.then((probed) => {
+            if (probed.mode === "software" && probed.wslAccess && !_wslSoftwareNoteLogged) {
+                _wslSoftwareNoteLogged = true;
+                console.error(buildWslSoftwareNote(probed));
+            }
+            return probed.mode;
+        });
+    }
     return _autoBrowserGpuModeCache.then((probed) => {
         // Warn once per cache lifetime, not once per caller: `createCaptureSession`
         // resolves the mode for the probe browser AND every parallel worker, so
         // an un-deduplicated warning prints N+1 times and buries itself.
         if (probed.mode === "software" && !_unverifiedHardwareGpuWarned) {
             _unverifiedHardwareGpuWarned = true;
-            console.warn(buildUnverifiedHardwareGpuWarning(options.platform ?? process.platform, probed.cause));
+            console.warn(buildUnverifiedHardwareGpuWarning(options.platform ?? process.platform, probed));
         }
         return "hardware";
     });
@@ -473,6 +488,19 @@ export function resolveBrowserGpuMode(mode, options = {}) {
  * cache lifetime (re-armed by `_resetAutoBrowserGpuModeCacheForTests`).
  */
 let _unverifiedHardwareGpuWarned = false;
+let _wslSoftwareNoteLogged = false;
+/** Auto mode under WSL selected software: say so, with what we checked. */
+function buildWslSoftwareNote({ cause, wslAccess = [] }) {
+    const check = cause === "probe-error"
+        ? "the GPU check could not finish (see the probe line above)"
+        : "the GPU check found no hardware GPU";
+    return [
+        `[hyperframes] WSL: ${check}, so this render uses software WebGL (SwiftShader) and runs ` +
+            "at CPU speed.",
+        ...wslAccess,
+        "  Pass --no-browser-gpu to skip the GPU check and render in software.",
+    ].join("\n");
+}
 /**
  * Warning text for "you asked for hardware GPU and we could not confirm it".
  *
@@ -482,7 +510,7 @@ let _unverifiedHardwareGpuWarned = false;
  * at `--gpus all` would send them chasing a phantom while their Chrome
  * install is the actual fault.
  */
-function buildUnverifiedHardwareGpuWarning(platform, cause) {
+function buildUnverifiedHardwareGpuWarning(platform, { cause, wslAccess }) {
     if (cause === "probe-error") {
         return ("[hyperframes] browserGpuMode=hardware was requested, but the GPU probe could not run, " +
             "so hardware acceleration is UNVERIFIED. If Chrome falls back to software WebGL the " +
@@ -491,19 +519,25 @@ function buildUnverifiedHardwareGpuWarning(platform, cause) {
             "`browserGpuMode probe → software (probe failed ...)` line above for the underlying " +
             "error, which usually means Chrome could not launch (bad HYPERFRAMES_BROWSER_PATH, " +
             "missing shared libraries, or a denied sandbox) rather than a GPU problem.\n" +
-            "  Run `hyperframes doctor` to check the Chrome install.");
-    }
-    const remediation = platform === "linux"
-        ? "Inside Docker, the container needs GPU passthrough: `--gpus all` with the NVIDIA " +
-            "Container Toolkit installed, or `--device /dev/dri` for Mesa/AMD/Intel. The image " +
-            "also needs the matching userspace driver + libEGL. Verify with " +
-            "`hyperframes render --browser-gpu` and watch for this warning disappearing."
-        : "Check that the host exposes a GPU to this process and that the graphics drivers are " +
-            "installed.";
+            "  Run `hyperframes doctor` to check the Chrome install." +
+            (wslAccess
+                ? ["", "  Under WSL, a GPU path that is slow to start or unreachable can also cause it:"]
+                    .concat(wslAccess)
+                    .join("\n")
+                : ""));
+    }
+    const remediation = wslAccess?.join("\n") ??
+        (platform === "linux"
+            ? "  Inside Docker, the container needs GPU passthrough: `--gpus all` with the NVIDIA " +
+                "Container Toolkit installed, or `--device /dev/dri` for Mesa/AMD/Intel. The image " +
+                "also needs the matching userspace driver + libEGL. Verify with " +
+                "`hyperframes render --browser-gpu` and watch for this warning disappearing."
+            : "  Check that the host exposes a GPU to this process and that the graphics drivers " +
+                "are installed.");
     return ("[hyperframes] browserGpuMode=hardware was requested, but the WebGL probe found no " +
         "hardware GPU, so Chrome will silently fall back to software WebGL and the capture will " +
         "run at CPU speed. Honouring the explicit request anyway.\n" +
-        `  ${remediation}\n` +
+        `${remediation}\n` +
         "  Pass --no-browser-gpu to select deterministic SwiftShader instead of waiting on a " +
         "hardware path that is not there.");
 }

package/dist/services/parallelCoordinator.d.ts

@@ -76,12 +76,8 @@ export interface WorkerSizingConfig extends Partial<Pick<EngineConfig, "concurre
 }
 type WorkerBrowserPoolDecision = {
     parallel?: boolean;
-    platform: NodeJS.Platform;
-    forceScreenshot?: boolean;
-    deviceScaleFactor?: number;
-    headlessShellPath?: string;
 };
-export declare function shouldDisableBrowserPoolForParallelWorker({ parallel, platform, deviceScaleFactor, headlessShellPath, }: WorkerBrowserPoolDecision): boolean;
+export declare function shouldDisableBrowserPoolForParallelWorker({ parallel, }: WorkerBrowserPoolDecision): boolean;
 export declare function selectWorkerDiagnostics(lines: readonly string[], maxLines?: number): string[];
 /**
  * Expected frame count for a worker task, honoring its stride. Contiguous

package/dist/services/parallelCoordinator.js

@@ -51,12 +51,11 @@ function defaultSafeMaxWorkers() {
     return Math.max(6, Math.min(16, Math.floor(cpus().length / 8)));
 }
 const MIN_FRAMES_PER_WORKER = 30;
-// Linux/headless parallel workers need isolated browser processes: BeginFrame
-// crashes when shared, while forceScreenshot is safe but serializes
-// Page.captureScreenshot per browser. Supersampling keeps the existing path
-// until browser-pool compatibility is keyed by DPR.
-export function shouldDisableBrowserPoolForParallelWorker({ parallel, platform, deviceScaleFactor, headlessShellPath, }) {
-    return Boolean(parallel && platform === "linux" && headlessShellPath && (deviceScaleFactor ?? 1) <= 1);
+// Every parallel worker gets its own browser: pages in one browser share six
+// connections to the file server, which a media-heavy page holds (#5548), and
+// sharing also crashes BeginFrame and serializes screenshots.
+export function shouldDisableBrowserPoolForParallelWorker({ parallel, }) {
+    return Boolean(parallel);
 }
 export function selectWorkerDiagnostics(lines, maxLines = MAX_WORKER_DIAGNOSTIC_LINES) {
     return lines
@@ -555,13 +554,7 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
         mkdirSync(task.outputDir, { recursive: true });
     let session = null;
     let perf;
-    const needsSeparateBrowsers = shouldDisableBrowserPoolForParallelWorker({
-        parallel,
-        platform: process.platform,
-        forceScreenshot: config?.forceScreenshot,
-        deviceScaleFactor: captureOptions.deviceScaleFactor,
-        headlessShellPath: resolveHeadlessShellPath(config),
-    });
+    const needsSeparateBrowsers = shouldDisableBrowserPoolForParallelWorker({ parallel });
     const workerConfig = needsSeparateBrowsers
         ? { ...config, enableBrowserPool: false }
         : config;

package/dist/services/videoFrameExtractor.js

@@ -114,7 +114,7 @@ const SDR_TO_HDR_COLORSPACE_FILTER = "colorspace=all=bt2020:iall=bt709:range=tv"
 const HDR_TO_SDR_ZSCALE_TRANSFORM_KEY = "hdr2sdr-hable-srgb";
 const HDR_TO_SDR_VIDEOTOOLBOX_TRANSFORM_KEY = "hdr2sdr-videotoolbox-hdr";
 const SDR_CANVAS_PASSTHROUGH_FILTER = "setparams=color_primaries=bt709:color_trc=iec61966-2-1";
-const SDR_JPEG_AS_BT601_FULL_RANGE_FILTER = "scale=flags=neighbor,format=gbrp,scale=out_color_matrix=bt601:out_range=pc:flags=neighbor,format=yuv420p";
+const SDR_JPEG_AS_BT601_FULL_RANGE_FILTER = "scale=flags=neighbor+accurate_rnd,format=gbrp,scale=out_color_matrix=bt601:out_range=pc:flags=neighbor,format=yuv420p";
 let warnedMissingZscale = false;
 async function toneMapsWithZscale() {
     return process.platform !== "darwin" || isFfmpegFilterAvailable("zscale");

package/dist/services/wslHost.d.ts

@@ -0,0 +1,24 @@
+/**
+ * WSL host detection and what we can check about its GPU path when Chrome's
+ * GPU probe does not confirm a hardware GPU (heygen-com/hyperframes#5548).
+ */
+export type RenderNodeAccess = {
+    state: "missing" | "read-write";
+} | {
+    state: "denied";
+    group: string;
+    userInGroup: boolean;
+};
+/** The host facts these checks read; tests pass a fake. */
+export interface WslHostFacts {
+    platform: NodeJS.Platform;
+    release: string;
+    readProcVersion(): string;
+    renderNodeAccess(path: string): RenderNodeAccess;
+}
+export declare function detectWsl(host?: WslHostFacts): boolean;
+/**
+ * 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;

package/dist/services/wslHost.js

@@ -0,0 +1,89 @@
+/**
+ * WSL host detection and what we can check about its GPU path when Chrome's
+ * GPU probe does not confirm a hardware GPU (heygen-com/hyperframes#5548).
+ */
+import { accessSync, constants, existsSync, readFileSync, statSync } from "node:fs";
+import { platform, release } from "node:os";
+function groupName(gid) {
+    try {
+        const line = readFileSync("/etc/group", "utf-8")
+            .split("\n")
+            .find((entry) => entry.split(":")[2] === String(gid));
+        return line?.split(":")[0] || String(gid);
+    }
+    catch {
+        return String(gid);
+    }
+}
+const realHost = {
+    get platform() {
+        return platform();
+    },
+    get release() {
+        return release();
+    },
+    readProcVersion: () => readFileSync("/proc/version", "utf-8"),
+    renderNodeAccess: (path) => {
+        if (!existsSync(path))
+            return { state: "missing" };
+        try {
+            accessSync(path, constants.R_OK | constants.W_OK);
+            return { state: "read-write" };
+        }
+        catch {
+            const gid = statSync(path, { throwIfNoEntry: false })?.gid ?? -1;
+            return {
+                state: "denied",
+                group: groupName(gid),
+                userInGroup: process.getgroups?.().includes(gid) ?? false,
+            };
+        }
+    },
+};
+export function detectWsl(host = realHost) {
+    if (host.platform !== "linux")
+        return false;
+    try {
+        const osRelease = host.release.toLowerCase();
+        if (osRelease.includes("microsoft") || osRelease.includes("wsl"))
+            return true;
+        const procVersion = host.readProcVersion().toLowerCase();
+        return procVersion.includes("microsoft") || procVersion.includes("wsl");
+    }
+    catch {
+        return false;
+    }
+}
+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.";
+/**
+ * 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) {
+    if (!detectWsl(host))
+        return null;
+    const access = host.renderNodeAccess(RENDER_NODE);
+    if (access.state === "denied" && !access.userInGroup) {
+        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}`,
+        ];
+    }
+    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}`,
+        ];
+    }
+    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}`,
+    ];
+}

package/dist/utils/sdrCaptureColor.d.ts

@@ -1,3 +1,3 @@
 export declare const SDR_RGB_TO_BT709_FILTER = "scale=out_color_matrix=bt709:out_range=tv:flags=neighbor";
-export declare const SDR_CAPTURE_TO_BT709_FILTER = "scale=in_color_matrix=bt601:in_range=pc:flags=neighbor,format=gbrp,scale=out_color_matrix=bt709:out_range=tv:flags=neighbor";
+export declare const SDR_CAPTURE_TO_BT709_FILTER = "scale=in_color_matrix=bt601:in_range=pc:flags=neighbor+accurate_rnd,format=gbrp,scale=out_color_matrix=bt709:out_range=tv:flags=neighbor";
 export declare const SDR_RGB_TO_TAGGED_BT709_FILTER = "scale=out_color_matrix=bt709:out_range=tv:flags=neighbor,setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv";

package/dist/utils/sdrCaptureColor.js

@@ -1,3 +1,3 @@
 export const SDR_RGB_TO_BT709_FILTER = "scale=out_color_matrix=bt709:out_range=tv:flags=neighbor";
-export const SDR_CAPTURE_TO_BT709_FILTER = `scale=in_color_matrix=bt601:in_range=pc:flags=neighbor,format=gbrp,${SDR_RGB_TO_BT709_FILTER}`;
+export const SDR_CAPTURE_TO_BT709_FILTER = `scale=in_color_matrix=bt601:in_range=pc:flags=neighbor+accurate_rnd,format=gbrp,${SDR_RGB_TO_BT709_FILTER}`;
 export const SDR_RGB_TO_TAGGED_BT709_FILTER = `${SDR_RGB_TO_BT709_FILTER},setparams=color_primaries=bt709:color_trc=bt709:colorspace=bt709:range=tv`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.153",
+  "version": "0.8.155",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -31,6 +31,10 @@
       "import": "./dist/services/systemMemory.js",
       "types": "./dist/services/systemMemory.d.ts"
     },
+    "./wsl-host": {
+      "import": "./dist/services/wslHost.js",
+      "types": "./dist/services/wslHost.d.ts"
+    },
     "./shader-transitions": {
       "import": "./dist/utils/shaderTransitions.js",
       "types": "./dist/utils/shaderTransitions.d.ts"
@@ -46,8 +50,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.153",
-    "@hyperframes/parsers": "^0.8.153"
+    "@hyperframes/core": "^0.8.155",
+    "@hyperframes/parsers": "^0.8.155"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",