fix(engine): skip readiness wait for natively-extracted HDR videos

HDR layered compositing extracts HEVC video frames out-of-band via
ffmpeg, so the in-DOM `<video>` element is only used for layout. On
Linux headless-shell, Chromium ships without HEVC support and these
elements never reach `readyState >= 1`, causing the per-page readiness
poll to time out after 45s with "video metadata not ready".

Add `skipReadinessVideoIds` to `CaptureOptions` and honor it in both
screenshot and beginframe readiness polls. Wire `nativeHdrVideoIds`
through every HDR-path `createCaptureSession`/`executeParallelCapture`
call in `renderOrchestrator`.

Made-with: Cursor
This commit is contained in:
Vance Ingalls
2026-04-19 22:54:03 -07:00
parent 70a891281c
commit 0d97d3146a
3 changed files with 33 additions and 8 deletions
+9 -3
View File
@@ -253,10 +253,14 @@ export async function initializeSession(session: CaptureSession): Promise<void>
}
// Wait for all video elements to have loaded metadata (dimensions + duration)
// Without this, frame 0 captures videos at their 300x150 default size
// Without this, frame 0 captures videos at their 300x150 default size.
// skipReadinessVideoIds excludes natively-extracted videos (e.g. HDR HEVC
// sources) whose frames come from ffmpeg out-of-band — Chromium may not be
// able to decode them at all (e.g. HEVC on Linux headless-shell).
const skipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
const videosReady = await pollPageExpression(
page,
`document.querySelectorAll("video").length === 0 || Array.from(document.querySelectorAll("video")).every(v => v.readyState >= 1)`,
`(() => { const skip = new Set(${skipIdsLiteral}); const vids = Array.from(document.querySelectorAll("video")).filter(v => !skip.has(v.id)); return vids.length === 0 || vids.every(v => v.readyState >= 1); })()`,
pageReadyTimeout,
);
if (!videosReady) {
@@ -331,11 +335,13 @@ export async function initializeSession(session: CaptureSession): Promise<void>
// Wait for all video elements to have loaded metadata (dimensions + duration).
// Without this, frame 0 captures videos at their 300x150 default size.
// See screenshot-mode comment above for why skipReadinessVideoIds exists.
const beginframeSkipIdsLiteral = JSON.stringify(session.options.skipReadinessVideoIds ?? []);
const videoDeadline =
Date.now() + (session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout);
while (Date.now() < videoDeadline) {
const videosReady = await page.evaluate(
`document.querySelectorAll("video").length === 0 || Array.from(document.querySelectorAll("video")).every(v => v.readyState >= 1)`,
`(() => { const skip = new Set(${beginframeSkipIdsLiteral}); const vids = Array.from(document.querySelectorAll("video")).filter(v => !skip.has(v.id)); return vids.length === 0 || vids.every(v => v.readyState >= 1); })()`,
);
if (videosReady) break;
await new Promise((r) => setTimeout(r, 100));
+12
View File
@@ -94,6 +94,18 @@ export interface CaptureOptions {
format?: "jpeg" | "png";
quality?: number;
deviceScaleFactor?: number;
/**
* Video element IDs to exclude from the in-page readiness check that waits
* for `video.readyState >= 1` before capture starts.
*
* Use for videos whose frames are supplied out-of-band (e.g. native HDR
* frame extraction via ffmpeg). The DOM `<video>` element is then only
* needed for layout (`getBoundingClientRect` / `offsetWidth`), which works
* at `readyState=0`. Without this, codecs that headless Chromium can't
* decode (HEVC on Linux `headless-shell`) cause a fatal timeout even
* though we never asked the browser to play the video.
*/
skipReadinessVideoIds?: readonly string[];
}
export interface CaptureResult {
@@ -1219,10 +1219,17 @@ export async function executeRenderJob(
// before each DOM screenshot — only the native FFmpeg-extracted HLG
// frames are used for HDR pixels.
if (!fileServer) throw new Error("fileServer must be initialized before HDR compositing");
// Native HDR videos (e.g. HEVC) may be undecodable by Chrome on the
// current platform — Linux headless-shell ships without HEVC support.
// Their pixels come from out-of-band ffmpeg extraction, so the DOM
// `<video>` element is only kept around for layout. Skip the per-page
// readiness wait for these IDs; otherwise the render hangs 45s and
// throws "video metadata not ready" even though we never asked the
// browser to decode the video.
const domSession = await createCaptureSession(
fileServer.url,
framesDir,
captureOptions,
{ ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
createVideoFrameInjector(frameLookup),
cfg,
);
@@ -1919,7 +1926,7 @@ export async function executeRenderJob(
fileServer.url,
workDir,
tasks,
captureOptions,
{ ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
() => createVideoFrameInjector(frameLookup),
abortSignal,
(progress) => {
@@ -1958,7 +1965,7 @@ export async function executeRenderJob(
(await createCaptureSession(
fileServer.url,
framesDir,
captureOptions,
{ ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
videoInjector,
cfg,
));
@@ -2020,7 +2027,7 @@ export async function executeRenderJob(
fileServer.url,
workDir,
tasks,
captureOptions,
{ ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
() => createVideoFrameInjector(frameLookup),
abortSignal,
(progress) => {
@@ -2060,7 +2067,7 @@ export async function executeRenderJob(
(await createCaptureSession(
fileServer.url,
framesDir,
captureOptions,
{ ...captureOptions, skipReadinessVideoIds: Array.from(nativeHdrVideoIds) },
videoInjector,
cfg,
));