Skip to content

Write HTML. Render video. Built for agents.

fix(engine): stop multi-worker renders hanging on media-heavy pages on Windows and macOS (#5565)

Miguel Ángel102c14a6c4ce
diff --git a/packages/engine/src/services/parallelCoordinator.test.ts b/packages/engine/src/services/parallelCoordinator.test.ts
index 365ce3ffbc..646bfdfc9d 100644
--- a/packages/engine/src/services/parallelCoordinator.test.ts
+++ b/packages/engine/src/services/parallelCoordinator.test.ts
@@ -211,40 +211,15 @@ describe("computeWorkerSizing", () => {
});
describe("shouldDisableBrowserPoolForParallelWorker", () => {
- const linuxHeadlessWorker = {
- parallel: true,
- platform: "linux" as NodeJS.Platform,
- deviceScaleFactor: 1,
- headlessShellPath: "/tmp/chrome-headless-shell",
- };
-
- it.each([
- ["BeginFrame", false],
- ["forced screenshot", true],
- ])(
- "disables the browser pool for parallel Linux/headless %s workers",
- (_mode, forceScreenshot) => {
- expect(
- shouldDisableBrowserPoolForParallelWorker({
- ...linuxHeadlessWorker,
- forceScreenshot,
- }),
- ).toBe(true);
- },
- );
+ // heygen-com/hyperframes#5548: pages sharing one browser share its
+ // connections to the file server, so every platform isolates workers.
+ it("gives every parallel worker its own browser", () => {
+ expect(shouldDisableBrowserPoolForParallelWorker({ parallel: true })).toBe(true);
+ });
- it.each([
- ["non-parallel", { parallel: false, forceScreenshot: true }],
- ["non-linux", { platform: "darwin" as NodeJS.Platform, forceScreenshot: true }],
- ["no headless shell", { headlessShellPath: undefined, forceScreenshot: true }],
- ["supersampled", { deviceScaleFactor: 2, forceScreenshot: false }],
- ])("keeps the shared pool for %s workers", (_case, overrides) => {
- expect(
- shouldDisableBrowserPoolForParallelWorker({
- ...linuxHeadlessWorker,
- ...overrides,
- }),
- ).toBe(false);
+ it("keeps the shared pool for a single worker", () => {
+ expect(shouldDisableBrowserPoolForParallelWorker({ parallel: false })).toBe(false);
+ expect(shouldDisableBrowserPoolForParallelWorker({})).toBe(false);
});
});
diff --git a/packages/engine/src/services/parallelCoordinator.ts b/packages/engine/src/services/parallelCoordinator.ts
index b7a2d95064..adf6699fa5 100644
--- a/packages/engine/src/services/parallelCoordinator.ts
+++ b/packages/engine/src/services/parallelCoordinator.ts
@@ -123,11 +123,6 @@ export interface WorkerSizingConfig extends Partial<
type WorkerBrowserPoolDecision = {
parallel?: boolean;
- platform: NodeJS.Platform;
- // Deliberately accepted but not used: forceScreenshot is not an exclusion.
- forceScreenshot?: boolean;
- deviceScaleFactor?: number;
- headlessShellPath?: string;
};
// System-memory budget per parallel worker. Each worker is a full Chrome
@@ -165,19 +160,13 @@ function defaultSafeMaxWorkers(): number {
}
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.
+// 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,
- platform,
- deviceScaleFactor,
- headlessShellPath,
}: WorkerBrowserPoolDecision): boolean {
- return Boolean(
- parallel && platform === "linux" && headlessShellPath && (deviceScaleFactor ?? 1) <= 1,
- );
+ return Boolean(parallel);
}
export function selectWorkerDiagnostics(
@@ -850,13 +839,7 @@ async function executeWorkerTask(
let session: CaptureSession | null = null;
let perf: CapturePerfSummary | undefined;
- const needsSeparateBrowsers = shouldDisableBrowserPoolForParallelWorker({
- parallel,
- platform: process.platform,
- forceScreenshot: config?.forceScreenshot,
- deviceScaleFactor: captureOptions.deviceScaleFactor,
- headlessShellPath: resolveHeadlessShellPath(config),
- });
+ const needsSeparateBrowsers = shouldDisableBrowserPoolForParallelWorker({ parallel });
const workerConfig: Partial<EngineConfig> | undefined = needsSeparateBrowsers
? { ...config, enableBrowserPool: false }
: config;
diff --git a/packages/engine/src/services/parallelWorkerBrowsers.browser.test.ts b/packages/engine/src/services/parallelWorkerBrowsers.browser.test.ts
new file mode 100644
index 0000000000..f59d26459b
--- /dev/null
+++ b/packages/engine/src/services/parallelWorkerBrowsers.browser.test.ts
@@ -0,0 +1,79 @@
+import { spawnSync } from "node:child_process";
+import { createServer, type ServerResponse } from "node:http";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { acquireBrowser, drainBrowserPool, resolveHeadlessShellPath } from "./browserManager.js";
+import { shouldDisableBrowserPoolForParallelWorker } from "./parallelCoordinator.js";
+
+const chromePath = resolveHeadlessShellPath();
+const hasBrowser = chromePath !== undefined && spawnSync(chromePath, ["--version"]).status === 0;
+
+// heygen-com/hyperframes#5548: a media-heavy page holds every connection
+// Chrome allows to one host, so a second worker page in the same browser
+// never finished page.goto on Windows segmented capture.
+describe.skipIf(!hasBrowser)("parallel worker browsers", () => {
+ const MEDIA_ELEMENTS = 10;
+ const openMedia = new Set<ServerResponse>();
+ let origin = "";
+ const server = createServer((req, res) => {
+ if (req.url?.startsWith("/media/")) {
+ // Never finishes, like a long source still buffering.
+ res.writeHead(200, { "Content-Type": "audio/mpeg" });
+ res.write(Buffer.alloc(1024));
+ openMedia.add(res);
+ res.on("close", () => openMedia.delete(res));
+ return;
+ }
+ const body =
+ req.url === "/heavy"
+ ? Array.from(
+ { length: MEDIA_ELEMENTS },
+ (_, i) => `<audio preload="auto" src="/media/${i}.mp3"></audio>`,
+ ).join("")
+ : "<p>worker</p>";
+ res.writeHead(200, { "Content-Type": "text/html" });
+ res.end(`<html><body>${body}</body></html>`);
+ });
+
+ beforeAll(async () => {
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ const address = server.address();
+ if (!address || typeof address === "string") throw new Error("No test server address");
+ origin = `http://127.0.0.1:${address.port}`;
+ });
+
+ afterAll(async () => {
+ for (const res of openMedia) res.destroy();
+ await drainBrowserPool();
+ await new Promise<void>((resolve) => server.close(() => resolve()));
+ });
+
+ it("loads a second worker's page while the first page's media holds its connections", async () => {
+ const config = {
+ enableBrowserPool: !shouldDisableBrowserPoolForParallelWorker({ parallel: true }),
+ forceScreenshot: true,
+ };
+ const args = [
+ "--no-sandbox",
+ "--disable-dev-shm-usage",
+ "--autoplay-policy=no-user-gesture-required",
+ ];
+ const first = await acquireBrowser(args, config);
+ const second = await acquireBrowser(args, config);
+ try {
+ const heavy = await first.browser.newPage();
+ await heavy.goto(`${origin}/heavy`);
+ const deadline = Date.now() + 10_000;
+ while (openMedia.size < 6 && Date.now() < deadline) {
+ await new Promise((resolve) => setTimeout(resolve, 50));
+ }
+ expect(openMedia.size).toBeGreaterThanOrEqual(6);
+
+ const page = await second.browser.newPage();
+ await page.goto(`${origin}/worker`, { timeout: 5_000 });
+ expect(await page.evaluate(() => document.body.textContent)).toBe("worker");
+ } finally {
+ await first.release();
+ await second.release();
+ }
+ }, 30_000);
+});
diff --git a/packages/producer/src/services/render/stages/captureSegmentedStage.ts b/packages/producer/src/services/render/stages/captureSegmentedStage.ts
index 8f46ad2dc4..966b14c22d 100644
--- a/packages/producer/src/services/render/stages/captureSegmentedStage.ts
+++ b/packages/producer/src/services/render/stages/captureSegmentedStage.ts
@@ -23,7 +23,6 @@ import {
getCapturePerfSummary,
initializeSession,
prepareCaptureSessionForReuse,
- resolveHeadlessShellPath,
shouldDisableBrowserPoolForParallelWorker,
spawnStreamingEncoder,
type BeforeCaptureHook,
@@ -327,9 +326,6 @@ async function openSegmentedSession(input: CaptureSegmentedStageInput): Promise<
const captureOptions = input.buildCaptureOptions();
const ownBrowser = shouldDisableBrowserPoolForParallelWorker({
parallel: (input.workerCount ?? 1) > 1,
- platform: process.platform,
- deviceScaleFactor: captureOptions.deviceScaleFactor,
- headlessShellPath: resolveHeadlessShellPath(captureCfg),
});
return createCaptureSession(
input.fileServer.url,