mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 00:18:27 +00:00
fix(producer): seed random values in every render so re-renders give the same film (#7410)
* fix(producer): every render draws the same random values, at any worker count * fix(producer): run the random-stagger fixture in CI and say what seeding covers
This commit is contained in:
@@ -8,7 +8,7 @@ import {
|
||||
} from "@hyperframes/engine";
|
||||
import type { ProducerLogger } from "../../logger.js";
|
||||
import {
|
||||
buildVirtualTimeShim,
|
||||
VIRTUAL_TIME_SHIM,
|
||||
closeFileServerSafely,
|
||||
createFileServer,
|
||||
resolveRenderFpsConfig,
|
||||
@@ -73,7 +73,7 @@ export async function measurePlanSecondsPerFrame(input: {
|
||||
projectDir: compiledDir,
|
||||
compiledDir,
|
||||
port: 0,
|
||||
preHeadScripts: [buildVirtualTimeShim({ seedRandomFromFrame: true })],
|
||||
preHeadScripts: [VIRTUAL_TIME_SHIM],
|
||||
fps: fpsRatio,
|
||||
});
|
||||
let session: Awaited<ReturnType<typeof createCaptureSession>> | null = null;
|
||||
|
||||
@@ -21,8 +21,7 @@
|
||||
* - Browser is launched with `browserGpuMode: "software"` and verified
|
||||
* against `chrome://gpu` via `assertSwiftShader` — a non-SwiftShader
|
||||
* backend trips a non-retryable `BROWSER_GPU_NOT_SOFTWARE`.
|
||||
* - The file server serves with the seeded-random shim
|
||||
* (`buildVirtualTimeShim({ seedRandomFromFrame: true })`) so any
|
||||
* - The file server serves `VIRTUAL_TIME_SHIM`, as every render path does, so any
|
||||
* composition that uses `Math.random` / `crypto.getRandomValues`
|
||||
* produces byte-identical pixels per `(planDir, chunkIndex)`.
|
||||
* - No `lastFrameCache` priming: every frame seeks fresh DOM so the
|
||||
@@ -30,7 +29,7 @@
|
||||
* - The chunk's encode runs with `lockGopForChunkConcat: true` and
|
||||
* `gopSize === framesInChunk` so concat-copy at assemble time is safe.
|
||||
*
|
||||
* Every determinism toggle above is opt-in — only this primitive enables them.
|
||||
* Every other determinism toggle above is opt-in — only this primitive enables them.
|
||||
* In-process renders (`executeRenderJob`) leave them off.
|
||||
*/
|
||||
|
||||
@@ -86,7 +85,7 @@ import {
|
||||
import { sha256Hex } from "../render/stages/planHash.js";
|
||||
import { applyRuntimeEnvSnapshot } from "../render/runtimeEnvSnapshot.js";
|
||||
import {
|
||||
buildVirtualTimeShim,
|
||||
VIRTUAL_TIME_SHIM,
|
||||
closeFileServerSafely,
|
||||
createFileServer,
|
||||
resolveRenderFpsConfig,
|
||||
@@ -723,12 +722,12 @@ export async function renderChunk(
|
||||
|
||||
// ── File server with the seeded-random shim ──
|
||||
// `Math.random` / `crypto.getRandomValues` are seeded from virtual
|
||||
// time so retries are pixel-identical. Only distributed renders flip this.
|
||||
// time so retries are pixel-identical.
|
||||
const fileServer: FileServerHandle = await createFileServer({
|
||||
projectDir: compiledDir,
|
||||
compiledDir,
|
||||
port: 0,
|
||||
preHeadScripts: [buildVirtualTimeShim({ seedRandomFromFrame: true })],
|
||||
preHeadScripts: [VIRTUAL_TIME_SHIM],
|
||||
// These dimensions are frozen by the controller from the render job, so
|
||||
// chunk runtime seek quantization stays on the same fps grid as capture.
|
||||
fps: { num: plan.dimensions.fpsNum, den: plan.dimensions.fpsDen },
|
||||
|
||||
@@ -1,16 +1,5 @@
|
||||
/**
|
||||
* Tests for the `seedRandomFromFrame` gate on `buildVirtualTimeShim`.
|
||||
*
|
||||
* 1. Backwards compatibility — `buildVirtualTimeShim({
|
||||
* seedRandomFromFrame: false })` returns a string byte-identical to the
|
||||
* legacy `VIRTUAL_TIME_SHIM`. Existing in-process callers see no
|
||||
* difference.
|
||||
*
|
||||
* 2. Distributed determinism — with `seedRandomFromFrame: true`, the shim's
|
||||
* `seekToTime(ms)` reseeds a Mulberry32 PRNG keyed by the virtual time
|
||||
* and replaces `Math.random` / `crypto.getRandomValues` with that PRNG.
|
||||
* `seekToTime(N)` → N `Math.random()` calls is a deterministic
|
||||
* sequence; reseeking to the same time restarts the sequence.
|
||||
* Tests for the seeded `Math.random` / `crypto.getRandomValues` in `VIRTUAL_TIME_SHIM`.
|
||||
*
|
||||
* The shim is executed inside `node:vm` with a synthetic `window`/`Math` so
|
||||
* tests don't need real Chrome.
|
||||
@@ -18,7 +7,7 @@
|
||||
|
||||
import { describe, expect, it } from "bun:test";
|
||||
import { Script, createContext, type Context } from "node:vm";
|
||||
import { buildVirtualTimeShim, VIRTUAL_TIME_SHIM } from "./fileServer.js";
|
||||
import { VIRTUAL_TIME_SHIM } from "./fileServer.js";
|
||||
|
||||
/**
|
||||
* Build a fresh VM context with its own globals (its own Math, its own
|
||||
@@ -62,50 +51,16 @@ function runShim(shimSource: string): {
|
||||
return ctx;
|
||||
}
|
||||
|
||||
describe("buildVirtualTimeShim — backwards compatibility", () => {
|
||||
it("default (seedRandomFromFrame: false) is byte-identical to VIRTUAL_TIME_SHIM", () => {
|
||||
// The const that existing call sites import:
|
||||
// renderOrchestrator.ts: preHeadScripts: [VIRTUAL_TIME_SHIM]
|
||||
// probeStage.ts: preHeadScripts: [VIRTUAL_TIME_SHIM]
|
||||
// Must continue to emit the same script.
|
||||
const built = buildVirtualTimeShim({ seedRandomFromFrame: false });
|
||||
expect(built).toBe(VIRTUAL_TIME_SHIM);
|
||||
});
|
||||
|
||||
it("default shim does not mention any seeded-RNG identifiers", () => {
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: false });
|
||||
expect(shim).not.toContain("mulberry32");
|
||||
expect(shim).not.toContain("reseedRngFromTime");
|
||||
expect(shim).not.toContain("__seededGetRandomValues");
|
||||
expect(shim).not.toContain("Math.random = ");
|
||||
});
|
||||
|
||||
it("default shim leaves Math.random pointing at the VM's native function", () => {
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: false });
|
||||
const { run } = runShim(shim);
|
||||
// toString() of native Math.random is `function random() { [native code] }`
|
||||
const isNative = run<boolean>(`/\\[native code\\]/.test(Math.random.toString())`);
|
||||
expect(isNative).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
|
||||
it("emits the seeded-RNG block", () => {
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
|
||||
expect(shim).toContain("mulberry32");
|
||||
expect(shim).toContain("reseedRngFromTime");
|
||||
expect(shim).toContain("__seededGetRandomValues");
|
||||
});
|
||||
|
||||
describe("VIRTUAL_TIME_SHIM seeded randomness", () => {
|
||||
it("replaces Math.random with a non-native PRNG", () => {
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
|
||||
const shim = VIRTUAL_TIME_SHIM;
|
||||
const { run } = runShim(shim);
|
||||
const isNative = run<boolean>(`/\\[native code\\]/.test(Math.random.toString())`);
|
||||
expect(isNative).toBe(false);
|
||||
});
|
||||
|
||||
it("produces identical Math.random sequences across two fresh VMs at the same time", () => {
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
|
||||
const shim = VIRTUAL_TIME_SHIM;
|
||||
const drawSequence = `(() => {
|
||||
window.__HF_VIRTUAL_TIME__.seekToTime(1234);
|
||||
const seq = [];
|
||||
@@ -126,7 +81,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
|
||||
it("re-seeking to the same time produces the same Math.random sequence", () => {
|
||||
// The core determinism contract for retries: same (planDir, chunkIndex) →
|
||||
// same frame N → same seekToTime(t_N) → same Math.random outputs.
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
|
||||
const shim = VIRTUAL_TIME_SHIM;
|
||||
const { run } = runShim(shim);
|
||||
const observed = run<{ first: number[]; second: number[] }>(`(() => {
|
||||
window.__HF_VIRTUAL_TIME__.seekToTime(42);
|
||||
@@ -141,7 +96,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
|
||||
});
|
||||
|
||||
it("different times produce different Math.random sequences", () => {
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
|
||||
const shim = VIRTUAL_TIME_SHIM;
|
||||
const { run } = runShim(shim);
|
||||
const observed = run<{ t0: number[]; t1: number[] }>(`(() => {
|
||||
window.__HF_VIRTUAL_TIME__.seekToTime(0);
|
||||
@@ -154,7 +109,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
|
||||
});
|
||||
|
||||
it("seeded crypto.getRandomValues writes deterministic bytes", () => {
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
|
||||
const shim = VIRTUAL_TIME_SHIM;
|
||||
const drawBytes = `(() => {
|
||||
window.__HF_VIRTUAL_TIME__.seekToTime(7);
|
||||
const buf = new Uint8Array(64);
|
||||
@@ -168,7 +123,7 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
|
||||
});
|
||||
|
||||
it("seeded crypto.getRandomValues handles odd byte lengths", () => {
|
||||
const shim = buildVirtualTimeShim({ seedRandomFromFrame: true });
|
||||
const shim = VIRTUAL_TIME_SHIM;
|
||||
const { run } = runShim(shim);
|
||||
const lengths = run<number[]>(`(() => {
|
||||
window.__HF_VIRTUAL_TIME__.seekToTime(3);
|
||||
@@ -182,4 +137,16 @@ describe("buildVirtualTimeShim — seedRandomFromFrame: true", () => {
|
||||
})()`);
|
||||
expect(lengths).toEqual([1, 2, 3, 4, 5, 7, 31, 33]);
|
||||
});
|
||||
|
||||
it("draws the same Math.random sequence at page load in two fresh pages", () => {
|
||||
// A GSAP stagger { from: "random" } draws its order when the page script runs, before any seek.
|
||||
const drawAtLoad = `(() => {
|
||||
const seq = [];
|
||||
for (let i = 0; i < 16; i++) seq.push(Math.random());
|
||||
return seq;
|
||||
})()`;
|
||||
const seqA = runShim(VIRTUAL_TIME_SHIM).run<number[]>(drawAtLoad);
|
||||
const seqB = runShim(VIRTUAL_TIME_SHIM).run<number[]>(drawAtLoad);
|
||||
expect(seqA).toEqual(seqB);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import { describe, expect, it } from "bun:test";
|
||||
import { createContext, Script } from "node:vm";
|
||||
import { buildVirtualTimeShim } from "./fileServer.js";
|
||||
import { VIRTUAL_TIME_SHIM } from "./fileServer.js";
|
||||
|
||||
type Page = { run: <T = unknown>(code: string) => T };
|
||||
|
||||
@@ -17,7 +17,7 @@ function page(): Page {
|
||||
globalThis.performance = { now: () => 0 };
|
||||
globalThis.__renderReady = true;
|
||||
`).runInContext(context);
|
||||
new Script(buildVirtualTimeShim({ seedRandomFromFrame: false })).runInContext(context);
|
||||
new Script(VIRTUAL_TIME_SHIM).runInContext(context);
|
||||
return { run: <T>(code: string) => new Script(code).runInContext(context) as T };
|
||||
}
|
||||
|
||||
|
||||
@@ -206,47 +206,29 @@ export function parseRangeHeader(
|
||||
}
|
||||
|
||||
/**
|
||||
* Options for {@link buildVirtualTimeShim}.
|
||||
* Page-side virtual-time shim, installed before page scripts on every render path.
|
||||
* Holds Date.now, performance.now, rAF and later timers at the seek time, and seeds Math.random and
|
||||
* crypto.getRandomValues from it, so a re-render repeats. Draws at page load or inside a frame also match
|
||||
* across worker counts; a value resolved on a tween's first render depends on the frame a worker reaches first.
|
||||
*/
|
||||
export interface VirtualTimeShimOptions {
|
||||
/**
|
||||
* When `true`, the shim additionally replaces `Math.random` and
|
||||
* `crypto.getRandomValues` with a Mulberry32-seeded PRNG keyed by the
|
||||
* current frame's virtual time. Compositions that call `Math.random()`
|
||||
* during render then produce byte-identical pixels across machines and
|
||||
* across replays of the same `(planDir, chunkIndex)` pair.
|
||||
*
|
||||
* Default `false`: leaves `Math.random` / `crypto.getRandomValues` native,
|
||||
* preserving the in-process renderer's non-deterministic behavior for
|
||||
* compositions that rely on it.
|
||||
*/
|
||||
seedRandomFromFrame: boolean;
|
||||
}
|
||||
const VIRTUAL_TIME_SHIM = String.raw`(function() {
|
||||
if (window.__HF_VIRTUAL_TIME__) return;
|
||||
|
||||
var virtualNowMs = 0;
|
||||
var rafId = 1;
|
||||
var rafQueue = [];
|
||||
var OriginalDate = Date;
|
||||
var originalSetTimeout = window.setTimeout.bind(window);
|
||||
var originalClearTimeout = window.clearTimeout.bind(window);
|
||||
var originalSetInterval = window.setInterval.bind(window);
|
||||
var originalClearInterval = window.clearInterval.bind(window);
|
||||
var originalRequestAnimationFrame = window.requestAnimationFrame
|
||||
? window.requestAnimationFrame.bind(window)
|
||||
: null;
|
||||
var originalCancelAnimationFrame = window.cancelAnimationFrame
|
||||
? window.cancelAnimationFrame.bind(window)
|
||||
: null;
|
||||
|
||||
/**
|
||||
* Build the page-side virtual-time shim script.
|
||||
*
|
||||
* The shim freezes `Date.now`, `performance.now`, rAF, and the timers set
|
||||
* after the first seek, so a render seek can deterministically advance the
|
||||
* page's notion of "now". The renderer issues `__HF_VIRTUAL_TIME__.seekToTime(ms)`
|
||||
* before every frame capture; everything timing-related on the page sees
|
||||
* exactly `ms` until the next seek.
|
||||
*
|
||||
* When `options.seedRandomFromFrame` is `true`, the returned script also
|
||||
* installs a seeded `Math.random` / `crypto.getRandomValues` keyed by the
|
||||
* current virtual time — so compositions with stochastic visuals retry
|
||||
* identically. When `false`, the shim emits no random-override code; the
|
||||
* page's native `Math.random` is left alone (the in-process default).
|
||||
*/
|
||||
export function buildVirtualTimeShim(options: VirtualTimeShimOptions): string {
|
||||
const seedRandomFromFrame = options.seedRandomFromFrame === true;
|
||||
// The seeded-RNG block is gated at build time so the unlocked shim is
|
||||
// byte-identical to the pre-flag form. Producer regression baselines
|
||||
// compare on rendered pixels — but the file-server unit tests in
|
||||
// `fileServer.test.ts` also string-match `VIRTUAL_TIME_SHIM`, and we want
|
||||
// those matches to remain stable.
|
||||
const seededRandomBlock = seedRandomFromFrame
|
||||
? String.raw`
|
||||
// Seeded Math.random / crypto.getRandomValues, keyed by virtual time.
|
||||
// Mulberry32: single uint32 state, deterministic, fast.
|
||||
var rngState = 0;
|
||||
@@ -288,30 +270,7 @@ export function buildVirtualTimeShim(options: VirtualTimeShimOptions): string {
|
||||
window.crypto.getRandomValues = __seededGetRandomValues;
|
||||
} catch (e) {}
|
||||
}
|
||||
`
|
||||
: "";
|
||||
// The seekToTime hook reseeds when seeding is on; under seedRandomFromFrame=false
|
||||
// we emit no extra call so the function body is byte-identical to the
|
||||
// unseeded shim.
|
||||
const seekToTimeReseedCall = seedRandomFromFrame ? "reseedRngFromTime(safeTimeMs);\n " : "";
|
||||
return String.raw`(function() {
|
||||
if (window.__HF_VIRTUAL_TIME__) return;
|
||||
|
||||
var virtualNowMs = 0;
|
||||
var rafId = 1;
|
||||
var rafQueue = [];
|
||||
var OriginalDate = Date;
|
||||
var originalSetTimeout = window.setTimeout.bind(window);
|
||||
var originalClearTimeout = window.clearTimeout.bind(window);
|
||||
var originalSetInterval = window.setInterval.bind(window);
|
||||
var originalClearInterval = window.clearInterval.bind(window);
|
||||
var originalRequestAnimationFrame = window.requestAnimationFrame
|
||||
? window.requestAnimationFrame.bind(window)
|
||||
: null;
|
||||
var originalCancelAnimationFrame = window.cancelAnimationFrame
|
||||
? window.cancelAnimationFrame.bind(window)
|
||||
: null;
|
||||
${seededRandomBlock}
|
||||
function flushAnimationFrame() {
|
||||
if (!rafQueue.length) return;
|
||||
var current = rafQueue.slice();
|
||||
@@ -442,7 +401,8 @@ ${seededRandomBlock}
|
||||
// page starts there keep the schedule a one-worker render gives them.
|
||||
if (safeTimeMs > 0) seekToTime(0);
|
||||
}
|
||||
${seekToTimeReseedCall}fireDueTimers(safeTimeMs);
|
||||
reseedRngFromTime(safeTimeMs);
|
||||
fireDueTimers(safeTimeMs);
|
||||
virtualNowMs = safeTimeMs;
|
||||
flushAnimationFrame();
|
||||
return virtualNowMs;
|
||||
@@ -461,14 +421,6 @@ ${seededRandomBlock}
|
||||
},
|
||||
};
|
||||
})();`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Default in-process virtual-time shim — `seedRandomFromFrame: false`.
|
||||
* Existing call sites (`renderOrchestrator`, `probeStage`) import this
|
||||
* constant. Distributed callers build their own with seeding enabled.
|
||||
*/
|
||||
const VIRTUAL_TIME_SHIM = buildVirtualTimeShim({ seedRandomFromFrame: false });
|
||||
|
||||
/**
|
||||
* Render mode extension -- adds renderSeek() for frame-accurate seeking
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
{
|
||||
"name": "random-stagger-workers",
|
||||
"description": "Regression test for Math.random during render. A 100-cell grid fades out with a GSAP stagger from \"random\", whose order GSAP draws from Math.random when the page loads. Rendered with 2 workers, both workers and every re-render must draw the same order, so the film matches the golden frame for frame.",
|
||||
"tags": ["regression", "parallel", "render-compat"],
|
||||
"minPsnr": 30,
|
||||
"maxFrameFailures": 0,
|
||||
"minAudioCorrelation": 0,
|
||||
"maxAudioLagWindows": 1,
|
||||
"renderConfig": {
|
||||
"fps": 30,
|
||||
"workers": 2
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:2d5665bb78e6cf9a065322ddcaef3f56f13d8b72d0b3c841734c15ce6b867160
|
||||
size 74536
|
||||
@@ -0,0 +1,3 @@
|
||||
version https://git-lfs.github.com/spec/v1
|
||||
oid sha256:6946b7491232166b7d0408f2a30e79a8cd60b3cfda2acf97a9515ebf7940228d
|
||||
size 72084
|
||||
@@ -0,0 +1,33 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=1080, height=1080">
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.2/gsap.min.js" integrity="sha384-d+vyQ0dYcymoP8ndq2hW7FGC50nqGdXUEgoOUGxbbkAJwZqL7h+jKN0GGgn9hFDS" crossorigin="anonymous"></script>
|
||||
<style>
|
||||
body { margin: 0; background: #0d1117; width: 1080px; height: 1080px; overflow: hidden; }
|
||||
#grid {
|
||||
position: absolute; left: 140px; top: 140px; width: 800px; height: 800px;
|
||||
display: grid; grid-template-columns: repeat(10, 1fr); grid-template-rows: repeat(10, 1fr); gap: 8px;
|
||||
}
|
||||
.cell { background: #e6edf3; border-radius: 6px; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div id="root" data-composition-id="root" data-width="1080" data-height="1080" data-duration="2"
|
||||
style="position:absolute;width:1080px;height:1080px;">
|
||||
<div id="grid"></div>
|
||||
</div>
|
||||
<script>
|
||||
const grid = document.getElementById("grid");
|
||||
for (let i = 0; i < 100; i++) {
|
||||
const cell = document.createElement("div");
|
||||
cell.className = "cell";
|
||||
grid.appendChild(cell);
|
||||
}
|
||||
const tl = gsap.timeline({ paused: true });
|
||||
tl.fromTo(".cell", { opacity: 1 }, { opacity: 0.1, duration: 0.1, ease: "none", stagger: { amount: 1.6, from: "random" } }, 0.2);
|
||||
window.__timelines["root"] = tl;
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -38,6 +38,7 @@
|
||||
"png-sequence": 3,
|
||||
"portrait-edge-bleed": 6,
|
||||
"raf-ball-render-compat": 10,
|
||||
"random-stagger-workers": 8,
|
||||
"timers-on-film-time": 8,
|
||||
"render-symlinked-assets": 6,
|
||||
"static-volume-future-set": 9,
|
||||
|
||||
Reference in New Issue
Block a user