Skip to content

Commit 96e2154

Browse files
fix(engine): say why WSL renders fall back to software and how to get the GPU (#5560)
* fix(engine): say why WSL renders fall back to software and how to get the GPU Under WSL the GPU check often falls back to SwiftShader and the only output was the probe line, with Docker passthrough advice for --browser-gpu. Print one note that says what was checked (can this user open the render node), the exact fix, and the native Windows alternative. The CLI's WSL detector moves to the engine so both use one. Part of #5548 * fix(engine): keep WSL GPU notes true to the probe result and render mode The WSL note now prints only when auto mode really selects software, and says whether the GPU check found no GPU or could not finish. Explicit --browser-gpu keeps its unverified and Chrome-install advice and adds the WSL checks. The render-node check verifies group membership before suggesting usermod.
1 parent 5de2712 commit 96e2154

10 files changed

Lines changed: 420 additions & 32 deletions

File tree

‎docs/guides/rendering.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,8 @@ npx hyperframes render --output final.mp4
159159
```
160160

161161
It starts quickly and can use the computer’s browser GPU.
162+
On WSL2, Chrome may not reach the GPU; see
163+
[the render is slow under WSL2](/guides/troubleshooting#the-render-is-slow-under-wsl2).
162164

163165
Use Docker when a controlled Chrome, FFmpeg, and font environment matters:
164166

‎docs/guides/troubleshooting.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -229,6 +229,36 @@ During iteration:
229229

230230
Run `npx hyperframes benchmark` when tuning worker settings.
231231

232+
### The render is slow under WSL2
233+
234+
WSL2 can expose a graphics card to Linux, but headless Chrome may not be able to use
235+
it. The render then falls back to software rendering, which can be several times
236+
slower on a long or effect-heavy video. The render log says so:
237+
238+
```text
239+
[hyperframes] browserGpuMode probe → software (WebGL unavailable)
240+
[hyperframes] WSL: the GPU check found no hardware GPU, so this render uses software WebGL ...
241+
```
242+
243+
The lines after it say what HyperFrames checked. If they say your user is not in
244+
the `render` group, add yourself, restart WSL, and render again:
245+
246+
```bash
247+
sudo usermod -aG render $USER
248+
# then, in Windows PowerShell:
249+
wsl --shutdown
250+
```
251+
252+
If the GPU is still not used, render from Windows instead. Copy the project to
253+
a Windows drive (for example `C:\Users\you\renders\my-video`) and run the same
254+
command from PowerShell, where Chrome uses the graphics card through Direct3D:
255+
256+
```powershell
257+
npx hyperframes render --output final.mp4
258+
```
259+
260+
Run it from a normal Windows folder, not a `\\wsl.localhost\...` path.
261+
232262
### Expected HDR but received SDR
233263

234264
HDR needs a supported output and correct source color metadata. MP4 is the normal HDR output path; WebM and MOV may fall back to SDR.
Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,5 @@
1-
import { platform, release } from "node:os";
2-
import { readFileSync } from "node:fs";
3-
41
// Shared host-platform detectors used by both system.ts (overall metadata)
52
// and agent_runtime.ts (sandbox fingerprinting). Lives in its own module
63
// to avoid an import cycle between those two files.
74

8-
export function detectWSL(): boolean {
9-
if (platform() !== "linux") return false;
10-
try {
11-
const osRelease = release().toLowerCase();
12-
if (osRelease.includes("microsoft") || osRelease.includes("wsl")) return true;
13-
const procVersion = readFileSync("/proc/version", "utf-8").toLowerCase();
14-
return procVersion.includes("microsoft") || procVersion.includes("wsl");
15-
} catch {
16-
return false;
17-
}
18-
}
5+
export { detectWsl as detectWSL } from "@hyperframes/engine/wsl-host";

‎packages/cli/tsup.config.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@ var __dirname = __hf_dirname(__filename);`,
101101
"./chrome-host-ceiling",
102102
"./shader-transitions",
103103
"./system-memory",
104+
"./wsl-host",
104105
]),
105106
};
106107
options.loader = { ...options.loader, ".browser.js": "text" };

‎packages/engine/package-subpaths.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,12 @@
2525
"types": "./dist/services/systemMemory.d.ts",
2626
"environments": ["bun", "node"]
2727
},
28+
"./wsl-host": {
29+
"source": "./src/services/wslHost.ts",
30+
"runtime": "./dist/services/wslHost.js",
31+
"types": "./dist/services/wslHost.d.ts",
32+
"environments": ["bun", "node"]
33+
},
2834
"./shader-transitions": {
2935
"source": "./src/utils/shaderTransitions.ts",
3036
"runtime": "./dist/utils/shaderTransitions.js",

‎packages/engine/package.json‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,11 @@
3535
"import": "./src/services/systemMemory.ts",
3636
"types": "./src/services/systemMemory.ts"
3737
},
38+
"./wsl-host": {
39+
"bun": "./src/services/wslHost.ts",
40+
"import": "./src/services/wslHost.ts",
41+
"types": "./src/services/wslHost.ts"
42+
},
3843
"./shader-transitions": {
3944
"bun": "./src/utils/shaderTransitions.ts",
4045
"import": "./src/utils/shaderTransitions.ts",
@@ -61,6 +66,10 @@
6166
"import": "./dist/services/systemMemory.js",
6267
"types": "./dist/services/systemMemory.d.ts"
6368
},
69+
"./wsl-host": {
70+
"import": "./dist/services/wslHost.js",
71+
"types": "./dist/services/wslHost.d.ts"
72+
},
6473
"./shader-transitions": {
6574
"import": "./dist/utils/shaderTransitions.js",
6675
"types": "./dist/utils/shaderTransitions.d.ts"

‎packages/engine/src/services/browserManager.test.ts‎

Lines changed: 128 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -369,6 +369,13 @@ describe("resolveBrowserGpuMode", () => {
369369
return { close, launch };
370370
};
371371

372+
const notWsl = {
373+
platform: "linux" as const,
374+
release: "6.8.0-45-generic",
375+
readProcVersion: () => "Linux version 6.8.0-45-generic",
376+
renderNodeAccess: () => ({ state: "read-write" as const }),
377+
};
378+
372379
beforeEach(() => {
373380
_resetAutoBrowserGpuModeCacheForTests();
374381
});
@@ -414,15 +421,15 @@ describe("resolveBrowserGpuMode", () => {
414421
renderer: "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device))",
415422
});
416423
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
417-
const mode = await resolveBrowserGpuMode("hardware", { platform: "linux" });
424+
const mode = await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost: notWsl });
418425
expect(mode).toBe("hardware");
419426
const warning = warn.mock.calls.map((call) => String(call[0])).join("\n");
420427
expect(warning).toContain("browserGpuMode=hardware was requested");
421428
expect(warning).toContain("--gpus all");
422429
// Once per process, not once per worker — the render path resolves the
423430
// mode for the probe browser plus every parallel worker.
424-
await resolveBrowserGpuMode("hardware", { platform: "linux" });
425-
await resolveBrowserGpuMode("hardware", { platform: "linux" });
431+
await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost: notWsl });
432+
await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost: notWsl });
426433
expect(warn).toHaveBeenCalledTimes(1);
427434
});
428435

@@ -440,7 +447,9 @@ describe("resolveBrowserGpuMode", () => {
440447
renderer: "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device))",
441448
});
442449
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
443-
expect(await resolveBrowserGpuMode("hardware", { platform: "darwin" })).toBe("hardware");
450+
expect(await resolveBrowserGpuMode("hardware", { platform: "darwin", wslHost: notWsl })).toBe(
451+
"hardware",
452+
);
444453
const warning = String(warn.mock.calls[0]?.[0]);
445454
expect(warning).toContain("host exposes a GPU");
446455
expect(warning).not.toContain("--gpus all");
@@ -454,13 +463,127 @@ describe("resolveBrowserGpuMode", () => {
454463
launch: vi.fn().mockRejectedValue(new Error("spawn ENOENT /bad/chrome")),
455464
} as unknown as PuppeteerNode);
456465
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
457-
expect(await resolveBrowserGpuMode("hardware", { platform: "linux" })).toBe("hardware");
466+
expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost: notWsl })).toBe(
467+
"hardware",
468+
);
458469
const warning = String(warn.mock.calls[0]?.[0]);
459470
expect(warning).toContain("GPU probe could not run");
460471
expect(warning).toContain("hyperframes doctor");
461472
expect(warning).not.toContain("--gpus all");
462473
});
463474

475+
describe("under WSL (heygen-com/hyperframes#5548)", () => {
476+
const wslHost = {
477+
platform: "linux" as const,
478+
release: "5.15.167.4-microsoft-standard-WSL2",
479+
readProcVersion: () => "",
480+
renderNodeAccess: () => ({ state: "denied" as const, group: "render", userInGroup: false }),
481+
};
482+
const output = (spy: { mock: { calls: unknown[][] } }) =>
483+
spy.mock.calls.map((call) => String(call[0])).join("\n");
484+
const neverAnsweringProbe = () => {
485+
const launch = vi.fn().mockResolvedValue({
486+
newPage: vi.fn().mockResolvedValue({ evaluate: () => new Promise(() => {}) }),
487+
close: () => new Promise(() => {}),
488+
process: () => ({ kill: vi.fn() }),
489+
disconnect: vi.fn().mockResolvedValue(undefined),
490+
});
491+
_setPuppeteerForTests({ launch } as unknown as PuppeteerNode);
492+
};
493+
494+
it("auto mode says it fell back to software, why, and the fix, once", async () => {
495+
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
496+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
497+
expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("software");
498+
await resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
499+
const text = output(error);
500+
expect(text).toContain("browserGpuMode probe → software (WebGL unavailable)");
501+
expect(text).toContain(
502+
"WSL: the GPU check found no hardware GPU, so this render uses software",
503+
);
504+
expect(text).toContain('is not in its group ("render")');
505+
expect(text).toContain("sudo usermod -aG render $USER");
506+
expect(text.match(/usermod/g)).toHaveLength(1);
507+
});
508+
509+
it("auto mode says the check did not finish when the probe page times out", async () => {
510+
vi.useFakeTimers();
511+
try {
512+
neverAnsweringProbe();
513+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
514+
const mode = resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
515+
await vi.advanceTimersByTimeAsync(15_000 + 250);
516+
await expect(mode).resolves.toBe("software");
517+
const text = output(error);
518+
expect(text).toContain("did not answer within 15000ms");
519+
expect(text).toContain("WSL: the GPU check could not finish");
520+
expect(text).not.toContain("found no hardware GPU");
521+
} finally {
522+
vi.useRealTimers();
523+
}
524+
});
525+
526+
it("explicit 'hardware' after a timeout stays unverified and never claims software", async () => {
527+
vi.useFakeTimers();
528+
try {
529+
neverAnsweringProbe();
530+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
531+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
532+
const mode = resolveBrowserGpuMode("hardware", { platform: "linux", wslHost });
533+
await vi.advanceTimersByTimeAsync(15_000 + 250);
534+
await expect(mode).resolves.toBe("hardware");
535+
const warning = output(warn);
536+
expect(warning).toContain("hardware acceleration is UNVERIFIED");
537+
expect(warning).toContain("hyperframes doctor");
538+
expect(warning).toContain("sudo usermod -aG render $USER");
539+
expect(warning).not.toContain("found no hardware GPU");
540+
expect(output(error)).not.toContain("this render uses software");
541+
} finally {
542+
vi.useRealTimers();
543+
}
544+
});
545+
546+
it("explicit 'hardware' with a broken Chrome keeps the Chrome-install advice", async () => {
547+
_setPuppeteerForTests({
548+
launch: vi.fn().mockRejectedValue(new Error("spawn ENOENT /bad/chrome")),
549+
} as unknown as PuppeteerNode);
550+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
551+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
552+
expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
553+
"hardware",
554+
);
555+
const warning = output(warn);
556+
expect(warning).toContain("GPU probe could not run");
557+
expect(warning).toContain("hyperframes doctor");
558+
expect(warning).not.toContain("--gpus all");
559+
expect(output(error)).not.toContain("this render uses software");
560+
});
561+
562+
it("explicit 'hardware' with no hardware GPU gives the WSL fix, not Docker passthrough", async () => {
563+
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
564+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
565+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
566+
expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
567+
"hardware",
568+
);
569+
const warning = output(warn);
570+
expect(warning).toContain("sudo usermod -aG render $USER");
571+
expect(warning).not.toContain("--gpus all");
572+
expect(output(error)).not.toContain("this render uses software");
573+
});
574+
575+
it("stays quiet when WSL hands Chrome a hardware GPU", async () => {
576+
setMockWebGlProbe({
577+
hasWebGL: true,
578+
vendor: "Google Inc. (Microsoft Corporation)",
579+
renderer: "ANGLE (Microsoft Corporation, D3D12 (Intel(R) Graphics), OpenGL ES 3.0)",
580+
});
581+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
582+
expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("hardware");
583+
expect(output(error)).not.toContain("WSL");
584+
});
585+
});
586+
464587
it("falls back to 'software' within the probe budget when the probe page never answers", async () => {
465588
vi.useFakeTimers();
466589
try {

0 commit comments

Comments
 (0)