Skip to content

Commit bb34e30

Browse files
fix(engine): a render stall names the step Chrome hung in and says what to do (#5450)
* fix(engine): a capture stall names the step Chrome stopped answering in * fix(engine): a stall on a motion-blurred frame names the seek or injection it hung in
1 parent 8bca7c4 commit bb34e30

5 files changed

Lines changed: 90 additions & 15 deletions

File tree

‎packages/engine/src/services/frameCapture-motionBlur.test.ts‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -591,3 +591,47 @@ describe("computeStaticFrameSet's real page-side property matching (not a canned
591591
expect(result.nonSpatialOnlyFrameSet.has(0)).toBe(true);
592592
});
593593
});
594+
595+
describe("a stall on a motion-blurred frame names the step in progress", () => {
596+
it("names the frame seek, the injection and the restore seek, not the previous frame's step", async () => {
597+
const steps: string[] = [];
598+
const session = makeSession({
599+
captureStep: "capturing the frame",
600+
onBeforeCapture: async () => {
601+
steps.push(`inject:${session.captureStep}`);
602+
},
603+
});
604+
const page = globalThis as unknown as {
605+
window: { __hf: { seek: (time: number, options?: { subFrameDivisions?: number }) => void } };
606+
};
607+
page.window.__hf.seek = (_time, options) => {
608+
if (options?.subFrameDivisions === undefined) steps.push(`seek:${session.captureStep}`);
609+
};
610+
611+
await captureFrameToBuffer(session, 10, 10 / 30);
612+
613+
expect(steps[0]).toBe("seek:seeking the timeline");
614+
expect(steps[1]).toBe("inject:injecting video frames");
615+
expect(steps[steps.length - 1]).toBe("seek:seeking the timeline");
616+
});
617+
618+
it("names the seek and the injection on a frame without motion blur too", async () => {
619+
const steps: string[] = [];
620+
const session = makeSession({
621+
motionBlur: undefined,
622+
captureStep: "capturing the frame",
623+
onBeforeCapture: async () => {
624+
steps.push(`inject:${session.captureStep}`);
625+
},
626+
});
627+
const page = globalThis as unknown as { window: { __hf: { seek: () => void } } };
628+
page.window.__hf.seek = () => {
629+
steps.push(`seek:${session.captureStep}`);
630+
};
631+
632+
await captureFrameToBuffer(session, 10, 10 / 30);
633+
634+
expect(steps).toEqual(["seek:seeking the timeline", "inject:injecting video frames"]);
635+
expect(session.captureStep).toBe("capturing the frame");
636+
});
637+
});

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,16 @@ export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSum
108108
* both times shows its frame for `heldVideoTime`, so footage does not smear. */
109109
export type BeforeCaptureHook = (page: Page, time: number, heldVideoTime?: number) => Promise<void>;
110110

111+
/** The per-frame wait a capture is in, worded for the stall error a user reads. */
112+
type CaptureStep =
113+
| "seeking the timeline"
114+
| "decoding CSS background images"
115+
| "injecting video frames"
116+
| "waiting for page seek handlers"
117+
| "loading color-grading LUTs"
118+
| "compositing the page"
119+
| "capturing the frame";
120+
111121
export interface CaptureSession {
112122
browser: Browser;
113123
/** Exact ownership token for this browser acquisition. */
@@ -298,6 +308,7 @@ export interface CaptureSession {
298308
* retries via screenshot.
299309
*/
300310
deFrameTimeouts?: number;
311+
captureStep?: CaptureStep;
301312
/**
302313
* drawElement init passed every gate but stopped before verification +
303314
* canvas injection: the session has no video-frame injector yet (probe
@@ -2856,8 +2867,10 @@ async function prepareFrameForCapture(
28562867
);
28572868

28582869
const seekStart = Date.now();
2870+
session.captureStep = "seeking the timeline";
28592871
const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);
28602872

2873+
session.captureStep = "decoding CSS background images";
28612874
await decodeDynamicCssBackgroundImages(page);
28622875

28632876
const seekMs = Date.now() - seekStart;
@@ -2867,9 +2880,12 @@ async function prepareFrameForCapture(
28672880
// replacements for <video> elements.
28682881
const beforeCaptureStart = Date.now();
28692882
if (session.onBeforeCapture) {
2883+
session.captureStep = "injecting video frames";
28702884
await session.onBeforeCapture(page, quantizedTime, heldVideoTime);
28712885
}
2886+
session.captureStep = "waiting for page seek handlers";
28722887
await waitForPendingSeekCompletion(page);
2888+
session.captureStep = "loading color-grading LUTs";
28732889
await page.evaluate(async () => {
28742890
const runtime = (
28752891
window as Window & {
@@ -2889,6 +2905,7 @@ async function prepareFrameForCapture(
28892905
session.captureMode !== "beginframe" &&
28902906
session.captureMode !== "drawelement"
28912907
) {
2908+
session.captureStep = "compositing the page";
28922909
await page.evaluate(async () => {
28932910
const w = window as unknown as { __hf_page_composite_prepare?: () => Promise<boolean> };
28942911
if (typeof w.__hf_page_composite_prepare === "function") {
@@ -2909,6 +2926,7 @@ async function prepareFrameForCapture(
29092926
});
29102927
}
29112928

2929+
session.captureStep = "capturing the frame";
29122930
return { quantizedTime, seekMs, beforeCaptureMs };
29132931
}
29142932

@@ -4189,12 +4207,14 @@ async function captureAccumulatedFrame(
41894207
const frameTime = quantizeSeekTime(absFrameIndex / fps, fps);
41904208

41914209
const eventfulSeekStart = Date.now();
4210+
session.captureStep = "seeking the timeline";
41924211
await seekPageTimeline(session.page, frameTime, undefined);
41934212
const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
41944213
if (session.onBeforeCapture) {
41954214
// The injector copies a video's own style only when its frame changes: inject at frameTime
41964215
// first so the held frame carries frameTime's style, not the first sample's.
41974216
const injectStart = Date.now();
4217+
session.captureStep = "injecting video frames";
41984218
await session.onBeforeCapture(session.page, frameTime, frameTime);
41994219
totals.beforeCaptureMs += Date.now() - injectStart;
42004220
}
@@ -4237,6 +4257,7 @@ async function captureAccumulatedFrame(
42374257
}
42384258

42394259
const restoreSeekStart = Date.now();
4260+
session.captureStep = "seeking the timeline";
42404261
await seekPageTimeline(session.page, frameTime, { suppressEvents: true });
42414262
totals.seekMs += Date.now() - restoreSeekStart;
42424263

@@ -4603,6 +4624,7 @@ export async function captureFramesBatchPipelined(
46034624
const fps = fpsToNumber(options.fps);
46044625
const quantized = times.map((t) => quantizeTimeToFrame(t, fps));
46054626

4627+
session.captureStep = "capturing the frame";
46064628
const { encodeResults, failedAt, error } = await produceDrawElementFrameBatch(
46074629
page,
46084630
quantized,

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -203,7 +203,7 @@ async function captureSegmentFrames(
203203
ctx.captureFrame(ctx.session, i, time),
204204
ctx.stallTimeoutMs - (Date.now() - lastProgressAt),
205205
{
206-
captureMode: ctx.session.captureMode,
206+
session: ctx.session,
207207
frameIndex: i,
208208
totalFrames: ctx.totalFrames,
209209
stallTimeoutMs: ctx.stallTimeoutMs,

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,11 +61,12 @@ mock.module("@hyperframes/engine", () => ({
6161
}
6262
return [];
6363
},
64-
captureFrameToBuffer: async () => {
64+
captureFrameToBuffer: async (session: { captureStep?: string }) => {
6565
if (failCaptureFrameToBuffer) {
6666
throw new Error("captureFrameToBuffer failed");
6767
}
6868
if (hangSequentialUntilStall) {
69+
session.captureStep = "capturing the frame";
6970
return new Promise(() => {});
7071
}
7172
return { buffer: Buffer.from("frame"), captureTimeMs: 1 };
@@ -600,6 +601,7 @@ describe("runCaptureStreamingStage", () => {
600601
expect(caught).toBeInstanceOf(Error);
601602
expect((caught as Error & { cause?: Error }).cause?.name).toBe("SequentialCaptureStallError");
602603
expect((caught as Error).message).toContain("Sequential screenshot capture stalled");
604+
expect((caught as Error).message).toContain("(stuck at frame 0/10 while capturing the frame)");
603605
expect((caught as Error).message).not.toContain("drawElement");
604606
expect(closeCaptureSession).toHaveBeenCalledTimes(1);
605607
});

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

Lines changed: 20 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,9 @@ import type { SdrStreamingCapturePlan } from "../capturePlan.js";
9393
*/
9494
const DEFAULT_CAPTURE_STALL_MS = 60_000;
9595
const DE_STALL_POLL_MS = 5_000;
96+
const STALL_ADVICE =
97+
"Chrome stopped answering. If another app is keeping the GPU or CPU busy " +
98+
"(a 3D render, a game, another export), let it finish or render one job at a time, then retry.";
9699

97100
/**
98101
* The parallel no-progress watchdog tripped. Typed like the sequential stall
@@ -116,12 +119,12 @@ class ParallelCaptureStallError extends Error {
116119
}) {
117120
const phases = args.phaseSummary ? ` Last worker phases: ${args.phaseSummary}.` : "";
118121
super(
119-
args.variant === "drain"
122+
(args.variant === "drain"
120123
? `[Render] Parallel ${args.captureLabel} capture stalled: no frame progress for ` +
121-
`${args.stallTimeoutMs}ms (stuck at ${args.lastCapturedFrames}/${args.totalFrames}).${phases}`
124+
`${args.stallTimeoutMs}ms (stuck at ${args.lastCapturedFrames}/${args.totalFrames}).${phases}`
122125
: `[Render] Parallel ${args.captureLabel} capture stalled after ${args.stallTimeoutMs}ms ` +
123-
`with no frame progress (last frame ${args.lastCapturedFrames}/${args.totalFrames}); ` +
124-
`retrying on a fresh screenshot session.${phases}`,
126+
`with no frame progress (last frame ${args.lastCapturedFrames}/${args.totalFrames}); ` +
127+
`retrying on a fresh screenshot session.${phases}`) + ` ${STALL_ADVICE}`,
125128
);
126129
this.name = "ParallelCaptureStallError";
127130
this.variant = args.variant;
@@ -160,29 +163,33 @@ function captureModeLabel(mode: CaptureSession["captureMode"]): string {
160163
return "screenshot";
161164
}
162165

166+
type StalledSession = Pick<CaptureSession, "captureMode" | "captureStep">;
167+
163168
class SequentialCaptureStallError extends Error {
164169
readonly captureMode: CaptureSession["captureMode"];
165170

166171
constructor(
167-
captureMode: CaptureSession["captureMode"],
172+
session: StalledSession,
168173
stallTimeoutMs: number,
169174
frameIndex: number,
170175
totalFrames: number,
171176
) {
177+
const step = session.captureStep ? ` while ${session.captureStep}` : "";
172178
super(
173-
`[Render] Sequential ${captureModeLabel(captureMode)} capture stalled: ` +
174-
`no frame progress for ${stallTimeoutMs}ms (stuck at frame ${frameIndex}/${totalFrames}).`,
179+
`[Render] Sequential ${captureModeLabel(session.captureMode)} capture stalled: ` +
180+
`no frame progress for ${stallTimeoutMs}ms (stuck at frame ${frameIndex}/${totalFrames}${step}). ` +
181+
STALL_ADVICE,
175182
);
176183
this.name = "SequentialCaptureStallError";
177-
this.captureMode = captureMode;
184+
this.captureMode = session.captureMode;
178185
}
179186
}
180187

181188
export function raceAgainstStall<T>(
182189
promise: Promise<T>,
183190
deadlineMs: number,
184191
input: {
185-
captureMode: CaptureSession["captureMode"];
192+
session: StalledSession;
186193
frameIndex: number;
187194
totalFrames: number;
188195
stallTimeoutMs: number;
@@ -195,11 +202,11 @@ export function raceAgainstStall<T>(
195202
reject(
196203
signal?.aborted
197204
? new Error(
198-
`[Render] Sequential ${captureModeLabel(input.captureMode)} capture aborted ` +
205+
`[Render] Sequential ${captureModeLabel(input.session.captureMode)} capture aborted ` +
199206
`while a capture call was in flight (frame ${input.frameIndex}/${input.totalFrames}).`,
200207
)
201208
: new SequentialCaptureStallError(
202-
input.captureMode,
209+
input.session,
203210
input.stallTimeoutMs,
204211
input.frameIndex,
205212
input.totalFrames,
@@ -473,7 +480,7 @@ async function runWorkerEncodePipelineLoop(
473480
raceAgainstStall(
474481
promise,
475482
stallTimeoutMs - (Date.now() - lastProgressAt),
476-
{ captureMode: session.captureMode, frameIndex: idx, totalFrames, stallTimeoutMs },
483+
{ session, frameIndex: idx, totalFrames, stallTimeoutMs },
477484
abortSignal,
478485
);
479486

@@ -953,7 +960,7 @@ export async function runCaptureStreamingStage(
953960
const { buffer } = await raceAgainstStall(
954961
captureFrameToBuffer(session, i, time),
955962
stallTimeoutMs - (Date.now() - lastProgressAt),
956-
{ captureMode: session.captureMode, frameIndex: i, totalFrames, stallTimeoutMs },
963+
{ session, frameIndex: i, totalFrames, stallTimeoutMs },
957964
abortSignal,
958965
);
959966
await reorderBuffer.waitForFrame(i);

0 commit comments

Comments
 (0)