mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
fix(render): make WebGL video textures deterministic in headless render (#1403)
* fix(render): make WebGL video textures deterministic in headless render WebGL compositions that sample a `<video>` as a texture (e.g. a faceted crystal with clips mapped onto its facets) rendered with flickering, non-deterministic facets: a video would intermittently show a stale frame or go black, and the same frame differed between two renders. Two gaps caused this: 1. No WebGL analog of the WebGPU `patchVideoTextureCompat`. Chrome's headless compositor can't feed decoded `<video>` frames to the GPU, so the engine injects a decoded `<img class="__render_frame__">` sibling per video each frame. The WebGPU `copyExternalImageToTexture` path substitutes it, but `texImage2D` / `texSubImage2D` did not — so WebGL uploaded a stale/black frame. Add `patchWebGLVideoTextureCompat()` mirroring the WebGPU patch (shared `resolveRenderFrameImage` helper). 2. Capture ordering. Per frame the runtime seeks (GPU adapters render on `hf-seek`) BEFORE the engine injects the decoded frames, so the GPU render read a frame that didn't exist yet. After injecting, the engine now calls `window.__hfReseekGpu(t)` — a force-dispatch (`forceDispatchSeekEvent`) that bypasses the same-time `hf-seek` dedup — so GPU compositions re-upload their textures from the freshly-injected, decoded frames, deterministically. Tests: unit tests for the texImage2D/texSubImage2D substitution and the force-dispatch, plus a videoFrameInjector regression test asserting the post-injection GPU reseek fires only when frames were injected. Verified end-to-end: a WebGL prism with 8 live <video> facets renders byte-identical across independent runs with no facet flicker. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * test(render): add producer render-compat regression for WebGL video textures A WebGL2 canvas samples a <video> as a texture every hf-seek (the natural author pattern, distilled from the HeyGen prism). The render-compat harness renders it and compares against the golden: with the video-texture fix the render reproduces the decoded frames; revert the fix and the canvas renders black, collapsing the comparison. Golden verified to contain real, time-varying video content (not black), so a regression is caught rather than passing vacuously. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
James Russo
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
6364281ba0
commit
d580f2a1d8
@@ -0,0 +1,45 @@
|
||||
import { describe, it, expect, vi, beforeEach } from "vitest";
|
||||
import { dispatchSeekEvent, forceDispatchSeekEvent, resetSeekDispatchState } from "./seek-dispatch";
|
||||
|
||||
describe("seek-dispatch", () => {
|
||||
beforeEach(() => {
|
||||
resetSeekDispatchState();
|
||||
});
|
||||
|
||||
it("dispatchSeekEvent fires an hf-seek event with the time", () => {
|
||||
const handler = vi.fn();
|
||||
window.addEventListener("hf-seek", handler);
|
||||
dispatchSeekEvent(2.5);
|
||||
window.removeEventListener("hf-seek", handler);
|
||||
expect(handler).toHaveBeenCalledTimes(1);
|
||||
expect((handler.mock.calls[0][0] as CustomEvent).detail.time).toBe(2.5);
|
||||
});
|
||||
|
||||
it("dispatchSeekEvent dedups consecutive same-time dispatches", () => {
|
||||
const handler = vi.fn();
|
||||
window.addEventListener("hf-seek", handler);
|
||||
dispatchSeekEvent(4);
|
||||
dispatchSeekEvent(4);
|
||||
window.removeEventListener("hf-seek", handler);
|
||||
expect(handler).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("forceDispatchSeekEvent re-fires even at the same time (post-injection re-render)", () => {
|
||||
const handler = vi.fn();
|
||||
window.addEventListener("hf-seek", handler);
|
||||
dispatchSeekEvent(6); // GPU adapters' first render at t=6
|
||||
forceDispatchSeekEvent(6); // engine re-render after video injection, same t
|
||||
window.removeEventListener("hf-seek", handler);
|
||||
expect(handler).toHaveBeenCalledTimes(2);
|
||||
expect((handler.mock.calls[1][0] as CustomEvent).detail.time).toBe(6);
|
||||
});
|
||||
|
||||
it("after a force dispatch, the same time still dedups on the normal path", () => {
|
||||
const handler = vi.fn();
|
||||
window.addEventListener("hf-seek", handler);
|
||||
forceDispatchSeekEvent(8);
|
||||
dispatchSeekEvent(8); // deduped — force already recorded t=8
|
||||
window.removeEventListener("hf-seek", handler);
|
||||
expect(handler).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
});
|
||||
@@ -30,6 +30,25 @@ export function dispatchSeekEvent(time: number): void {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Force-dispatch a `"hf-seek"` event even if `time` equals the last dispatched
|
||||
* time, bypassing the dedup guard.
|
||||
*
|
||||
* Needed for the post-video-injection GPU re-render: the engine seeks to time
|
||||
* T (GPU adapters render once, before video frames are injected), then injects
|
||||
* the decoded `__render_frame__` images, then must re-render GPU compositions
|
||||
* at the *same* T so they re-upload textures from the now-present frames. The
|
||||
* normal dedup would swallow that second dispatch.
|
||||
*/
|
||||
export function forceDispatchSeekEvent(time: number): void {
|
||||
_lastDispatchedTime = time;
|
||||
try {
|
||||
window.dispatchEvent(new CustomEvent("hf-seek", { detail: { time } }));
|
||||
} catch (err) {
|
||||
swallow("runtime.adapters.seek-dispatch.force", err);
|
||||
}
|
||||
}
|
||||
|
||||
/** Reset internal state — used in tests to prevent cross-test contamination. */
|
||||
export function resetSeekDispatchState(): void {
|
||||
_lastDispatchedTime = -1;
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
import { describe, it, expect, beforeEach, afterEach } from "vitest";
|
||||
import { patchWebGLVideoTextureCompat } from "./video-texture-compat";
|
||||
|
||||
// Minimal fake WebGL2 context that records the source passed to texImage2D /
|
||||
// texSubImage2D, so we can assert the patch substitutes the injected frame.
|
||||
class FakeGL2 {
|
||||
lastImageArgs: unknown[] | null = null;
|
||||
lastSubArgs: unknown[] | null = null;
|
||||
texImage2D(...args: unknown[]) {
|
||||
this.lastImageArgs = args;
|
||||
}
|
||||
texSubImage2D(...args: unknown[]) {
|
||||
this.lastSubArgs = args;
|
||||
}
|
||||
}
|
||||
|
||||
function makeInjectedImage(): HTMLImageElement {
|
||||
const img = document.createElement("img");
|
||||
img.classList.add("__render_frame__");
|
||||
Object.defineProperty(img, "complete", { value: true, configurable: true });
|
||||
Object.defineProperty(img, "naturalWidth", { value: 16, configurable: true });
|
||||
return img;
|
||||
}
|
||||
|
||||
describe("patchWebGLVideoTextureCompat", () => {
|
||||
let originalGL2: unknown;
|
||||
|
||||
beforeEach(() => {
|
||||
originalGL2 = (globalThis as Record<string, unknown>).WebGL2RenderingContext;
|
||||
(globalThis as Record<string, unknown>).WebGL2RenderingContext = FakeGL2;
|
||||
document.body.innerHTML = "";
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
(globalThis as Record<string, unknown>).WebGL2RenderingContext = originalGL2;
|
||||
document.body.innerHTML = "";
|
||||
});
|
||||
|
||||
it("substitutes the decoded __render_frame__ image when uploading a <video>", () => {
|
||||
patchWebGLVideoTextureCompat();
|
||||
|
||||
const video = document.createElement("video");
|
||||
const img = makeInjectedImage();
|
||||
document.body.append(video, img); // img is video.nextElementSibling
|
||||
|
||||
const gl = new FakeGL2();
|
||||
gl.texImage2D(0x0de1, 0, 0x1908, 0x1908, 0x1401, video);
|
||||
|
||||
// Last argument (the source) must be swapped to the injected image.
|
||||
expect(gl.lastImageArgs?.[gl.lastImageArgs.length - 1]).toBe(img);
|
||||
});
|
||||
|
||||
it("leaves the <video> source untouched when no render frame is present (preview)", () => {
|
||||
patchWebGLVideoTextureCompat();
|
||||
|
||||
const video = document.createElement("video");
|
||||
document.body.append(video);
|
||||
|
||||
const gl = new FakeGL2();
|
||||
gl.texImage2D(0x0de1, 0, 0x1908, 0x1908, 0x1401, video);
|
||||
|
||||
expect(gl.lastImageArgs?.[gl.lastImageArgs.length - 1]).toBe(video);
|
||||
});
|
||||
|
||||
it("ignores a render-frame image that is not yet decoded", () => {
|
||||
patchWebGLVideoTextureCompat();
|
||||
|
||||
const video = document.createElement("video");
|
||||
const img = document.createElement("img");
|
||||
img.classList.add("__render_frame__");
|
||||
Object.defineProperty(img, "complete", { value: false, configurable: true });
|
||||
Object.defineProperty(img, "naturalWidth", { value: 0, configurable: true });
|
||||
document.body.append(video, img);
|
||||
|
||||
const gl = new FakeGL2();
|
||||
gl.texImage2D(0x0de1, 0, 0x1908, 0x1908, 0x1401, video);
|
||||
|
||||
expect(gl.lastImageArgs?.[gl.lastImageArgs.length - 1]).toBe(video);
|
||||
});
|
||||
|
||||
it("also patches texSubImage2D", () => {
|
||||
patchWebGLVideoTextureCompat();
|
||||
|
||||
const video = document.createElement("video");
|
||||
const img = makeInjectedImage();
|
||||
document.body.append(video, img);
|
||||
|
||||
const gl = new FakeGL2();
|
||||
gl.texSubImage2D(0x0de1, 0, 0, 0, 0x1908, 0x1401, video);
|
||||
|
||||
expect(gl.lastSubArgs?.[gl.lastSubArgs.length - 1]).toBe(img);
|
||||
});
|
||||
|
||||
it("does not touch numeric/pixel-data overloads (no video source)", () => {
|
||||
patchWebGLVideoTextureCompat();
|
||||
|
||||
const pixels = new Uint8Array([1, 2, 3, 4]);
|
||||
const gl = new FakeGL2();
|
||||
gl.texImage2D(0x0de1, 0, 0x1908, 1, 1, 0, 0x1908, 0x1401, pixels);
|
||||
|
||||
expect(gl.lastImageArgs?.[gl.lastImageArgs.length - 1]).toBe(pixels);
|
||||
});
|
||||
|
||||
it("is idempotent — patching twice does not double-wrap", () => {
|
||||
patchWebGLVideoTextureCompat();
|
||||
const once = FakeGL2.prototype.texImage2D;
|
||||
patchWebGLVideoTextureCompat();
|
||||
expect(FakeGL2.prototype.texImage2D).toBe(once);
|
||||
});
|
||||
});
|
||||
@@ -1,18 +1,47 @@
|
||||
/**
|
||||
* Patches `GPUQueue.copyExternalImageToTexture` so that video-backed WebGPU
|
||||
* effects work in both preview and render mode.
|
||||
* Patches GPU texture-upload paths so that video-backed effects work in both
|
||||
* preview and render mode — for WebGPU (`GPUQueue.copyExternalImageToTexture`)
|
||||
* and WebGL (`texImage2D` / `texSubImage2D`).
|
||||
*
|
||||
* During render, the engine's video-frame injector replaces each `<video>`
|
||||
* with a pre-decoded `<img class="__render_frame__">` sibling. Chrome's
|
||||
* headless compositor can't supply decoded frames from the native `<video>`
|
||||
* element to WebGPU, so `copyExternalImageToTexture({ source: video })`
|
||||
* fails with "Browser fails extracting valid resource from external image."
|
||||
*
|
||||
* This patch checks whether a render-frame `<img>` exists next to the
|
||||
* source `<video>`. If it does and has decoded pixels, the patch
|
||||
* transparently substitutes it as the copy source. In preview mode (no
|
||||
* render-frame sibling), the original video path is used unchanged.
|
||||
* element to the GPU, so uploading a `<video>` directly fails (WebGPU throws
|
||||
* "Browser fails extracting valid resource from external image"; WebGL uploads
|
||||
* a black/stale frame). These patches transparently substitute the decoded
|
||||
* render-frame `<img>` as the upload source. In preview mode (no render-frame
|
||||
* sibling), the original `<video>` path is used unchanged.
|
||||
*/
|
||||
|
||||
/**
|
||||
* Resolve the decoded render-frame `<img>` for a source `<video>`, if the
|
||||
* engine has injected one and it has decoded pixels. Returns null in preview
|
||||
* mode or before the frame is decoded, so callers fall back to the video.
|
||||
*
|
||||
* The injector inserts the `<img>` as the video's immediate next sibling and
|
||||
* also gives it the id `__render_frame_<videoId>__`; we check the sibling
|
||||
* first (cheap) and fall back to an id lookup in case a node was inserted
|
||||
* between them.
|
||||
*/
|
||||
function resolveRenderFrameImage(video: HTMLVideoElement): HTMLImageElement | null {
|
||||
const sibling = video.nextElementSibling;
|
||||
if (
|
||||
sibling instanceof HTMLImageElement &&
|
||||
sibling.classList.contains("__render_frame__") &&
|
||||
sibling.complete &&
|
||||
sibling.naturalWidth > 0
|
||||
) {
|
||||
return sibling;
|
||||
}
|
||||
if (video.id) {
|
||||
const byId = document.getElementById(`__render_frame_${video.id}__`);
|
||||
if (byId instanceof HTMLImageElement && byId.complete && byId.naturalWidth > 0) {
|
||||
return byId;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export function patchVideoTextureCompat(): void {
|
||||
const GPUQueueCtor = (globalThis as Record<string, unknown>).GPUQueue as
|
||||
| { prototype: Record<string, unknown> }
|
||||
@@ -32,16 +61,51 @@ export function patchVideoTextureCompat(): void {
|
||||
copySize: unknown,
|
||||
) {
|
||||
if (source?.source instanceof HTMLVideoElement) {
|
||||
const sibling = source.source.nextElementSibling;
|
||||
if (
|
||||
sibling instanceof HTMLImageElement &&
|
||||
sibling.classList.contains("__render_frame__") &&
|
||||
sibling.complete &&
|
||||
sibling.naturalWidth > 0
|
||||
) {
|
||||
return orig.call(this, { ...source, source: sibling }, destination, copySize);
|
||||
const img = resolveRenderFrameImage(source.source);
|
||||
if (img) {
|
||||
return orig.call(this, { ...source, source: img }, destination, copySize);
|
||||
}
|
||||
}
|
||||
return orig.call(this, source, destination, copySize);
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* WebGL analog of {@link patchVideoTextureCompat}. Patches `texImage2D` and
|
||||
* `texSubImage2D` on both `WebGL2RenderingContext` and `WebGLRenderingContext`
|
||||
* so that when a `<video>` is passed as the texture source (the last argument
|
||||
* in the DOM-source overloads), the decoded render-frame `<img>` is uploaded
|
||||
* instead during render. Numeric/`ArrayBufferView` overloads are untouched —
|
||||
* only a trailing `HTMLVideoElement` argument is substituted.
|
||||
*/
|
||||
export function patchWebGLVideoTextureCompat(): void {
|
||||
const ctors = [
|
||||
(globalThis as Record<string, unknown>).WebGL2RenderingContext,
|
||||
(globalThis as Record<string, unknown>).WebGLRenderingContext,
|
||||
] as Array<{ prototype: Record<string, unknown> } | undefined>;
|
||||
|
||||
const methods = ["texImage2D", "texSubImage2D"] as const;
|
||||
|
||||
for (const ctor of ctors) {
|
||||
const proto = ctor?.prototype;
|
||||
if (!proto) continue;
|
||||
for (const method of methods) {
|
||||
const orig = proto[method] as ((...args: unknown[]) => unknown) & {
|
||||
__hfVideoPatched?: boolean;
|
||||
};
|
||||
if (typeof orig !== "function" || orig.__hfVideoPatched) continue;
|
||||
|
||||
const patched = function (this: unknown, ...args: unknown[]) {
|
||||
const lastIndex = args.length - 1;
|
||||
const last = args[lastIndex];
|
||||
if (last instanceof HTMLVideoElement) {
|
||||
const img = resolveRenderFrameImage(last);
|
||||
if (img) args[lastIndex] = img;
|
||||
}
|
||||
return orig.apply(this, args);
|
||||
} as ((...args: unknown[]) => unknown) & { __hfVideoPatched?: boolean };
|
||||
patched.__hfVideoPatched = true;
|
||||
proto[method] = patched;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -7,7 +7,11 @@ import { createAnimeJsAdapter } from "./adapters/animejs";
|
||||
import { createLottieAdapter } from "./adapters/lottie";
|
||||
import { createThreeAdapter } from "./adapters/three";
|
||||
import { createTypegpuAdapter } from "./adapters/typegpu";
|
||||
import { patchVideoTextureCompat } from "./adapters/video-texture-compat";
|
||||
import {
|
||||
patchVideoTextureCompat,
|
||||
patchWebGLVideoTextureCompat,
|
||||
} from "./adapters/video-texture-compat";
|
||||
import { forceDispatchSeekEvent } from "./adapters/seek-dispatch";
|
||||
import { createWaapiAdapter } from "./adapters/waapi";
|
||||
import { refreshRuntimeMediaCache, syncRuntimeMedia } from "./media";
|
||||
import { probeAndCacheElementVolume, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
|
||||
@@ -1795,6 +1799,15 @@ export function initSandboxRuntimeModular(): void {
|
||||
createGsapAdapter({ getTimeline: () => state.capturedTimeline }),
|
||||
] as RuntimeDeterministicAdapter[];
|
||||
patchVideoTextureCompat();
|
||||
patchWebGLVideoTextureCompat();
|
||||
// Lets the engine re-render GPU compositions after it injects decoded video
|
||||
// frames, so video-textured WebGL/WebGPU scenes sample the correct frame.
|
||||
window.__hfReseekGpu = (time: number) => {
|
||||
const t = Math.max(0, Number(time) || 0);
|
||||
window.__hfThreeTime = t;
|
||||
window.__hfTypegpuTime = t;
|
||||
forceDispatchSeekEvent(t);
|
||||
};
|
||||
installRuntimeErrorDiagnostics();
|
||||
bindMediaMetadataListeners();
|
||||
runAdapters("discover");
|
||||
|
||||
+7
@@ -45,6 +45,13 @@ declare global {
|
||||
* imperative push signal: `window.addEventListener("hf-seek", e => render(e.detail.time))`.
|
||||
*/
|
||||
__hfTypegpuTime?: number;
|
||||
/**
|
||||
* Re-render GPU adapters (Three.js / WebGPU) at the given time, bypassing
|
||||
* the `"hf-seek"` dedup. Called by the engine after injecting decoded
|
||||
* video frames so GPU compositions re-upload their video textures from the
|
||||
* freshly-injected `__render_frame__` images. See `forceDispatchSeekEvent`.
|
||||
*/
|
||||
__hfReseekGpu?: (time: number) => void;
|
||||
__HF_PICKER_API?: HyperframePickerApi;
|
||||
gsap?: {
|
||||
timeline: (params?: { paused?: boolean }) => RuntimeTimelineLike;
|
||||
|
||||
Reference in New Issue
Block a user