Skip to content

Commit 9046b3b

Browse files
fix(engine): defend macOS regular Chrome screenshots
Fixes heygen-com#1699.
1 parent 2524788 commit 9046b3b

13 files changed

Lines changed: 819 additions & 15 deletions

File tree

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// @vitest-environment node
2+
import { describe, expect, it } from "vitest";
3+
import { resolveCaptureSessionOptions } from "./frameCapture.js";
4+
5+
describe("createCaptureSession captureBeyondViewport defaults", () => {
6+
it("plumbs the macOS regular-Chrome default into returned session options", () => {
7+
const options = resolveCaptureSessionOptions(
8+
{
9+
width: 1920,
10+
height: 1080,
11+
fps: { num: 30, den: 1 },
12+
format: "jpeg",
13+
},
14+
"Chrome/149.0.7827.155",
15+
"darwin",
16+
);
17+
18+
expect(options.captureBeyondViewport).toBe(true);
19+
});
20+
21+
it("preserves explicit caller overrides", () => {
22+
const options = resolveCaptureSessionOptions(
23+
{
24+
width: 1920,
25+
height: 1080,
26+
fps: { num: 30, den: 1 },
27+
format: "jpeg",
28+
captureBeyondViewport: false,
29+
},
30+
"Chrome/149.0.7827.155",
31+
"darwin",
32+
);
33+
34+
expect(options.captureBeyondViewport).toBe(false);
35+
});
36+
});

‎packages/engine/src/services/frameCapture.ts‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ import {
2828
getCdpSession,
2929
pageScreenshotCapture,
3030
initTransparentBackground,
31+
shouldDefaultCaptureBeyondViewport,
3132
} from "./screenshotService.js";
3233
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
3334
import type {
@@ -310,6 +311,18 @@ export async function driveWarmupTicks(
310311
}
311312
}
312313

314+
export function resolveCaptureSessionOptions(
315+
options: CaptureOptions,
316+
browserVersion: string,
317+
platform: NodeJS.Platform = process.platform,
318+
): CaptureOptions {
319+
return {
320+
...options,
321+
captureBeyondViewport:
322+
options.captureBeyondViewport ?? shouldDefaultCaptureBeyondViewport(browserVersion, platform),
323+
};
324+
}
325+
313326
async function waitForCloseWithTimeout(promise: Promise<unknown>): Promise<boolean> {
314327
let timedOut = false;
315328
let timer: ReturnType<typeof setTimeout> | undefined;
@@ -417,6 +430,7 @@ export async function createCaptureSession(
417430
}, variablesJson);
418431
}
419432
const browserVersion = await browser.version();
433+
const sessionOptions = resolveCaptureSessionOptions(options, browserVersion);
420434
const expectedMajor = config?.expectedChromiumMajor;
421435
if (Number.isFinite(expectedMajor)) {
422436
const actualChromiumMajor = Number.parseInt(
@@ -430,9 +444,9 @@ export async function createCaptureSession(
430444
}
431445
}
432446
const viewport: Viewport = {
433-
width: options.width,
434-
height: options.height,
435-
deviceScaleFactor: options.deviceScaleFactor || 1,
447+
width: sessionOptions.width,
448+
height: sessionOptions.height,
449+
deviceScaleFactor: sessionOptions.deviceScaleFactor || 1,
436450
};
437451
await page.setViewport(viewport);
438452

@@ -446,7 +460,7 @@ export async function createCaptureSession(
446460
return {
447461
browser,
448462
page,
449-
options,
463+
options: sessionOptions,
450464
serverUrl,
451465
outputDir,
452466
onBeforeCapture,

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

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import {
77
cdpSessionCache,
88
injectVideoFramesBatch,
99
syncVideoFrameVisibility,
10+
shouldDefaultCaptureBeyondViewport,
1011
} from "./screenshotService.js";
1112

1213
// Stub a Page + CDPSession just enough that pageScreenshotCapture can call
@@ -121,6 +122,22 @@ describe("pageScreenshotCapture supersample plumbing", () => {
121122
});
122123
});
123124

125+
describe("shouldDefaultCaptureBeyondViewport", () => {
126+
it("guards regular Chrome on macOS", () => {
127+
expect(shouldDefaultCaptureBeyondViewport("Chrome/149.0.7827.155", "darwin")).toBe(true);
128+
});
129+
130+
it("keeps chrome-headless-shell on the faster viewport-bound path", () => {
131+
expect(shouldDefaultCaptureBeyondViewport("HeadlessChrome/148.0.7778.97", "darwin")).toBe(
132+
false,
133+
);
134+
});
135+
136+
it("does not change regular Chrome defaults on non-macOS platforms", () => {
137+
expect(shouldDefaultCaptureBeyondViewport("Chrome/149.0.7827.155", "linux")).toBe(false);
138+
});
139+
});
140+
124141
describe("injectVideoFramesBatch replacement layout", () => {
125142
it("does not copy opposing inset constraints onto the injected frame image", async () => {
126143
const { window, document } = parseHTML(

‎packages/engine/src/services/screenshotService.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,17 @@ export async function getCdpSession(page: Page): Promise<import("puppeteer-core"
1919
return client;
2020
}
2121

22+
export function shouldDefaultCaptureBeyondViewport(
23+
browserVersion: string,
24+
platform: NodeJS.Platform = process.platform,
25+
): boolean {
26+
// Regular Chrome's viewport-bound screenshot path can expose a compositor
27+
// surface shorter than the page viewport on affected macOS builds. In that
28+
// case Chrome fills the clipped area with the page background. Headless shell
29+
// reports as HeadlessChrome and keeps the faster viewport-bound path.
30+
return platform === "darwin" && browserVersion.startsWith("Chrome/");
31+
}
32+
2233
/**
2334
* BeginFrame result with screenshot data and damage detection.
2435
*/

‎packages/engine/src/types.ts‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -93,10 +93,11 @@ export interface CaptureOptions {
9393
quality?: number;
9494
deviceScaleFactor?: number;
9595
/**
96-
* Opt into Chrome's capture-beyond-viewport screenshot path. Keep this off
97-
* for ordinary viewport-sized captures because it is substantially slower in
98-
* Chrome's screenshot compositor path. Enable for known compositor edge cases
99-
* such as native video surfaces in tall portrait renders.
96+
* Opt into Chrome's capture-beyond-viewport screenshot path. Leave undefined
97+
* to let the engine pick the safe browser-specific default. Pass false only
98+
* when the caller explicitly wants Chrome's faster viewport-bound path.
99+
* Enable for known compositor edge cases such as native video surfaces in
100+
* tall portrait renders.
100101
*/
101102
captureBeyondViewport?: boolean;
102103
/**

‎packages/producer/src/services/distributed/renderChunk.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -507,7 +507,7 @@ export async function renderChunk(
507507
// declare `data-composition-variables` leave this undefined and the
508508
// engine skips the `evaluateOnNewDocument` injection.
509509
variables: encoder.variables,
510-
captureBeyondViewport: (planVideos?.videos.length ?? 0) > 0,
510+
...((planVideos?.videos.length ?? 0) > 0 ? { captureBeyondViewport: true } : {}),
511511
// lock the BeginFrame warmup loop to a fixed iteration count so
512512
// `beginFrameTimeTicks` is host-independent. Only chunks ever set this.
513513
lockWarmupTicks: true,

‎packages/producer/src/services/render/stages/captureStage.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,8 @@ export interface CaptureStageResult {
126126
probeSession: CaptureSession | null;
127127
/** Browser console buffer from whichever session was active last. */
128128
lastBrowserConsole: string[];
129+
/** Engine-resolved screenshot flag from the consumed sequential/probe session, when observed. */
130+
captureBeyondViewport?: boolean;
129131
}
130132

131133
export async function runCaptureStage(input: CaptureStageInput): Promise<CaptureStageResult> {
@@ -150,6 +152,7 @@ export async function runCaptureStage(input: CaptureStageInput): Promise<Capture
150152
} = input;
151153
let { workerCount, probeSession } = input;
152154
let lastBrowserConsole: string[] = [];
155+
let captureBeyondViewport: boolean | undefined = probeSession?.options.captureBeyondViewport;
153156

154157
// Derive a local cfg view rather than reading `forceScreenshot` from the
155158
// caller-owned `cfg`. The sequencer threads the resolved value via the
@@ -228,6 +231,7 @@ export async function runCaptureStage(input: CaptureStageInput): Promise<Capture
228231
workerCount = lastAttempt.workers;
229232
}
230233
if (probeSession) {
234+
captureBeyondViewport = probeSession.options.captureBeyondViewport;
231235
lastBrowserConsole = probeSession.browserConsoleBuffer;
232236
await closeCaptureSession(probeSession);
233237
probeSession = null;
@@ -245,6 +249,7 @@ export async function runCaptureStage(input: CaptureStageInput): Promise<Capture
245249
videoInjector,
246250
captureCfg,
247251
));
252+
captureBeyondViewport = session.options.captureBeyondViewport;
248253
if (probeSession) {
249254
prepareCaptureSessionForReuse(session, framesDir, videoInjector);
250255
probeSession = null;
@@ -304,5 +309,5 @@ export async function runCaptureStage(input: CaptureStageInput): Promise<Capture
304309
}
305310
}
306311

307-
return { workerCount, probeSession, lastBrowserConsole };
312+
return { workerCount, probeSession, lastBrowserConsole, captureBeyondViewport };
308313
}

‎packages/producer/src/services/render/stages/captureStreamingStage.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,8 @@ export type CaptureStreamingStageResult =
126126
probeSession: CaptureSession | null;
127127
lastBrowserConsole: string[];
128128
workerCount: number;
129+
/** Engine-resolved screenshot flag from the consumed sequential/probe session, when observed. */
130+
captureBeyondViewport?: boolean;
129131
}
130132
| {
131133
/** Spawn failed (non-abort) — sequencer should fall back to the disk path. */
@@ -156,6 +158,7 @@ export async function runCaptureStreamingStage(
156158
} = input;
157159
let { workerCount, probeSession } = input;
158160
let lastBrowserConsole: string[] = [];
161+
let captureBeyondViewport: boolean | undefined = probeSession?.options.captureBeyondViewport;
159162

160163
// Derive a local cfg view rather than reading `forceScreenshot` from the
161164
// caller-owned `cfg`. The sequencer threads the resolved value via the
@@ -241,6 +244,7 @@ export async function runCaptureStreamingStage(
241244
pushWorkerDedupPerfs(workerResults, dedupPerfs);
242245

243246
if (probeSession) {
247+
captureBeyondViewport = probeSession.options.captureBeyondViewport;
244248
lastBrowserConsole = probeSession.browserConsoleBuffer;
245249
await closeCaptureSession(probeSession);
246250
probeSession = null;
@@ -258,6 +262,7 @@ export async function runCaptureStreamingStage(
258262
videoInjector,
259263
captureCfg,
260264
));
265+
captureBeyondViewport = session.options.captureBeyondViewport;
261266
if (probeSession) {
262267
prepareCaptureSessionForReuse(session, framesDir, videoInjector);
263268
probeSession = null;
@@ -325,6 +330,7 @@ export async function runCaptureStreamingStage(
325330
probeSession,
326331
lastBrowserConsole,
327332
workerCount,
333+
captureBeyondViewport,
328334
};
329335
} finally {
330336
// Defensive cleanup: if the streaming branch threw before

‎packages/producer/src/services/renderOrchestrator.ts‎

Lines changed: 21 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1074,6 +1074,10 @@ export async function executeRenderJob(
10741074
fileServer = probeResult.fileServer;
10751075
probeSession = probeResult.probeSession;
10761076
lastBrowserConsole = probeResult.lastBrowserConsole;
1077+
let resolvedCaptureBeyondViewport = probeSession?.options.captureBeyondViewport;
1078+
if (resolvedCaptureBeyondViewport !== undefined) {
1079+
updateCaptureObservability({ captureBeyondViewport: resolvedCaptureBeyondViewport });
1080+
}
10771081
// The probe stage produces `duration` / `totalFrames` values; the
10781082
// sequencer owns the `RenderJob` and writes them onto it.
10791083
job.duration = probeResult.duration;
@@ -1213,11 +1217,13 @@ export async function executeRenderJob(
12131217
quality: needsAlpha ? undefined : job.config.quality === "draft" ? 80 : 95,
12141218
variables: job.config.variables,
12151219
deviceScaleFactor,
1216-
captureBeyondViewport: composition.videos.length > 0,
1220+
...(composition.videos.length > 0 ? { captureBeyondViewport: true } : {}),
12171221
};
1218-
updateCaptureObservability({
1219-
captureBeyondViewport: captureOptions.captureBeyondViewport ?? false,
1220-
});
1222+
resolvedCaptureBeyondViewport =
1223+
captureOptions.captureBeyondViewport ?? resolvedCaptureBeyondViewport;
1224+
if (resolvedCaptureBeyondViewport !== undefined) {
1225+
updateCaptureObservability({ captureBeyondViewport: resolvedCaptureBeyondViewport });
1226+
}
12211227

12221228
// Capture sessions do not need native browser metadata for videos whose
12231229
// pixels come from out-of-band FFmpeg frame extraction. Waiting on those
@@ -1442,7 +1448,7 @@ export async function executeRenderJob(
14421448
observability.checkpoint("capture_strategy", "resolved", {
14431449
workerCount,
14441450
forceScreenshot: captureForceScreenshot,
1445-
captureBeyondViewport: captureOptions.captureBeyondViewport ?? false,
1451+
captureBeyondViewport: resolvedCaptureBeyondViewport ?? null,
14461452
useStreamingEncode,
14471453
useLayeredComposite,
14481454
usePageSideCompositing: usePageSideCompositingForTransitions,
@@ -1592,6 +1598,11 @@ export async function executeRenderJob(
15921598
streamingHandled = true;
15931599
workerCount = streamingRes.workerCount;
15941600
updateCaptureObservability({ workerCount });
1601+
if (streamingRes.captureBeyondViewport !== undefined) {
1602+
updateCaptureObservability({
1603+
captureBeyondViewport: streamingRes.captureBeyondViewport,
1604+
});
1605+
}
15951606
probeSession = streamingRes.probeSession;
15961607
lastBrowserConsole = streamingRes.lastBrowserConsole;
15971608
perfStages.captureMs = Date.now() - stage4Start;
@@ -1637,6 +1648,11 @@ export async function executeRenderJob(
16371648
const captureFrameMs = Date.now() - captureFrameStart;
16381649
workerCount = captureRes.workerCount;
16391650
updateCaptureObservability({ workerCount });
1651+
if (captureRes.captureBeyondViewport !== undefined) {
1652+
updateCaptureObservability({
1653+
captureBeyondViewport: captureRes.captureBeyondViewport,
1654+
});
1655+
}
16401656
probeSession = captureRes.probeSession;
16411657
lastBrowserConsole = captureRes.lastBrowserConsole;
16421658

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"name": "chrome-screenshot-bottom-edge",
3+
"description": "Regression guard for screenshot capture leaking page background into the bottom of a viewport-sized MP4. The composition paints a red page background below full-frame content so any bottom-edge capture gap collapses PSNR.",
4+
"tags": ["regression", "screenshot", "edge"],
5+
"minPsnr": 30,
6+
"maxFrameFailures": 0,
7+
"minAudioCorrelation": 0,
8+
"maxAudioLagWindows": 1,
9+
"renderConfig": {
10+
"fps": 12,
11+
"workers": 1
12+
}
13+
}

0 commit comments

Comments
 (0)