Skip to content

Commit c38ac54

Browse files
vanceingallsclaude
andauthored
feat(producer): distributed and range renders honour page motion blur (#7311)
* feat(producer): distributed and range renders honour page motion blur A film with data-motion-blur="on" blurs the same way however it is rendered. plan() no longer forces the synthetic job to pageMotionBlur "off", so the plan locks screenshot capture for a blurred film as a whole render does, and renderChunk() no longer defaults the page's off switch to "distributed-render". An explicit pageMotionBlur "off" in the config still stands the page down. Hosted renders pick this up after the next OSS release and a producer pin bump; a render of a blur-on film that goes distributed changes output then. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> * test(producer): the default tier blurs the same in chunks; docs agree distributed renders blur Two files compare plan -> renderChunk -> assemble with the tier attribute removed, so `auto` (the filter tier) decides, against a whole render: held-card and callbacks (the muted-callback path). The skill's motion reference no longer says distributed renders are off. The rewritten R19 plan test gets 60 s for its three plan() calls. Co-Authored-By: Claude Sonnet 5.5 <[email protected]> --------- Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent e351253 commit c38ac54

22 files changed

Lines changed: 448 additions & 26 deletions

‎docs/guides/motion-blur.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ A page that asks for capture gets the filter tier instead when capture cannot ru
6969

7070
This is decided once for the whole composition, from the first frame. A defect the scan misses (a WebGL canvas added late, say) is caught per frame instead: that one frame is rendered sharp and counted in `failedFrames`.
7171

72-
Blur is off, and stays off, for HDR renders, distributed renders, and renders that use the engine's own sub-frame blur.
72+
Blur is off, and stays off, for HDR renders and renders that use the engine's own sub-frame blur. Distributed renders (`plan`, `renderChunk`, `assemble`, as the AWS Lambda and Google Cloud Run adapters run them) and `--start`/`--end` range renders blur like a whole local render. Pass `--page-motion-blur off` (or `pageMotionBlur: "off"` in a distributed config) to render them sharp.
7373

7474
### Find out which one is drawing
7575

@@ -88,6 +88,7 @@ In the page, `window.__hfMotionBlur.report()` returns `state`, `tier`, `reason`,
8888
## Cost and limits
8989

9090
- **Render time.** It varies by film. On an 8 s test composition with four whips, a render took 9.8 s with capture, 5.2–5.4 s with the filter tier and 5.3–5.9 s with no blur (two runs each, including startup). On two real 1080p films the filter tier cost more than capture, measured as CPU seconds of the whole render (wall time was too noisy on a loaded machine): `spacex-launch` (77 movers, 39.5 s) took 547–552 CPU s with the filter tier, 302–320 with capture and 184–193 with no blur (three runs each, 2.9 times no blur); `k3-promo` (106 movers, 16.5 s) took 236, 205 and 117 (one run per arm, 2.0 times no blur). The two films do not order by mover count, and the cause of the difference was not isolated. The filter tier draws each mover as at least 32 offset copies per frame; capture adds a second paint per blurred frame.
91+
- **Distributed renders.** Blur applies in every chunk, drawn with the filter tier on `auto`. Measured on two real 1080p films with plan, `renderChunk` and assemble at 240 frames per chunk, in a software-GPU Chrome 153 on a machine other work was loading (load average 12 to 25), one run per arm: summed chunk CPU seconds went from 155 to 246 (1.6 times) on `k3-promo` and from 338 to 545 (1.6 times) on `spacex-launch`; summed chunk wall time rose 1.2 and 1.4 times. A film with `data-motion-blur="on"` also plans screenshot capture instead of BeginFrame capture, and the measured cost includes that switch.
9192
- **Editing.** The filter tier never wraps anything. With capture the root is wrapped only while playing or rendering; paused, it is plain DOM, so click-to-select works.
9293
- **Capture only.** Blurred preview can run at half the frame rate on heavy compositions, and a `<video>` drawn through the capture looks about 2–3% darker in the browser editor preview than in normal playback. Renders are not affected.
9394
- **Preview and render.** `auto` draws the same way in both. A page that asks for capture previews with the filter tier in a browser without HTML in Canvas, so a spin or zoom looks softer there than in the render.

‎packages/cli/src/docs/motion-blur.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,6 @@ The same attributes drive the browser editor preview and `hyperframes render`.
2222

2323
- `npx hyperframes check` reports `motion_blur_filter_fallback`, `motion_blur_no_movers` and `motion_blur_unverified`
2424
- `hyperframes render --page-motion-blur off` renders without the composition's blur
25-
- Blur is off for HDR, distributed, and sub-frame-blur renders
25+
- Blur is off for HDR and sub-frame-blur renders; distributed and `--start`/`--end` range renders blur like a whole render
2626

2727
Full guide: https://hyperframes.heygen.com/guides/motion-blur

‎packages/producer/scripts/integration-tests.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,13 @@
99
"src/services/htmlCompiler.heif.test.ts",
1010
"src/services/vfxDeterminism.test.ts",
1111
"src/services/distributed/assemble.test.ts",
12+
"src/services/distributed/blurChunks.callbacks.integration.test.ts",
13+
"src/services/distributed/blurChunks.callbacksFilter.integration.test.ts",
14+
"src/services/distributed/blurChunks.configOff.integration.test.ts",
15+
"src/services/distributed/blurChunks.heldCard.integration.test.ts",
16+
"src/services/distributed/blurChunks.heldCardFilter.integration.test.ts",
17+
"src/services/distributed/blurChunks.onceGuardLabel.integration.test.ts",
18+
"src/services/distributed/blurChunks.scrollList.integration.test.ts",
1219
"src/services/distributed/chunkBoundary.test.ts",
1320
"src/services/distributed/crossWorkerIdempotency.test.ts",
1421
"src/services/distributed/plan.masterBus.test.ts",

‎packages/producer/scripts/run-test-lane.mjs‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,11 @@ const vitestFiles = tests.filter((test) => test.runner === "vitest").map((test)
3232
const vitestEnv = unit
3333
? { NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ""} --import ${noNetwork.href}`.trim() }
3434
: {};
35-
// Files that start many Chromes at once run alone, after the rest: next to them, the Chrome
36-
// node-count assertions in coreRuntimeBrowser.test.ts see a different garbage-collection schedule.
37-
const runsAlone = (file) => /\/blurDifferential(\.\w+)?\.integration\.test\.ts$/.test(file);
35+
// Files that start many Chromes at once run alone, after the rest and one file at a time: next to
36+
// them, the Chrome node-count assertions in coreRuntimeBrowser.test.ts see a different
37+
// garbage-collection schedule.
38+
const runsAlone = (file) =>
39+
/(^|\/)blur(Differential|Chunks)[^/]*\.integration\.test\.ts$/.test(file);
3840
const shared = vitestFiles.filter((file) => !runsAlone(file));
3941
const alone = vitestFiles.filter(runsAlone);
4042
if (shared.length > 0) run(["x", "vitest", "run", ...shared], vitestEnv);
Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
import { spawnSync } from "node:child_process";
2+
import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
5+
import { afterAll, beforeAll, expect } from "vitest";
6+
import { decodePng, getFfmpegBinary, resolveConfig } from "@hyperframes/engine";
7+
import {
8+
compareTiles,
9+
type Differential,
10+
type Rgba,
11+
} from "../../../../../engine/src/services/__fixtures__/blurDifferential.js";
12+
import {
13+
FIXTURES,
14+
type BlurFixture,
15+
} from "../../../../../engine/src/services/__fixtures__/motionBlur/fixtures.js";
16+
import {
17+
INVARIANTS,
18+
RENDER_OUTSIDE_MAX_MAE,
19+
} from "../../../../../engine/src/services/__fixtures__/motionBlur/thresholds.js";
20+
import { createRenderJob, executeRenderJob } from "../../renderOrchestrator.js";
21+
import { assemble } from "../assemble.js";
22+
import { plan, type DistributedRenderConfig } from "../plan.js";
23+
import { renderChunk } from "../renderChunk.js";
24+
25+
export const HAS_FFMPEG =
26+
spawnSync(getFfmpegBinary(), ["-version"], { encoding: "utf-8" }).status === 0;
27+
const FPS = 30;
28+
/** Four workers over 60 frames start at 0, 15, 30 and 45, so no block starts where a 20-frame chunk does. */
29+
export const WHOLE_WORKERS = 4;
30+
const CHUNK_SIZE = 20;
31+
export const RENDER_TIMEOUT_MS = 600_000;
32+
33+
const quietLogger = { info() {}, warn() {}, error() {}, debug() {} };
34+
35+
export const fixtureNamed = (name: string): BlurFixture => {
36+
const f = FIXTURES.find((x) => x.name === name);
37+
if (!f) throw new Error(`missing fixture ${name}`);
38+
return f;
39+
};
40+
41+
/** The fixture with its `data-motion-blur-tier` removed, so `auto` itself picks the tier (the filter tier). */
42+
function withoutTierAttribute(f: BlurFixture): BlurFixture {
43+
const html = (blur: "on" | "off"): string => {
44+
const pinned = f.html(blur);
45+
const stripped = pinned.replace(/ data-motion-blur-tier="[a-z]+"/, "");
46+
if (blur === "on" && stripped === pinned) throw new Error(`${f.name} pins no tier to remove`);
47+
return stripped;
48+
};
49+
return { ...f, html };
50+
}
51+
52+
/** A scratch directory for the suite, whose fontconfig draws grayscale text so DOM glyphs and the capture canvas agree. */
53+
export function useBlurScratch(): () => string {
54+
let root = "";
55+
let prior: string | undefined;
56+
beforeAll(() => {
57+
root = mkdtempSync(join(tmpdir(), "hf-blur-chunks-"));
58+
prior = process.env.FONTCONFIG_FILE;
59+
const conf = join(root, "fonts.conf");
60+
writeFileSync(
61+
conf,
62+
`<?xml version="1.0"?><!DOCTYPE fontconfig SYSTEM "fonts.dtd"><fontconfig>
63+
<include ignore_missing="yes">/etc/fonts/fonts.conf</include>
64+
<match target="font"><edit name="rgba" mode="assign"><const>none</const></edit></match>
65+
</fontconfig>`,
66+
);
67+
process.env.FONTCONFIG_FILE = conf;
68+
});
69+
afterAll(() => {
70+
if (prior === undefined) delete process.env.FONTCONFIG_FILE;
71+
else process.env.FONTCONFIG_FILE = prior;
72+
rmSync(root, { recursive: true, force: true });
73+
});
74+
return () => root;
75+
}
76+
77+
function decodeFrames(dir: string): Rgba[] {
78+
return readdirSync(dir)
79+
.filter((file) => file.endsWith(".png"))
80+
.sort()
81+
.map((file) => decodePng(readFileSync(join(dir, file))));
82+
}
83+
84+
function writeProject(root: string, f: BlurFixture, blur: "on" | "off", tag: string) {
85+
const workDir = join(root, `${f.name}-${tag}`);
86+
const projectDir = join(workDir, "project");
87+
mkdirSync(projectDir, { recursive: true });
88+
writeFileSync(join(projectDir, "index.html"), f.html(blur));
89+
return { workDir, projectDir };
90+
}
91+
92+
/** The normal in-process render: the page's own `data-motion-blur` decides. */
93+
export async function renderWhole(
94+
root: string,
95+
f: BlurFixture,
96+
blur: "on" | "off",
97+
workers: number,
98+
): Promise<Rgba[]> {
99+
const { workDir, projectDir } = writeProject(root, f, blur, `whole-${blur}`);
100+
const outputDir = join(workDir, "frames");
101+
const job = createRenderJob({
102+
fps: FPS,
103+
format: "png-sequence",
104+
quality: "standard",
105+
hdrMode: "force-sdr",
106+
useGpu: false,
107+
workers,
108+
logger: quietLogger,
109+
producerConfig: resolveConfig({ browserGpuMode: "software" }),
110+
});
111+
await executeRenderJob(job, projectDir, outputDir);
112+
const frames = decodeFrames(outputDir);
113+
rmSync(workDir, { recursive: true, force: true });
114+
return frames;
115+
}
116+
117+
/** plan() then renderChunk() per chunk then assemble(), the way a Lambda or Cloud Run fan-out runs. */
118+
export async function renderChunked(
119+
root: string,
120+
f: BlurFixture,
121+
blur: "on" | "off",
122+
tag: string,
123+
config: Partial<DistributedRenderConfig> = {},
124+
): Promise<Rgba[]> {
125+
const { workDir, projectDir } = writeProject(root, f, blur, tag);
126+
const planDir = join(workDir, "plan");
127+
const chunksDir = join(workDir, "chunks");
128+
const outputDir = join(workDir, "frames");
129+
mkdirSync(planDir, { recursive: true });
130+
mkdirSync(chunksDir, { recursive: true });
131+
const planned = await plan(
132+
projectDir,
133+
{
134+
fps: FPS,
135+
width: f.width,
136+
height: f.height,
137+
format: "png-sequence",
138+
chunkSize: CHUNK_SIZE,
139+
rejectOnSystemFonts: false,
140+
failClosedFontFetch: false,
141+
...config,
142+
},
143+
planDir,
144+
);
145+
const chunkPaths: string[] = [];
146+
for (let i = 0; i < planned.chunkCount; i++) {
147+
const chunkPath = join(chunksDir, `chunk-${String(i).padStart(4, "0")}`);
148+
await renderChunk(planDir, i, chunkPath);
149+
chunkPaths.push(chunkPath);
150+
}
151+
await assemble(planDir, chunkPaths, null, outputDir);
152+
const frames = decodeFrames(outputDir);
153+
rmSync(workDir, { recursive: true, force: true });
154+
return frames;
155+
}
156+
157+
const wholeFrameMask = (frame: Rgba): Uint8Array => new Uint8Array(frame.width * frame.height);
158+
159+
function at(frames: readonly Rgba[], n: number): Rgba {
160+
const frame = frames[n];
161+
if (!frame) throw new Error(`missing frame ${n}`);
162+
return frame;
163+
}
164+
165+
/** Whole-frame tile comparison of every frame: no trail is masked out, chunk boundaries included. */
166+
export function compareEveryFrame(
167+
reference: readonly Rgba[],
168+
actual: readonly Rgba[],
169+
): { frame: number; differential: Differential }[] {
170+
if (actual.length !== reference.length) {
171+
throw new Error(`frame count ${actual.length} differs from ${reference.length}`);
172+
}
173+
return reference.map((frame, n) => ({
174+
frame: n,
175+
differential: compareTiles(frame, at(actual, n), wholeFrameMask(frame), "outside", {
176+
block: INVARIANTS.block,
177+
maxMae: RENDER_OUTSIDE_MAX_MAE,
178+
}),
179+
}));
180+
}
181+
182+
export function worstMae(results: readonly { differential: Differential }[]): number {
183+
return Math.max(...results.map((x) => x.differential.worstMae));
184+
}
185+
186+
export function expectEqualFrames(
187+
label: string,
188+
results: readonly { frame: number; differential: Differential }[],
189+
): void {
190+
const firstBad = results
191+
.filter((x) => x.differential.bad.length > 0)
192+
.slice(0, 5)
193+
.map((x) => ({ frame: x.frame, bad: x.differential.bad.slice(0, 3) }));
194+
expect(
195+
results.flatMap((x) => x.differential.bad),
196+
`${label} ${JSON.stringify(firstBad)}`,
197+
).toEqual([]);
198+
}
199+
200+
/** The frames of plan() -> renderChunk() -> assemble() with blur on equal a whole in-process render with blur on. */
201+
export async function expectChunksEqualWhole(
202+
root: string,
203+
name: string,
204+
tier: "capture" | "auto" = "capture",
205+
): Promise<void> {
206+
const f = tier === "auto" ? withoutTierAttribute(fixtureNamed(name)) : fixtureNamed(name);
207+
const whole = await renderWhole(root, f, "on", WHOLE_WORKERS);
208+
const chunked = await renderChunked(root, f, "on", "chunked-on");
209+
expectEqualFrames(name, compareEveryFrame(whole, chunked));
210+
}
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Page motion blur through plan() -> renderChunk() -> assemble() on `callbacks`: the frames a fan-out
2+
// assembles equal the frames a whole in-process render draws, chunk boundaries included.
3+
// Needs Chrome and ffmpeg: integration lane.
4+
5+
import { describe, it } from "vitest";
6+
import {
7+
expectChunksEqualWhole,
8+
HAS_FFMPEG,
9+
RENDER_TIMEOUT_MS,
10+
useBlurScratch,
11+
} from "./__test_utils__/blurChunkRender.js";
12+
13+
describe.skipIf(!HAS_FFMPEG)("page motion blur in a distributed render: callbacks", () => {
14+
const root = useBlurScratch();
15+
16+
it(
17+
"chunks of 20 frames assemble to the whole render's frames",
18+
() => expectChunksEqualWhole(root(), "callbacks"),
19+
RENDER_TIMEOUT_MS,
20+
);
21+
});
Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// The default tier through plan() -> renderChunk() -> assemble() on `callbacks`: with no
2+
// data-motion-blur-tier on the root, `auto` draws with the filter tier, and the frames a fan-out
3+
// assembles equal a whole in-process render's. Needs Chrome and ffmpeg: integration lane.
4+
5+
import { describe, it } from "vitest";
6+
import {
7+
expectChunksEqualWhole,
8+
HAS_FFMPEG,
9+
RENDER_TIMEOUT_MS,
10+
useBlurScratch,
11+
} from "./__test_utils__/blurChunkRender.js";
12+
13+
describe.skipIf(!HAS_FFMPEG)(
14+
"page motion blur in a distributed render, auto tier: callbacks",
15+
() => {
16+
const root = useBlurScratch();
17+
18+
it(
19+
"chunks of 20 frames assemble to the whole render's frames",
20+
() => expectChunksEqualWhole(root(), "callbacks", "auto"),
21+
RENDER_TIMEOUT_MS,
22+
);
23+
},
24+
);
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// An explicit pageMotionBlur "off" in the distributed config still stands the page's blur down:
2+
// the escape hatch behind `hyperframes render --page-motion-blur off`. Needs Chrome and ffmpeg:
3+
// integration lane.
4+
5+
import { describe, expect, it } from "vitest";
6+
import { RENDER_OUTSIDE_MAX_MAE } from "../../../../engine/src/services/__fixtures__/motionBlur/thresholds.js";
7+
import {
8+
compareEveryFrame,
9+
expectEqualFrames,
10+
fixtureNamed,
11+
HAS_FFMPEG,
12+
RENDER_TIMEOUT_MS,
13+
renderChunked,
14+
renderWhole,
15+
useBlurScratch,
16+
WHOLE_WORKERS,
17+
worstMae,
18+
} from "./__test_utils__/blurChunkRender.js";
19+
20+
describe.skipIf(!HAS_FFMPEG)("page motion blur in a distributed render: config off", () => {
21+
const root = useBlurScratch();
22+
23+
it(
24+
"keeps pageMotionBlur off when the config says off",
25+
async () => {
26+
const f = fixtureNamed("held-card");
27+
const wholeOff = await renderWhole(root(), f, "off", WHOLE_WORKERS);
28+
const stoodDown = await renderChunked(root(), f, "on", "chunked-config-off", {
29+
pageMotionBlur: "off",
30+
});
31+
expectEqualFrames("config off", compareEveryFrame(wholeOff, stoodDown));
32+
33+
const blurred = await renderChunked(root(), f, "on", "chunked-on");
34+
expect(
35+
worstMae(compareEveryFrame(wholeOff, blurred)),
36+
"blur on must differ from blur off, or the comparison above proves nothing",
37+
).toBeGreaterThan(RENDER_OUTSIDE_MAX_MAE);
38+
},
39+
RENDER_TIMEOUT_MS,
40+
);
41+
});
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Page motion blur through plan() -> renderChunk() -> assemble() on `held-card`: the frames a fan-out
2+
// assembles equal the frames a whole in-process render draws, chunk boundaries included.
3+
// Needs Chrome and ffmpeg: integration lane.
4+
5+
import { describe, it } from "vitest";
6+
import {
7+
expectChunksEqualWhole,
8+
HAS_FFMPEG,
9+
RENDER_TIMEOUT_MS,
10+
useBlurScratch,
11+
} from "./__test_utils__/blurChunkRender.js";
12+
13+
describe.skipIf(!HAS_FFMPEG)("page motion blur in a distributed render: held-card", () => {
14+
const root = useBlurScratch();
15+
16+
it(
17+
"chunks of 20 frames assemble to the whole render's frames",
18+
() => expectChunksEqualWhole(root(), "held-card"),
19+
RENDER_TIMEOUT_MS,
20+
);
21+
});

0 commit comments

Comments
 (0)