Skip to content

Write HTML. Render video. Built for agents.

fix(producer): renders the fast capture refuses keep their parallel workers (#5945)

Miguel Ángel30f514b13a00
diff --git a/packages/producer/src/services/render/perfSummary.test.ts b/packages/producer/src/services/render/perfSummary.test.ts
index 29aae01d12..28e6c8bb94 100644
--- a/packages/producer/src/services/render/perfSummary.test.ts
+++ b/packages/producer/src/services/render/perfSummary.test.ts
@@ -64,3 +64,14 @@ describe("buildRenderPerfSummary host telemetry", () => {
expect(summary.workers).toBe(4);
});
});
+
+describe("buildRenderPerfSummary drawElement gate reason", () => {
+ it("keeps the probe's gate when the workers that captured report none", () => {
+ const summary = buildRenderPerfSummary({
+ ...baseInput,
+ dedupPerfs: [{ captureMode: "screenshot" }, { captureMode: "screenshot" }],
+ drawElement: { probeGateReason: "css_effect:filter", selfVerifyFallback: false },
+ } as Parameters<typeof buildRenderPerfSummary>[0]);
+ expect(summary.drawElement?.gateReason).toBe("css_effect:filter");
+ });
+});
diff --git a/packages/producer/src/services/render/perfSummary.ts b/packages/producer/src/services/render/perfSummary.ts
index 02a100ea45..f6160f6a58 100644
--- a/packages/producer/src/services/render/perfSummary.ts
+++ b/packages/producer/src/services/render/perfSummary.ts
@@ -83,6 +83,8 @@ export function roundDb(value: number | undefined): number | undefined {
export interface DrawElementPerfInput {
compileGate?: string;
clampReason?: string;
+ /** Engine init-time gate the pre-capture probe hit; its session may be closed before capture. */
+ probeGateReason?: string;
workerInversion?: "inverted" | "reverted";
/** Auto-resolved worker count before the inversion pinned it to 1 (set only when the inversion fired). */
preInversionWorkers?: number;
@@ -145,7 +147,9 @@ function aggregateDrawElement(
if (perfs.length === 0) return undefined;
const modes = [...new Set(perfs.map((p) => p.captureMode).filter(Boolean))].sort();
const gateReasons = [
- ...new Set(perfs.map((p) => p.deGateReason).filter((r): r is string => !!r)),
+ ...new Set(
+ [de.probeGateReason, ...perfs.map((p) => p.deGateReason)].filter((r): r is string => !!r),
+ ),
].sort();
const gpuRenderers = [
...new Set(perfs.map((p) => p.gpuRenderer).filter((r): r is string => !!r)),
diff --git a/packages/producer/src/services/renderOrchestrator.deGateProbe.test.ts b/packages/producer/src/services/renderOrchestrator.deGateProbe.test.ts
new file mode 100644
index 0000000000..9d9a130fad
--- /dev/null
+++ b/packages/producer/src/services/renderOrchestrator.deGateProbe.test.ts
@@ -0,0 +1,177 @@
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveConfig } from "@hyperframes/engine";
+import { createRenderJob, executeRenderJob } from "./renderOrchestrator.js";
+
+// Entry: executeRenderJob, with a composition the browser probe stage skips (static
+// duration, no media), so no session has run the engine's drawElement gates yet.
+const { RESOLVER_WORKERS, state, captureReached } = vi.hoisted(() => {
+ const state = {
+ probeCaptureMode: "screenshot",
+ probeGateReason: undefined as string | undefined,
+ sessions: [] as object[],
+ calibrations: 0,
+ firstCapture: undefined as { workerCount: number; probeSession: unknown } | undefined,
+ };
+ const captureReached = async (input: {
+ plan: { workerCount: number };
+ probeSession: unknown;
+ }): Promise<never> => {
+ state.firstCapture ??= {
+ workerCount: input.plan.workerCount,
+ probeSession: input.probeSession,
+ };
+ throw new Error("capture reached");
+ };
+ return { RESOLVER_WORKERS: 4, state, captureReached };
+});
+
+vi.mock("@hyperframes/engine", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("@hyperframes/engine")>()),
+ assertConfiguredFfmpegBinariesExist: () => {},
+ resolveBrowserGpuMode: async () => "hardware",
+ createCaptureSession: async () => {
+ const session = { browserConsoleBuffer: [], options: {}, isInitialized: false };
+ state.sessions.push(session);
+ return session;
+ },
+ initializeSession: async (session: Record<string, unknown>) => {
+ session.isInitialized = true;
+ session.captureMode = state.probeCaptureMode;
+ session.deGateReason = state.probeGateReason;
+ },
+ closeCaptureSession: async () => {},
+}));
+vi.mock("./fileServer.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./fileServer.js")>()),
+ createFileServer: async () => ({
+ url: "http://127.0.0.1:1",
+ port: 1,
+ close: () => {},
+ addPreHeadScript: () => {},
+ }),
+}));
+vi.mock("./render/stages/compileStage.js", () => ({
+ runCompileStage: async () => ({
+ compiled: {
+ html: "<div></div>",
+ renderModeHints: { reasons: [] },
+ hasShaderTransitions: false,
+ unresolvedCompositions: [],
+ },
+ composition: { width: 320, height: 180, duration: 40, videos: [], images: [], audios: [] },
+ deviceScaleFactor: 1,
+ outputWidth: 320,
+ outputHeight: 180,
+ compileOnlyMs: 0,
+ forceScreenshot: false,
+ }),
+}));
+vi.mock("./render/stages/probeStage.js", () => ({
+ runProbeStage: async ({ compiled }: { compiled: object }) => ({
+ compiled,
+ fileServer: null,
+ probeSession: null,
+ lastBrowserConsole: [],
+ duration: 40,
+ totalFrames: 1200,
+ browserProbeMs: 0,
+ }),
+}));
+vi.mock("./render/stages/extractVideosStage.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./render/stages/extractVideosStage.js")>()),
+ runExtractVideosStage: async () => ({
+ extractionResult: null,
+ frameLookup: null,
+ videoReadinessSkipIds: new Set<string>(),
+ videoMetadataHints: new Map(),
+ nativeHdrVideoIds: new Set<string>(),
+ videoTransfers: new Map(),
+ nativeHdrImageIds: new Set<string>(),
+ imageTransfers: new Map(),
+ hdrImageSrcPaths: new Map(),
+ imageColorSpaces: [],
+ videoExtractMs: 0,
+ failureToEnforce: undefined,
+ }),
+}));
+vi.mock("./render/stages/audioStage.js", () => ({
+ runAudioStage: async () => ({ audioOutputPath: undefined, hasAudio: false, audioProcessMs: 0 }),
+}));
+vi.mock("./render/captureCost.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./render/captureCost.js")>()),
+ resolveRenderWorkerCount: () => RESOLVER_WORKERS,
+ runCaptureCalibration: async (input: { forceScreenshot: boolean; probeSession: unknown }) => {
+ state.calibrations += 1;
+ return {
+ calibration: undefined,
+ forceScreenshot: input.forceScreenshot,
+ probeSession: input.probeSession,
+ lastBrowserConsole: [],
+ };
+ },
+}));
+vi.mock("./render/stages/captureStage.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./render/stages/captureStage.js")>()),
+ runCaptureStage: captureReached,
+}));
+vi.mock("./render/stages/captureStreamingStage.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("./render/stages/captureStreamingStage.js")>()),
+ runCaptureStreamingStage: captureReached,
+}));
+
+const dirs: string[] = [];
+beforeEach(() => {
+ state.sessions = [];
+ state.calibrations = 0;
+ state.firstCapture = undefined;
+ vi.stubEnv("PRODUCER_EXPERIMENTAL_FAST_CAPTURE", "");
+ vi.stubEnv("HF_DE_PARALLEL_STREAM", "");
+ vi.stubEnv("HF_DE_PARALLEL_MIN_MEM_MB", "0");
+});
+afterEach(() => {
+ vi.unstubAllEnvs();
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+async function renderUntilCapture(): Promise<void> {
+ const root = mkdtempSync(join(tmpdir(), "hf-de-gate-probe-"));
+ dirs.push(root);
+ writeFileSync(join(root, "index.html"), "<div></div>");
+ const job = createRenderJob({
+ fps: 30,
+ quality: "standard",
+ hdrMode: "force-sdr",
+ producerConfig: resolveConfig({ useDrawElement: true, browserGpuMode: "hardware" }),
+ logger: { info() {}, warn() {}, error() {}, debug() {} },
+ });
+ await expect(executeRenderJob(job, root, join(root, "output.mp4"))).rejects.toThrow();
+}
+
+it.each([
+ ["single-worker inversion", "false"],
+ ["parallel router", "true"],
+])(
+ "a comp the engine refuses at init keeps the resolver's workers, not the %s",
+ async (_route, router) => {
+ vi.stubEnv("HF_DE_PARALLEL_ROUTER", router);
+ state.probeCaptureMode = "screenshot";
+ state.probeGateReason = "css_effect:filter";
+ await renderUntilCapture();
+ expect(state.firstCapture?.workerCount).toBe(RESOLVER_WORKERS);
+ expect(state.calibrations).toBe(1);
+ expect(state.sessions).toHaveLength(1);
+ },
+);
+
+it("a comp drawElement accepts still inverts, and capture reuses the gate-check session", async () => {
+ vi.stubEnv("HF_DE_PARALLEL_ROUTER", "false");
+ state.probeCaptureMode = "drawelement";
+ state.probeGateReason = undefined;
+ await renderUntilCapture();
+ expect(state.firstCapture?.workerCount).toBe(1);
+ expect(state.calibrations).toBe(0);
+ expect(state.firstCapture?.probeSession).toBe(state.sessions[0]);
+});
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index 6e95a1f072..c86407d7c9 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -68,6 +68,8 @@ import {
type ExtractionPhaseBreakdown,
type VideoFrameFormat,
closeCaptureSession,
+ createCaptureSession,
+ initializeSession,
type CaptureOptions,
type CaptureVideoMetadataHint,
type SubTimelineWaitMemo,
@@ -2155,6 +2157,11 @@ export function shouldPreferSingleWorkerDrawElement(args: {
);
}
+/** The session ran the engine's init-time drawElement gates and one refused it. */
+function isProbeDeGated(session: CaptureSession | null): session is CaptureSession {
+ return session !== null && session.captureMode !== "drawelement" && !session.deInitDeferred;
+}
+
/**
* Plan the self-verify retry for an inverted render: the inversion bet on
* drawElement and lost, so the re-render returns to the pre-inversion parallel
@@ -3645,10 +3652,7 @@ async function executeRenderPipeline(input: {
singleWorkerStreamingOk: shouldUseStreamingEncode(cfg, outputFormat, 1, job.duration),
layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
supersampling: deviceScaleFactor !== 1,
- probeDeGated:
- probeSession !== null &&
- probeSession.captureMode !== "drawelement" &&
- !probeSession.deInitDeferred,
+ probeDeGated: isProbeDeGated(probeSession),
experimentalParallelDeOptIn:
process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" ||
// Verified parallel DE streaming (opt-in) wants its parallelism kept.
@@ -3668,14 +3672,14 @@ async function executeRenderPipeline(input: {
// inverted", and emitting it now is what establishes the DiD cohort
// before the flip. Do not short-circuit this block behind
// `deShortBandRoute` (review nit).
- const deShortBand = resolveDeShortBand({
+ let deShortBand = resolveDeShortBand({
invertAtBaseFloor,
invertAtBandFloor,
bandEnabled: deShortBandEnabled,
bandOpen: deShortBandOpen,
elementCountSource: compositionElementCountSource,
});
- const deInversionEligible =
+ let deInversionEligible =
deShortBandRoute && deShortBand === "applied" ? invertAtBandFloor : invertAtBaseFloor;
// The floor that actually decided this render — for the human-facing log
// below, so it never claims e.g. "400 frames >= 900" for a band-routed
@@ -3727,7 +3731,7 @@ async function executeRenderPipeline(input: {
const deParallelMinMemoryMb = Number.isFinite(deParallelMinMemNum)
? deParallelMinMemNum
: 24576;
- const deParallelRouterEligible = shouldPreferParallelDrawElement({
+ let deParallelRouterEligible = shouldPreferParallelDrawElement({
workerCount: WOULD_RESOLVE_MULTI_WORKER,
requestedWorkers: job.config.workers,
useDrawElement: cfg.useDrawElement,
@@ -3738,10 +3742,7 @@ async function executeRenderPipeline(input: {
minFrames: deParallelMinFrames,
layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
supersampling: deviceScaleFactor !== 1,
- probeDeGated:
- probeSession !== null &&
- probeSession.captureMode !== "drawelement" &&
- !probeSession.deInitDeferred,
+ probeDeGated: isProbeDeGated(probeSession),
experimentalParallelDeOptIn:
process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" ||
process.env.HF_DE_PARALLEL_STREAM === "true",
@@ -3759,6 +3760,40 @@ async function executeRenderPipeline(input: {
totalMemoryMb: Math.round(totalmem() / (1024 * 1024)),
minMemoryMb: deParallelMinMemoryMb,
});
+ // The browser probe is conditional, so most renders arrive here without the engine's
+ // init-time drawElement gates having run. Run them before pinning 1 or 3 workers: a
+ // refused comp captures by screenshot and keeps the resolver's parallelism.
+ if (probeSession === null && (deInversionEligible || deParallelRouterEligible)) {
+ try {
+ probeSession = await createCaptureSession(
+ activeFileServer.url,
+ framesDir,
+ buildCaptureOptions(),
+ null,
+ { ...cfg, forceScreenshot: captureForceScreenshot },
+ );
+ await initializeSession(probeSession);
+ } catch (error) {
+ assertNotAborted();
+ if (probeSession) {
+ lastBrowserConsole = probeSession.browserConsoleBuffer;
+ await closeCaptureSession(probeSession).catch(() => {});
+ probeSession = null;
+ }
+ // The capture stage opens its own session and owns retrying or failing it.
+ log.warn("[Render] Fast capture gate check failed; routing without it.", {
+ error: error instanceof Error ? error.message : String(error),
+ });
+ }
+ if (isProbeDeGated(probeSession)) {
+ // What both predicates and the band answer for a gated probe.
+ deInversionEligible = false;
+ deParallelRouterEligible = false;
+ deShortBand = undefined;
+ }
+ }
+ // Workers capturing by screenshot report no gate of their own, so carry the probe's.
+ const deProbeGateReason = isProbeDeGated(probeSession) ? probeSession.deGateReason : undefined;
// Declared ahead of resolution (assigned below, after calibration) so
// captureStageObservationData can close over it for the calibration
// stage itself — reads as undefined until resolveRenderWorkerCount runs.
@@ -3891,11 +3926,8 @@ async function executeRenderPipeline(input: {
);
// DE priority inversion — see shouldPreferSingleWorkerDrawElement for the
// policy and benchmark rationale (eligibility resolved above, before
- // calibration). Comps that pass every static check but hit an engine
- // INIT-time gate at capture (css-effects / at-risk, ~1.5% of local
- // renders) render single-worker screenshot streaming — slower than
- // parallel would have been, accepted for the routing win everywhere else.
- // `preRoutingWorkerCount` lets the self-verify retry return to the
+ // calibration; a comp the engine's init-time gates refuse is never
+ // eligible). `preRoutingWorkerCount` lets the self-verify retry return to the
// parallel path when the drawElement bet loses — shared by both the
// inversion and the router below, whichever fires (mutually exclusive).
const preRoutingWorkerCount = workerCount;
@@ -5092,6 +5124,7 @@ async function executeRenderPipeline(input: {
drawElement: {
compileGate: deCompileGate,
clampReason: deClampReason,
+ probeGateReason: deProbeGateReason,
workerInversion: deWorkerInversion,
preInversionWorkers: deWorkerInversion ? preRoutingWorkerCount : undefined,
compositionElementCount,