Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix: preserve motion blur off through cloud render requests (#6087)
Miguel Ángel62252711734a
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdxindex 0a976f2dc6..f8621df07e 100644--- a/docs/packages/cli.mdx+++ b/docs/packages/cli.mdx@@ -2079,6 +2079,7 @@ Render parameters mirror local `hyperframes render` where they overlap:| `--fps` | `30` | Integer, 1–240 || `--quality` | `standard` | `draft`, `standard`, or `high` || `--format` | `mp4` | `mp4`, `webm`, or `mov` |+| `--page-motion-blur` | current cloud behavior | Pass `off` to disable authored page motion blur. Omit to preserve current behavior. Sends the public API field `page_motion_blur: "off"`. || `--resolution` | `1080p` | `1080p` or `4k`. 4k bills at 1.5×. || `--aspect-ratio` | auto | `16:9`, `9:16`, or `1:1`. Auto-detected from a local project's `data-width` and `data-height`, so you rarely need it. The renderer cannot reshape a composition — a value that disagrees with the authored ratio is an error. With `--asset-id` or `--url` the server defaults to `16:9`. || `--composition` / `-c` | `index.html` | Entry HTML file inside the zip |diff --git a/packages/aws-lambda/src/sdk/validateConfig.test.ts b/packages/aws-lambda/src/sdk/validateConfig.test.tsindex 8edba86ae1..4806691e00 100644--- a/packages/aws-lambda/src/sdk/validateConfig.test.ts+++ b/packages/aws-lambda/src/sdk/validateConfig.test.ts@@ -31,6 +31,7 @@ describe("validateDistributedRenderConfig", () => {codec: "h265",quality: "high",crf: 18,+ pageMotionBlur: "off",chunkSize: 240,maxParallelChunks: 16,runtimeCap: "lambda",@@ -42,6 +43,11 @@ describe("validateDistributedRenderConfig", () => {it.each([["null config", null as unknown as SerializableDistributedRenderConfig, "config"],+ [+ "unsupported page motion blur",+ { ...VALID, pageMotionBlur: "on" as never } satisfies SerializableDistributedRenderConfig,+ "config.pageMotionBlur",+ ],["wrong fps",{ ...VALID, fps: 50 as never } satisfies SerializableDistributedRenderConfig,diff --git a/packages/cli/src/cloud/_gen/client.ts b/packages/cli/src/cloud/_gen/client.tsindex d4b523fd4d..b8863c6de5 100644--- a/packages/cli/src/cloud/_gen/client.ts+++ b/packages/cli/src/cloud/_gen/client.ts@@ -204,7 +204,7 @@ export class HyperframesCloudClient {/*** Upload Asset*- * Uploads a file (image, video, audio, PDF, or SRT subtitle) and returns an asset_id for use in other endpoints. Max 32 MB. Supported types: png, jpeg, mp4, webm, mp3, wav, pdf, srt.+ * Uploads a file (image, video, audio, PDF, or SRT subtitle) and returns an asset_id for use in other endpoints. Max 50 MB, or 32 MB for an image. Supported types: png, jpeg, mp4, webm, mp3, wav, pdf, srt. A file is checked against the content policy after it is uploaded; if it is blocked, the asset is removed and later requests for it return not found.*/async uploadAsset(args: {file: Blob | Buffer | Uint8Array;diff --git a/packages/cli/src/cloud/_gen/types.ts b/packages/cli/src/cloud/_gen/types.tsindex 999e31001d..c2a1d71779 100644--- a/packages/cli/src/cloud/_gen/types.ts+++ b/packages/cli/src/cloud/_gen/types.ts@@ -174,6 +174,16 @@ export interface CreateHyperframesRenderRequest {* Output container/codec.*/format?: "mp4" | "webm" | "mov";+ /**+ * Overrides the quality preset's constant rate factor (lower is higher quality+ * and a larger file). Integer 0-51 for mp4, 0-63 for webm; ignored for mov.+ * Omit to use the preset's CRF.+ */+ crf?: number | null;+ /**+ * Set 'off' to disable page motion blur. Omit or null to keep behavior.+ */+ page_motion_blur?: "off" | null;/*** Output resolution tier. Defaults to '1080p'. Pass '4k' for 4K renders* (billed at 1.5x).@@ -305,6 +315,13 @@ export interface HyperframesRenderDetail {* Error description. Present only when status is 'failed'.*/failure_message?: string | null;+ /**+ * Why billing refused a finished render: 'hf_usage_exhausted',+ * 'hf_subscription_required' or 'api_key_required'. Present only when status+ * is 'failed' for that reason; nothing was charged, so the render can be sent+ * again on a HeyGen API key.+ */+ failure_code?: string | null;}/**@@ -339,6 +356,11 @@ export interface StandardAPIError {* errors by node).*/errors?: Array<StandardAPIErrorDetail>;+ /**+ * Request identifier, also returned in the X-HeyGen-Request-Id response+ * header. Include it when contacting support.+ */+ request_id?: string;}export interface StandardAPIErrorDetail {diff --git a/packages/cli/src/commands/cloud/render.pageMotionBlur.test.ts b/packages/cli/src/commands/cloud/render.pageMotionBlur.test.tsnew file mode 100644index 0000000000..4bcd223a4a--- /dev/null+++ b/packages/cli/src/commands/cloud/render.pageMotionBlur.test.ts@@ -0,0 +1,52 @@+import { runCommand } from "citty";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import render from "./render.js";+import { CliUsageError, consumeCommandResult } from "../../utils/commandResult.js";++const bodies: unknown[] = [];+const baseArgs = ["--asset-id", "asst_fixture", "--no-wait", "--json"];++beforeEach(() => {+ bodies.length = 0;+ vi.stubEnv("HEYGEN_API_KEY", "fixture-key");+ vi.stubEnv("HEYGEN_API_URL", "https://cloud.fixture.invalid");+ vi.spyOn(console, "log").mockImplementation(() => undefined);+ vi.spyOn(console, "error").mockImplementation(() => undefined);+ vi.stubGlobal("fetch", async (url: unknown, init?: RequestInit) => {+ expect(String(url)).toBe("https://cloud.fixture.invalid/v3/hyperframes/renders");+ expect(init?.method).toBe("POST");+ if (typeof init?.body !== "string") throw new Error("Expected a JSON submit body");+ const body: unknown = JSON.parse(init.body);+ bodies.push(body);+ return Response.json({ data: { render_id: "hfr_fixture" } }, { status: 202 });+ });+});++afterEach(() => {+ vi.unstubAllGlobals();+ vi.unstubAllEnvs();+ vi.restoreAllMocks();+ consumeCommandResult();+});++describe("cloud render page motion blur", () => {+ it("writes explicit off into the public API request", async () => {+ await runCommand(render, { rawArgs: [...baseArgs, "--page-motion-blur", "off"] });+ expect(bodies).toHaveLength(1);+ expect(bodies[0]).toHaveProperty("page_motion_blur", "off");+ expect(bodies[0]).not.toHaveProperty("pageMotionBlur");+ });++ it("omits the override when the flag is absent", async () => {+ await runCommand(render, { rawArgs: baseArgs });+ expect(bodies).toHaveLength(1);+ expect(bodies[0]).not.toHaveProperty("page_motion_blur");+ });++ it.each(["on", "false", "", "OFF"])("rejects %j before any cloud request", async (value) => {+ await expect(+ runCommand(render, { rawArgs: [...baseArgs, "--page-motion-blur", value] }),+ ).rejects.toThrow(CliUsageError);+ expect(bodies).toHaveLength(0);+ });+});diff --git a/packages/cli/src/commands/cloud/render.ts b/packages/cli/src/commands/cloud/render.tsindex a43dce0803..87d64ba239 100644--- a/packages/cli/src/commands/cloud/render.ts+++ b/packages/cli/src/commands/cloud/render.ts@@ -118,6 +118,11 @@ export default defineCommand({fps: { type: "string", description: "Frames per second (1-240). Default: 30." },quality: { type: "string", description: "draft | standard | high (default: standard)" },format: { type: "string", description: "mp4 | webm | mov (default: mp4)" },+ "page-motion-blur": {+ type: "string",+ description:+ "Set off to disable authored page motion blur. Omit to keep the current cloud behavior.",+ },resolution: {type: "string",description: "Resolution tier: 1080p | 4k (default: 1080p; 4k is billed at 1.5x)",@@ -214,6 +219,9 @@ export default defineCommand({const fps = parseIntFlag(args.fps, { flag: "--fps", min: 1, max: 240 });const quality = parseEnumFlag(args.quality, VALID_QUALITY, { flag: "--quality" });const format = parseEnumFlag(args.format, VALID_FORMAT, { flag: "--format" });+ const pageMotionBlur = parseEnumFlag(args["page-motion-blur"], ["off"] as const, {+ flag: "--page-motion-blur",+ });const resolution = parseEnumFlag(args.resolution, VALID_RESOLUTION, {flag: "--resolution",});@@ -282,6 +290,7 @@ export default defineCommand({quality,format,resolution,+ pageMotionBlur,aspectRatio,composition: args.composition,variables,@@ -802,6 +811,7 @@ interface SubmitOptions {fps: number | undefined;quality: "draft" | "standard" | "high" | undefined;format: "mp4" | "webm" | "mov" | undefined;+ pageMotionBlur: NonNullable<CreateHyperframesRenderRequest["page_motion_blur"]> | undefined;resolution: CreateHyperframesRenderRequest["resolution"] | undefined;aspectRatio: CreateHyperframesRenderRequest["aspect_ratio"] | undefined;composition: string | undefined;@@ -830,6 +840,7 @@ function buildRenderBody(opts: SubmitOptions): CreateHyperframesRenderRequest {if (opts.fps !== undefined) body.fps = opts.fps;if (opts.quality !== undefined) body.quality = opts.quality;if (opts.format !== undefined) body.format = opts.format;+ if (opts.pageMotionBlur !== undefined) body.page_motion_blur = opts.pageMotionBlur;if (opts.resolution !== undefined) body.resolution = opts.resolution;if (opts.aspectRatio !== undefined) body.aspect_ratio = opts.aspectRatio;if (opts.composition !== undefined) body.composition = opts.composition;diff --git a/packages/producer/README.md b/packages/producer/README.mdindex 515ae7692f..3367179ce8 100644--- a/packages/producer/README.md+++ b/packages/producer/README.md@@ -18,18 +18,13 @@ npm install @hyperframes/producerimport { createRenderJob, executeRenderJob } from "@hyperframes/producer";const job = createRenderJob({- inputPath: "./my-composition.html",- outputPath: "./output.mp4",- width: 1920,- height: 1080,fps: 30,+ quality: "standard",});-const result = await executeRenderJob(job, (progress) => {- console.log(`${Math.round(progress.percent * 100)}%`);+await executeRenderJob(job, "./my-project", "./output.mp4", (currentJob) => {+ console.log(`${Math.round(currentJob.progress)}%`);});--console.log(result.outputPath); // ./output.mp4```### Run as an HTTP server@@ -40,24 +35,27 @@ The producer can also run as a render server, accepting render requests over HTTimport { startServer } from "@hyperframes/producer";await startServer({ port: 8080 });-// POST /render with a RenderConfig body+// POST /render or /render/stream with projectDir, html, or previewUrl and render options```+Both HTTP routes accept optional `pageMotionBlur: "off"` to disable authored page+motion blur. Omit it to preserve the composition's behavior. Other explicit values+are rejected before a render starts. This is separate from engine sub-frame+`motionBlur` sampling.+### Configuration`RenderConfig` controls the render pipeline:-| Option | Default | Description |-| ------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| `inputPath` | — | Path to the HTML composition |-| `outputPath` | — | Output video file path (or directory, for `format: "png-sequence"` and `format: "hls"`) |-| `width` | 1920 | Frame width in pixels |-| `height` | 1080 | Frame height in pixels |-| `fps` | 30 | Frames per second (24, 30, or 60) |-| `quality` | `"standard"` | Encoder preset (`"draft"`, `"standard"`, `"high"`) |-| `format` | `"mp4"` | Output container — `"mp4"`, `"webm"`, `"mov"`, `"gif"`, `"png-sequence"`, or `"hls"`. See [Transparent Video Output](#transparent-video-output) and [HLS Output](#hls-output) below. |-| `hlsSegmentSeconds` | `4` | HLS target segment length in whole seconds. Ignored for every other format. |-| `videoFrameFormat` | `"auto"` | Source video frame extraction format — `"auto"`, `"jpg"`, or `"png"`. Use `"png"` for UI recordings, screen captures, and color-sensitive source videos. |+| Option | Default | Description |+| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `entryFile` | `index.html` | Entry composition inside the project directory. Its authored dimensions set the canvas size. |+| `fps` | required | Frame rate as an integer or exact `{ num, den }` rational. |+| `quality` | required | Encoder preset (`"draft"`, `"standard"`, `"high"`). |+| `pageMotionBlur` | authored setting | Set `"off"` to disable page motion blur; omit to preserve authored behavior. |+| `format` | `"mp4"` | Output container — `"mp4"`, `"webm"`, `"mov"`, `"gif"`, `"png-sequence"`, or `"hls"`. See [Transparent Video Output](#transparent-video-output) and [HLS Output](#hls-output) below. |+| `hlsSegmentSeconds` | `4` | HLS target segment length in whole seconds. Ignored for every other format. |+| `videoFrameFormat` | `"auto"` | Source video frame extraction format — `"auto"`, `"jpg"`, or `"png"`. Use `"png"` for UI recordings, screen captures, and color-sensitive source videos. |## Transparent Video Output@@ -68,7 +66,7 @@ The producer can render HTML compositions to formats that carry a **true alpha c| `"mp4"` (default) | H.264 (yuv420p) or H.265 + HDR10 | No | AAC | Streaming, social, default deliverable || `"webm"` | VP9 + yuva420p | **True alpha** | Opus | Web playback as overlay (`<video>` over background); supported in Chrome, Edge, Firefox || `"mov"` | ProRes 4444 + yuva444p10le | **True alpha + 10-bit** | AAC | Editor ingest (Premiere, Final Cut Pro, DaVinci Resolve) |-| `"png-sequence"` | Numbered RGBA PNGs in a directory | **Lossless alpha** | Sidecar `audio.aac` | After Effects / Nuke / Fusion, or pipelines that post-process frames before encoding |+| `"png-sequence"` | Numbered RGBA PNGs in a directory | **Lossless alpha** | Sidecar `audio.m4a` | After Effects / Nuke / Fusion, or pipelines that post-process frames before encoding || `"hls"` | H.264 (yuv420p) in MPEG-TS | No | AAC rendition | VOD streaming — see [HLS Output](#hls-output) |### Example@@ -77,15 +75,12 @@ The producer can render HTML compositions to formats that carry a **true alpha cimport { createRenderJob, executeRenderJob } from "@hyperframes/producer";const job = createRenderJob({- inputPath: "./my-composition.html",- outputPath: "./output.webm", // or a directory for "png-sequence"- width: 1080,- height: 1920,fps: 30,+ quality: "standard",format: "webm", // "mp4" | "webm" | "mov" | "png-sequence"});-await executeRenderJob(job);+await executeRenderJob(job, "./my-project", "./output.webm");```### What "transparent background" means here@@ -102,7 +97,7 @@ This is not chroma keying. There is no green/blue background to remove and no "k- **Linux + alpha forces screenshot capture.** Chrome's BeginFrame compositor (the default deterministic capture path on Linux headless-shell) does not preserve alpha; the orchestrator falls back to `Page.captureScreenshot`, which is slower per frame. macOS and Windows already use screenshot mode by default, so they are unaffected.- **HDR + alpha is not supported.** Setting `hdr: true` together with an alpha-capable format logs a warning and falls back to SDR. Use `format: "mp4"` for HDR10 output.-- **`png-sequence` does not produce a single muxed file.** When the composition contains audio elements, an `audio.aac` sidecar is written alongside the PNGs in `outputPath`.+- **`png-sequence` does not produce a single muxed file.** When the composition contains audio elements, an `audio.m4a` sidecar is written alongside the PNGs in `outputPath`.- **Safari + WebM alpha is incomplete.** For broad browser playback of an alpha video, ship `format: "mov"` to your editor and re-encode for the codec your distribution target supports.### Authoring transparent compositions@@ -124,11 +119,12 @@ audio_00000.ts```typescriptconst job = createRenderJob({- inputPath: "./my-composition.html",- outputPath: "./renders/stream",+ fps: 30,+ quality: "standard",format: "hls",hlsSegmentSeconds: 4,});+await executeRenderJob(job, "./my-project", "./renders/stream");```Segments are exactly `hlsSegmentSeconds` long except the last: the encoder's GOP@@ -181,7 +177,7 @@ The activity functions plus their result types are also re-exported from `@hyper1. **Serve** — spins up a local file server for the HTML composition2. **Capture** — opens the page in headless Chrome, seeks frame-by-frame via `HeadlessExperimental.beginFrame` (or `Page.captureScreenshot` for transparent / non-Linux renders), captures screenshots3. **Encode** — pipes frames through FFmpeg (with GPU encoder detection and chunked concat). Skipped for `format: "png-sequence"`.-4. **Mix** — extracts `<audio>` elements and mixes them into the final video. For `png-sequence`, audio is written as an `audio.aac` sidecar.+4. **Mix** — extracts `<audio>` elements and mixes them into the final video. For `png-sequence`, audio is written as an `audio.m4a` sidecar.5. **Finalize** — applies faststart for streaming-friendly MP4 (no-op for WebM, MOV, and `png-sequence`). For `hls`, stream-copies the encode into playlists and MPEG-TS segments instead.### Where each step livesdiff --git a/packages/producer/src/renderRequest.test.ts b/packages/producer/src/renderRequest.test.tsindex 96ffd04f19..ae1020457d 100644--- a/packages/producer/src/renderRequest.test.ts+++ b/packages/producer/src/renderRequest.test.ts@@ -50,6 +50,20 @@ function request() {}describe("RenderRequest", () => {+ it("preserves explicit motion blur off through the distributed request round trip", () => {+ const value = request();+ value.options.pageMotionBlur = "off";+ const config = distributedConfigFromRequest(value);+ expect(config.pageMotionBlur).toBe("off");+ expect(+ renderRequestFromDistributedConfig({+ projectDir: value.projectDir,+ outputPath: value.outputPath,+ config,+ }).options.pageMotionBlur,+ ).toBe("off");+ });+it("round-trips through JSON without dropping nested options", () => {const value = request();expect(parseRenderRequest(serializeRenderRequest(value))).toEqual(value);diff --git a/packages/producer/src/renderRequest.ts b/packages/producer/src/renderRequest.tsindex 5c5630887a..80f4de504b 100644--- a/packages/producer/src/renderRequest.ts+++ b/packages/producer/src/renderRequest.ts@@ -299,6 +299,7 @@ export function distributedConfigFromRequest(codec: distributed.codec,quality: options.quality,crf: options.crf,+ pageMotionBlur: options.pageMotionBlur,bitrate: options.videoBitrate,videoFrameFormat: options.videoFrameFormat,outputResolution: options.outputResolution,@@ -354,6 +355,7 @@ export function renderRequestFromDistributedConfig(input: {format: config.format,distributed,...optionalProperty("crf", config.crf),+ ...optionalProperty("pageMotionBlur", config.pageMotionBlur),...optionalProperty("videoBitrate", config.bitrate),...optionalProperty("videoFrameFormat", config.videoFrameFormat),...optionalProperty("outputResolution", config.outputResolution),diff --git a/packages/producer/src/server.encoderOptions.test.ts b/packages/producer/src/server.encoderOptions.test.tsindex 86064c0f3b..92445912ed 100644--- a/packages/producer/src/server.encoderOptions.test.ts+++ b/packages/producer/src/server.encoderOptions.test.ts@@ -62,6 +62,24 @@ describe.each(ROUTES)("POST %s — encoder options", (path) => {expect(capturedRenderConfigs).toHaveLength(0);}+ it("preserves explicit page motion blur off in the render config", async () => {+ const response = await requestRender(path, { pageMotionBlur: "off" });+ expect(response.status).toBe(200);+ expect(capturedRenderConfigs[0]?.pageMotionBlur).toBe("off");+ });++ it("keeps page motion blur unspecified when omitted", async () => {+ await requestRender(path, {});+ expect(capturedRenderConfigs[0]).not.toHaveProperty("pageMotionBlur");+ });++ it.each(["on", "", true, false, null, 0])(+ "rejects invalid page motion blur %j",+ async (value) => {+ await expectRejected({ pageMotionBlur: value }, "pageMotionBlur must be off when supplied");+ },+ );+it("sends no encoder overrides when none are requested", async () => {const response = await requestRender(path, { quality: "high" });diff --git a/packages/producer/src/server.ts b/packages/producer/src/server.tsindex 1a7ad26d95..79a8acbe71 100644--- a/packages/producer/src/server.ts+++ b/packages/producer/src/server.ts@@ -84,6 +84,7 @@ interface RenderInput {quality: "draft" | "standard" | "high";format?: "mp4" | "webm" | "mov";videoFrameFormat?: RenderConfig["videoFrameFormat"];+ pageMotionBlur?: RenderConfig["pageMotionBlur"];outputDynamicRange?: "auto" | "hdr" | "sdr";workers?: number;crf?: number;@@ -317,6 +318,7 @@ function buildRenderJobConfig(input: RenderInput, outputPath: string, log: ProduoutputResolution: input.outputResolution,outputResolutionAspectAgnostic: input.outputResolutionAspectAgnostic,videoFrameFormat: input.videoFrameFormat,+ pageMotionBlur: input.pageMotionBlur,hdrMode: toRenderHdrMode(input.outputDynamicRange),},});@@ -456,7 +458,11 @@ export async function prepareRenderBody(const overrideError = validateRenderOverrides(body);if (overrideError) return { error: overrideError };- const options = parseRenderOptions(body);+ const pageMotionBlur = body.pageMotionBlur;+ if (pageMotionBlur !== undefined && pageMotionBlur !== "off") {+ return { error: "pageMotionBlur must be off when supplied" };+ }+ const options: Omit<RenderInput, "projectDir"> = { ...parseRenderOptions(body), pageMotionBlur };const project = prepareProjectDirectory(body.projectDir, options);if (project) return project;const source = await resolveInlineRenderHtml(body);diff --git a/packages/producer/src/services/distributed/chunkFrames.test.ts b/packages/producer/src/services/distributed/chunkFrames.test.tsindex ce1b2dc710..1780603902 100644--- a/packages/producer/src/services/distributed/chunkFrames.test.ts+++ b/packages/producer/src/services/distributed/chunkFrames.test.ts@@ -9,6 +9,15 @@ const input = {};describe("buildChunkCaptureOptions", () => {+ it("honors the explicit off value frozen by the planner", () => {+ expect(+ buildChunkCaptureOptions({+ ...input,+ encoder: { ...input.encoder, pageMotionBlur: "off" },+ }).pageMotionBlur,+ ).toBe("off");+ });+it("turns the page's capture motion blur off: a distributed render has no preview to match (R19)", () => {expect(buildChunkCaptureOptions(input).pageMotionBlur).toBe("distributed-render");});diff --git a/packages/producer/src/services/distributed/chunkFrames.ts b/packages/producer/src/services/distributed/chunkFrames.tsindex ebc46d1578..2a29f9b959 100644--- a/packages/producer/src/services/distributed/chunkFrames.ts+++ b/packages/producer/src/services/distributed/chunkFrames.ts@@ -145,7 +145,10 @@ export function buildChunkCaptureOptions(input: {fpsDen: number;format: DistributedFormat;};- encoder: Pick<LockedRenderConfig, "quality" | "deviceScaleFactor" | "variables">;+ encoder: Pick<+ LockedRenderConfig,+ "quality" | "deviceScaleFactor" | "variables" | "pageMotionBlur"+ >;videoCount: number;html: string;skipReadinessVideoIds?: string[];@@ -168,7 +171,7 @@ export function buildChunkCaptureOptions(input: {...(videoCaptureBeyondViewport !== undefined? { captureBeyondViewport: videoCaptureBeyondViewport }: {}),- pageMotionBlur: "distributed-render",+ pageMotionBlur: encoder.pageMotionBlur ?? "distributed-render",// A fixed warmup count keeps `beginFrameTimeTicks` host-independent.lockWarmupTicks: true,requiresWebGpu: compositionRequiresWebGpu(input.html),diff --git a/packages/producer/src/services/distributed/plan.test.ts b/packages/producer/src/services/distributed/plan.test.tsindex df4a8189a3..f277e903ce 100644--- a/packages/producer/src/services/distributed/plan.test.ts+++ b/packages/producer/src/services/distributed/plan.test.ts@@ -1361,6 +1361,23 @@ describe("plan() — codec knob", () => {});});+describe("plan() motion blur intent", () => {+ it("freezes explicit off into the plan identity while omission preserves the old plan", async () => {+ const base = { fps: 30 as const, width: 320, height: 240, format: "mp4" as const };+ const ordinaryDir = join(runRoot, "motion-blur-omitted");+ const offDir = join(runRoot, "motion-blur-off");+ mkdirSync(ordinaryDir, { recursive: true });+ mkdirSync(offDir, { recursive: true });+ const ordinary = await plan(projectDir, base, ordinaryDir);+ const off = await plan(projectDir, { ...base, pageMotionBlur: "off" }, offDir);+ const encoder = (dir: string) =>+ JSON.parse(readFileSync(join(dir, "meta", "encoder.json"), "utf-8"));+ expect(encoder(ordinaryDir)).not.toHaveProperty("pageMotionBlur");+ expect(encoder(offDir).pageMotionBlur).toBe("off");+ expect(off.planHash).not.toBe(ordinary.planHash);+ }, 30_000);+});+describe("plan() — variables", () => {const TIMEOUT_MS = 30_000;diff --git a/packages/producer/src/services/distributed/plan.ts b/packages/producer/src/services/distributed/plan.tsindex 8e1465e394..69d2e0c1d9 100644--- a/packages/producer/src/services/distributed/plan.ts+++ b/packages/producer/src/services/distributed/plan.ts@@ -98,6 +98,7 @@ import {readFfmpegVersion,readProducerVersion,} from "./shared.js";+import type { RenderRequestOptions } from "../../renderRequest.js";import { writeChunkAudioSlices } from "./chunkAudio.js";import { PLAN_PROTOCOL_V1, type PlanProtocolV1Descriptor } from "./planProtocol.js";import {@@ -111,7 +112,7 @@ import {* `height`, and `format` are required; everything else carries a default* sensible for AWS Lambda fan-out.*/-export interface DistributedRenderConfig {+export interface DistributedRenderConfig extends Pick<RenderRequestOptions, "pageMotionBlur"> {/** Integer frame rate. Distributed renders only accept integer fps; the in-process renderer's `Fps` rational handles NTSC. */fps: DistributedFps;width: number;@@ -915,6 +916,7 @@ function buildLockedRenderConfig(input: {chunkCount: input.chunkCount,runtimeEnv: input.runtimeEnv,variables: config.variables,+ pageMotionBlur: config.pageMotionBlur,...(input.chunksCarryAudio ? { chunksCarryAudio: true } : {}),...(input.separateAudio ? { separateAudio: true } : {}),};diff --git a/packages/producer/src/services/distributed/renderConfigValidation.ts b/packages/producer/src/services/distributed/renderConfigValidation.tsindex 699475e553..8f579c4ce3 100644--- a/packages/producer/src/services/distributed/renderConfigValidation.ts+++ b/packages/producer/src/services/distributed/renderConfigValidation.ts@@ -89,6 +89,10 @@ export function validateDistributedRenderConfig(validateIntDimension("config.width", config.width);validateIntDimension("config.height", config.height);+ if (config.pageMotionBlur !== undefined && config.pageMotionBlur !== "off") {+ throw new InvalidConfigError("config.pageMotionBlur", 'must be "off" when provided');+ }+if (!ALLOWED_FORMATS.includes(config.format)) {throw new InvalidConfigError("config.format",diff --git a/packages/producer/src/services/render/stages/freezePlan.ts b/packages/producer/src/services/render/stages/freezePlan.tsindex b155fb3b4d..5f608bca62 100644--- a/packages/producer/src/services/render/stages/freezePlan.ts+++ b/packages/producer/src/services/render/stages/freezePlan.ts@@ -14,6 +14,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } fromimport { join, relative, resolve } from "node:path";import type { Fps } from "@hyperframes/core";+import type { RenderRequestOptions } from "../../../renderRequest.js";import { PLAN_PROTOCOL_V1 } from "../../distributed/planProtocol.js";import {canonicalJsonStringify,@@ -27,7 +28,7 @@ import {/*** The encoder configuration locked in at plan time.*/-export interface LockedRenderConfig {+export interface LockedRenderConfig extends Pick<RenderRequestOptions, "pageMotionBlur"> {// CapturecaptureMode: "beginframe" | "screenshot";forceScreenshot: boolean;diff --git a/packages/studio-server/src/routes/render.test.ts b/packages/studio-server/src/routes/render.test.tsindex 75adffe67f..612a28936f 100644--- a/packages/studio-server/src/routes/render.test.ts+++ b/packages/studio-server/src/routes/render.test.ts@@ -813,6 +813,41 @@ describe("POST /projects/:id/render — telemetryDistinctId forwarding", () => {}});+ it("preserves explicit page motion blur off over preview capability", async () => {+ const spy = vi.fn();+ const { app, cleanup } = buildApp(spy);+ try {+ const res = await app.request("http://localhost/projects/demo/render", {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ pageMotionBlur: "off", previewMotionBlur: true }),+ });+ expect(res.status).toBe(200);+ expect(spy.mock.calls[0][0].pageMotionBlur).toBe("off");+ } finally {+ cleanup();+ }+ });++ it.each(["on", "", false, true, null, 0])(+ "rejects invalid page motion blur %s before starting a render",+ async (pageMotionBlur) => {+ const spy = vi.fn();+ const { app, cleanup } = buildApp(spy);+ try {+ const res = await app.request("http://localhost/projects/demo/render", {+ method: "POST",+ headers: { "content-type": "application/json" },+ body: JSON.stringify({ pageMotionBlur }),+ });+ expect(res.status).toBe(400);+ expect(spy).not.toHaveBeenCalled();+ } finally {+ cleanup();+ }+ },+ );+// An old client omits the flag, and a non-boolean is not a signal either.// Defaulting those to "opted out" would silently drop every pre-upgrade// render outcome.diff --git a/packages/studio-server/src/routes/render.ts b/packages/studio-server/src/routes/render.tsindex b041957c94..228ecf6bce 100644--- a/packages/studio-server/src/routes/render.ts+++ b/packages/studio-server/src/routes/render.ts@@ -109,6 +109,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): voidvariables?: Record<string, unknown>;gpu?: boolean;previewMotionBlur?: boolean;+ pageMotionBlur?: unknown;};const VALID_FORMATS = new Set(["mp4", "webm", "mov"]);const FORMAT_EXT: Record<string, string> = { mp4: ".mp4", webm: ".webm", mov: ".mov" };@@ -151,6 +152,15 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): voidconst encoder = parseEncoderOptions(body, format);if (!encoder.ok) return c.json({ error: encoder.error }, 400);+ const requestedPageMotionBlur = body.pageMotionBlur;+ if (requestedPageMotionBlur !== undefined && requestedPageMotionBlur !== "off") {+ return c.json({ error: "pageMotionBlur must be off when supplied" }, 400);+ }+ const pageMotionBlur =+ requestedPageMotionBlur === undefined && body.previewMotionBlur === false+ ? "off"+ : requestedPageMotionBlur;+const now = new Date();const jobId = `${project.id}_${formatRenderOutputTimestamp(now)}`;const rendersDir = adapter.rendersDir(project);@@ -173,7 +183,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): voiddistinctId:typeof body.telemetryDistinctId === "string" ? body.telemetryDistinctId : undefined,telemetryOptOut: body.telemetryOptOut === true,- ...(body.previewMotionBlur === false ? { pageMotionBlur: "off" as const } : {}),+ ...(pageMotionBlur === undefined ? {} : { pageMotionBlur }),});(jobState as RenderJobState & { createdAt: number }).createdAt = Date.now();renderJobs.set(jobId, jobState as RenderJobState & { createdAt: number });