Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(producer): stop JPEG frame capture adding colour noise to graded footage (#5514)
Miguel Ángelf073281bd9e8
diff --git a/packages/producer/src/services/distributed/renderChunk.ts b/packages/producer/src/services/distributed/renderChunk.tsindex e4796427e2..44c5cbdc80 100644--- a/packages/producer/src/services/distributed/renderChunk.ts+++ b/packages/producer/src/services/distributed/renderChunk.ts@@ -69,6 +69,7 @@ import { applyRenderWarningPolicy } from "../renderOrchestrator.js";import { runEncodeStage } from "../render/stages/encodeStage.js";import { runCaptureStage } from "../render/stages/captureStage.js";import { resolveVideoCaptureBeyondViewport } from "../render/captureBeyondViewport.js";+import { resolveCaptureJpegQuality } from "../render/captureImageFormat.js";import { createCapturePlan } from "../render/capturePlan.js";import {type ChunkSliceJson,@@ -819,7 +820,10 @@ export async function renderChunk(height: plan.dimensions.height,fps: { num: plan.dimensions.fpsNum, den: plan.dimensions.fpsDen },format: plan.dimensions.format === "mp4" ? "jpeg" : "png",- quality: plan.dimensions.format === "mp4" ? 80 : undefined,+ quality:+ plan.dimensions.format === "mp4"+ ? resolveCaptureJpegQuality(job.config.quality)+ : undefined,deviceScaleFactor: encoder.deviceScaleFactor,// Re-inject the controller's snapshotted variables so the chunk's// first capture sees the same `window.__hfVariables` the in-processdiff --git a/packages/producer/src/services/render/captureImageFormat.test.ts b/packages/producer/src/services/render/captureImageFormat.test.tsindex c6a8af1c3b..e7b663ca93 100644--- a/packages/producer/src/services/render/captureImageFormat.test.ts+++ b/packages/producer/src/services/render/captureImageFormat.test.ts@@ -1,6 +1,6 @@import { describe, expect, it } from "bun:test";import { frameFileExtension } from "@hyperframes/engine";-import { resolveCaptureImageFormat } from "./captureImageFormat.js";+import { resolveCaptureImageFormat, resolveCaptureJpegQuality } from "./captureImageFormat.js";describe("resolveCaptureImageFormat", () => {it("captures JPEG for an ordinary opaque render", () => {@@ -27,3 +27,14 @@ describe("resolveCaptureImageFormat", () => {}});});++describe("resolveCaptureJpegQuality", () => {+ it("captures standard and high renders at quality 100 so graded colour survives", () => {+ expect(resolveCaptureJpegQuality("standard")).toBe(100);+ expect(resolveCaptureJpegQuality("high")).toBe(100);+ });++ it("keeps draft renders on the smaller, faster frames", () => {+ expect(resolveCaptureJpegQuality("draft")).toBe(80);+ });+});diff --git a/packages/producer/src/services/render/captureImageFormat.ts b/packages/producer/src/services/render/captureImageFormat.tsindex 1b4cb96575..44074d95c3 100644--- a/packages/producer/src/services/render/captureImageFormat.ts+++ b/packages/producer/src/services/render/captureImageFormat.ts@@ -1,4 +1,4 @@-import type { MotionBlurOptions } from "@hyperframes/engine";+import type { EngineConfig, MotionBlurOptions } from "@hyperframes/engine";/*** The format a render captures its frames in.@@ -19,3 +19,11 @@ export function resolveCaptureImageFormat(input: {}): "jpeg" | "png" {return input.needsAlpha || input.motionBlur ? "png" : "jpeg";}++/**+ * Below 100, Chrome's JPEG turns graded colour and grain into 8x8 chroma blotches that survive+ * the final encode. Draft keeps the smaller, faster frames.+ */+export function resolveCaptureJpegQuality(quality: EngineConfig["quality"]): number {+ return quality === "draft" ? 80 : 100;+}diff --git a/packages/producer/src/services/render/segmentManifest.test.ts b/packages/producer/src/services/render/segmentManifest.test.tsindex 1c2469671f..5ac7ada268 100644--- a/packages/producer/src/services/render/segmentManifest.test.ts+++ b/packages/producer/src/services/render/segmentManifest.test.ts@@ -31,6 +31,7 @@ const hashInput: SegmentPlanHashInput = {outputWidth: 1920,outputHeight: 1080,motionBlur: "",+ captureQuality: 80,};describe("computeSegmentPlanHash", () => {@@ -68,6 +69,7 @@ describe("computeSegmentPlanHash", () => {expect(computeSegmentPlanHash({ ...hashInput, motionBlur: '{"samplesPerFrame":32}' })).not.toBe(a,);+ expect(computeSegmentPlanHash({ ...hashInput, captureQuality: 100 })).not.toBe(a);});it("does not collide across adjacent field boundaries", () => {diff --git a/packages/producer/src/services/render/segmentManifest.ts b/packages/producer/src/services/render/segmentManifest.tsindex 5e7203fa77..03d2bf6795 100644--- a/packages/producer/src/services/render/segmentManifest.ts+++ b/packages/producer/src/services/render/segmentManifest.ts@@ -48,6 +48,7 @@ export interface SegmentPlanHashInput {outputHeight: number;/** Serialised motion-blur options, or "" when off; sample count and shutter change every pixel. */motionBlur: string;+ captureQuality: number | undefined;}const MANIFEST_FILENAME = "segments.json";@@ -70,6 +71,7 @@ export function computeSegmentPlanHash(input: SegmentPlanHashInput): string {input.useGpu ? "gpu" : "cpu",`${input.outputWidth}x${input.outputHeight}`,input.motionBlur,+ input.captureQuality === undefined ? "" : String(input.captureQuality),].join(" ");return createHash("sha256").update(ordered).digest("hex").slice(0, 16);}diff --git a/packages/producer/src/services/render/stages/captureStage.test.ts b/packages/producer/src/services/render/stages/captureStage.test.tsindex 46d6ee16b1..f8341a8cd3 100644--- a/packages/producer/src/services/render/stages/captureStage.test.ts+++ b/packages/producer/src/services/render/stages/captureStage.test.ts@@ -80,6 +80,12 @@ describe("disk capture capacity", () => {expect(estimateDiskCaptureBytes(10, captureOptions)).toBe(100_000);});+ it("allows for the larger frames of jpeg above draft quality", () => {+ expect(estimateDiskCaptureBytes(10, { ...captureOptions, quality: 80 })).toBe(100_000);+ expect(estimateDiskCaptureBytes(10, { ...captureOptions, quality: 95 })).toBe(200_000);+ expect(estimateDiskCaptureBytes(10, { ...captureOptions, quality: 100 })).toBe(200_000);+ });+it("fails before capture when estimated frames exceed available headroom", () => {expect(() =>assertDiskCaptureHeadroom("/render/captured-frames", 10, pngOptions, () => 800_000),diff --git a/packages/producer/src/services/render/stages/captureStage.ts b/packages/producer/src/services/render/stages/captureStage.tsindex 7b43ff53f8..21f4a19238 100644--- a/packages/producer/src/services/render/stages/captureStage.ts+++ b/packages/producer/src/services/render/stages/captureStage.ts@@ -142,8 +142,10 @@ export function shouldAllowAdaptiveCaptureRetry(return workerCount > 1;}-/** Jpeg frames are far smaller than raw pixels; this divisor is a conservative bound. */+/** Jpeg frames are far smaller than raw pixels; these divisors are conservative bounds. */const JPEG_RAW_RGBA_DIVISOR = 8;+/** Above draft's quality 80; quality-100 jpeg of grainy 4K footage measures about 1/6 of raw RGBA. */+const HIGH_QUALITY_JPEG_RAW_RGBA_DIVISOR = 4;/** Frames captured before the measured projection replaces the static estimate. */const DISK_PROJECTION_SAMPLE_FRAMES = 10;@@ -156,7 +158,12 @@ export function estimateDiskCaptureBytes(const outputHeight = Math.ceil(captureOptions.height * scale);const rawBytes = Math.ceil(totalFrames) * outputWidth * outputHeight * 4;return frameFileExtension(captureOptions.format) === "jpg"- ? Math.ceil(rawBytes / JPEG_RAW_RGBA_DIVISOR)+ ? Math.ceil(+ rawBytes /+ ((captureOptions.quality ?? 80) > 80+ ? HIGH_QUALITY_JPEG_RAW_RGBA_DIVISOR+ : JPEG_RAW_RGBA_DIVISOR),+ ): rawBytes;}diff --git a/packages/producer/src/services/render/stages/probeStage.test.ts b/packages/producer/src/services/render/stages/probeStage.test.tsindex 9d2cf6f7d8..45bdddb134 100644--- a/packages/producer/src/services/render/stages/probeStage.test.ts+++ b/packages/producer/src/services/render/stages/probeStage.test.ts@@ -927,6 +927,26 @@ describe("runProbeStage — render variable threading", () => {});});+describe("runProbeStage — capture jpeg quality", () => {+ // A sequential disk render reuses this session for every frame, so its quality is the render's.+ for (const [preset, expected] of [+ ["draft", 80],+ ["standard", 100],+ ["high", 100],+ ] as const) {+ it(`captures ${preset} renders at jpeg quality ${expected}`, async () => {+ capturedOptions.length = 0;+ const { runProbeStage } = await import("./probeStage.js");+ const input = makeProbeInput({ stageForceScreenshot: false });+ input.job.config.quality = preset;++ await runProbeStage(input);++ expect(capturedOptions[0]).toMatchObject({ format: "jpeg", quality: expected });+ });+ }+});+describe("runProbeStage — decimal duration frame count", () => {it("reproduces all 14 cumulative final-frame indices from the field report", async () => {const { runProbeStage } = await import("./probeStage.js");diff --git a/packages/producer/src/services/render/stages/probeStage.ts b/packages/producer/src/services/render/stages/probeStage.tsindex 0203e8f963..5ecff9bd41 100644--- a/packages/producer/src/services/render/stages/probeStage.ts+++ b/packages/producer/src/services/render/stages/probeStage.ts@@ -71,7 +71,7 @@ import {import type { RenderJob } from "../../renderOrchestrator.js";import { isActionableProbeFailure } from "./probeFailures.js";import { preflightCompositionAssetMediaTypes } from "../../assetMediaType.js";-import { resolveCaptureImageFormat } from "../captureImageFormat.js";+import { resolveCaptureImageFormat, resolveCaptureJpegQuality } from "../captureImageFormat.js";export interface ProbeStageInput {projectDir: string;@@ -379,7 +379,8 @@ export async function runProbeStage(input: ProbeStageInput): Promise<ProbeStageRheight,fps: job.config.fps,format: captureFormat,- quality: captureFormat === "png" ? undefined : 80,+ quality:+ captureFormat === "png" ? undefined : resolveCaptureJpegQuality(job.config.quality),variables: job.config.variables,deviceScaleFactor,motionBlur,diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.tsindex f24a81e1ae..414f7d2e50 100644--- a/packages/producer/src/services/renderOrchestrator.ts+++ b/packages/producer/src/services/renderOrchestrator.ts@@ -211,7 +211,10 @@ import { runCaptureHdrStage } from "./render/stages/captureHdrStage.js";import { runEncodeStage } from "./render/stages/encodeStage.js";import { runAssembleStage } from "./render/stages/assembleStage.js";import { shouldUseLayeredComposite } from "./hdrCompositor.js";-import { resolveCaptureImageFormat } from "./render/captureImageFormat.js";+import {+ resolveCaptureImageFormat,+ resolveCaptureJpegQuality,+} from "./render/captureImageFormat.js";import { assertMotionBlurSupported } from "./render/motionBlurRoute.js";export function sampleDirectoryBytes(dir: string): number {@@ -3471,7 +3474,8 @@ async function executeRenderPipeline(input: {height,fps: job.config.fps,format: captureImageFormat,- quality: captureImageFormat === "png" ? undefined : job.config.quality === "draft" ? 80 : 95,+ quality:+ captureImageFormat === "png" ? undefined : resolveCaptureJpegQuality(job.config.quality),variables: job.config.variables,deviceScaleFactor,motionBlur: job.config.motionBlur,@@ -4438,6 +4442,7 @@ async function executeRenderPipeline(input: {outputWidth: captureCompositionWidth ?? width,outputHeight: captureCompositionHeight ?? height,motionBlur: job.config.motionBlur ? JSON.stringify(job.config.motionBlur) : "",+ captureQuality: captureOptions.quality,});const segmentDir = segmentDirFor(join(projectDir, "renders"), segmentPlanHash);let completedSegments: ReadonlySet<number> = new Set<number>();