Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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,