Skip to content

Write HTML. Render video. Built for agents.

fix: preserve motion blur off through cloud render requests (#6087)

Miguel Ángel62252711734a
diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.md
index 515ae7692f..3367179ce8 100644
--- a/packages/producer/README.md
+++ b/packages/producer/README.md
@@ -18,18 +18,13 @@ npm install @hyperframes/producer
import { 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 HTT
import { 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 c
import { 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
```typescript
const 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 `@hyper
1. **Serve** — spins up a local file server for the HTML composition
2. **Capture** — opens the page in headless Chrome, seeks frame-by-frame via `HeadlessExperimental.beginFrame` (or `Page.captureScreenshot` for transparent / non-Linux renders), captures screenshots
3. **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 lives
diff --git a/packages/producer/src/renderRequest.test.ts b/packages/producer/src/renderRequest.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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: Produ
outputResolution: 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 } from
import { 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"> {
// Capture
captureMode: "beginframe" | "screenshot";
forceScreenshot: boolean;
diff --git a/packages/studio-server/src/routes/render.test.ts b/packages/studio-server/src/routes/render.test.ts
index 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.ts
index 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): void
variables?: 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): void
const 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): void
distinctId:
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 });