Skip to content

Commit 8c00eba

Browse files
fix(core): show a scene's starting state on a render's first frame (#5614)
* fix(core): show a scene's starting state on a render's first frame A seek to the time a GSAP timeline already sits at renders nothing, so a sub-composition timeline at 0 never applied its t=0 steps before frame 0 was captured. Every runtime seek now goes through seekGsapTimeline, which redraws the timeline silently when the seek did not move it. * test(producer): share the frame-level reader across render tests * fix(core): name the in-place render skip instead of commenting it * perf(core): redraw a parked scene timeline once instead of every frame * fix(core): redraw only a scene timeline GSAP has never drawn
1 parent c0636d0 commit 8c00eba

9 files changed

Lines changed: 250 additions & 40 deletions

File tree

‎packages/core/src/runtime/adapters/gsap.steps.test.ts‎

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
// @vitest-environment happy-dom
22
import gsap from "gsap";
33
import { describe, expect, it } from "vitest";
4-
import { createGsapAdapter, rerenderGsapTimelineAt } from "./gsap";
4+
import { createGsapAdapter, rerenderGsapTimelineAt, seekGsapTimeline } from "./gsap";
55
import type { RuntimeTimelineLike } from "../types";
66

77
// Every 0.1 s: hide all three frames, then show one, as frame-by-frame films do.
@@ -531,3 +531,51 @@ describe("gsap adapter just after a tween's start", () => {
531531
}
532532
});
533533
});
534+
535+
describe("seekGsapTimeline", () => {
536+
function hiddenAtZero() {
537+
const word = document.body.appendChild(document.createElement("span"));
538+
let calls = 0;
539+
const timeline = gsap.timeline({ paused: true });
540+
timeline.set(word, { visibility: "hidden" }, 0);
541+
timeline.call(() => void calls++, [], 0);
542+
timeline.set(word, { visibility: "visible" }, 0.5);
543+
return { word, timeline: timeline as unknown as RuntimeTimelineLike, calls: () => calls };
544+
}
545+
546+
it("renders a never-rendered timeline seeked to the time it sits at", () => {
547+
const film = hiddenAtZero();
548+
seekGsapTimeline(film.timeline, 0, false);
549+
expect(film.word.style.visibility).toBe("hidden");
550+
});
551+
552+
it("redraws a timeline parked at one time once, not on every seek", () => {
553+
const film = hiddenAtZero();
554+
const real = film.timeline;
555+
let moves = 0;
556+
const counted = {
557+
...real,
558+
time: () => real.time(),
559+
totalTime: (time?: number, suppressEvents?: boolean) => {
560+
if (time === undefined) return real.totalTime!();
561+
moves++;
562+
return real.totalTime!(time, suppressEvents);
563+
},
564+
getChildren: real.getChildren!.bind(real),
565+
} as RuntimeTimelineLike;
566+
seekGsapTimeline(counted, 0, false);
567+
const firstSeekMoves = moves;
568+
seekGsapTimeline(counted, 0, false);
569+
seekGsapTimeline(counted, 0, false);
570+
expect(firstSeekMoves).toBeGreaterThan(1);
571+
expect(moves - firstSeekMoves).toBe(2);
572+
});
573+
574+
it("fires a call at that time once across the next seeks", () => {
575+
const film = hiddenAtZero();
576+
seekGsapTimeline(film.timeline, 0, false);
577+
seekGsapTimeline(film.timeline, 0, false);
578+
seekGsapTimeline(film.timeline, 0.1, false);
579+
expect(film.calls()).toBe(1);
580+
});
581+
});

‎packages/core/src/runtime/adapters/gsap.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,37 @@ export function rerenderGsapTimelineAt(
4949
}
5050
}
5151

52+
type GsapRenderState = { _initted?: number };
53+
54+
function gsapNeverRendered(timeline: RuntimeTimelineLike): boolean {
55+
const [child] = (timeline.getChildren?.(false, true, true) ?? []) as { parent?: unknown }[];
56+
const rendered = child?.parent as GsapRenderState | undefined;
57+
return rendered !== undefined && !rendered._initted;
58+
}
59+
60+
export function seekGsapTimeline(
61+
timeline: RuntimeTimelineLike,
62+
t: number,
63+
suppressEvents: boolean,
64+
): boolean {
65+
if (typeof timeline.totalTime !== "function") {
66+
timeline.seek(t, suppressEvents);
67+
return false;
68+
}
69+
const gsapSkipsRenderInPlace = Number(timeline.totalTime()) === t;
70+
timeline.totalTime(t, suppressEvents);
71+
if (!gsapSkipsRenderInPlace || !gsapNeverRendered(timeline)) return false;
72+
rerenderGsapTimelineAt(
73+
{
74+
totalTime: timeline.totalTime.bind(timeline),
75+
totalDuration: timeline.totalDuration?.bind(timeline),
76+
getChildren: timeline.getChildren?.bind(timeline),
77+
},
78+
t,
79+
);
80+
return true;
81+
}
82+
5283
type GsapParent = {
5384
_dur: number;
5485
_tDur: number;

‎packages/core/src/runtime/init.test.ts‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3119,7 +3119,7 @@ describe("initSandboxRuntimeModular", () => {
31193119
const rootTimeline = createMockTimeline(10);
31203120
const originalTotalTime = rootTimeline.totalTime;
31213121
rootTimeline.totalTime = (time: number, suppressEvents?: boolean) => {
3122-
seekCalls.push({ time, suppressEvents });
3122+
if (time !== undefined) seekCalls.push({ time, suppressEvents });
31233123
return originalTotalTime?.(time, suppressEvents);
31243124
};
31253125

@@ -3155,7 +3155,7 @@ describe("initSandboxRuntimeModular", () => {
31553155
const rootTimeline = createMockTimeline(10);
31563156
const originalTotalTime = rootTimeline.totalTime;
31573157
rootTimeline.totalTime = (time: number, suppressEvents?: boolean) => {
3158-
seekCalls.push({ time, suppressEvents });
3158+
if (time !== undefined) seekCalls.push({ time, suppressEvents });
31593159
return originalTotalTime?.(time, suppressEvents);
31603160
};
31613161
Object.assign(rootTimeline, {
@@ -3177,6 +3177,26 @@ describe("initSandboxRuntimeModular", () => {
31773177
expect(seekCalls).toEqual([{ time: 2, suppressEvents: false }]);
31783178
});
31793179

3180+
it("keeps a later root tween's value over a nested scene the root already drew", () => {
3181+
document.body.innerHTML = `<div data-composition-id="main" data-root="true" data-start="0" data-duration="2" data-width="1920" data-height="1080"><div data-composition-id="child" data-start="0" data-duration="2"><div id="box"></div></div></div>`;
3182+
const box = document.getElementById("box")!;
3183+
const options = { duration: 2, ease: "none", immediateRender: false, lazy: false };
3184+
const child = gsap.timeline({ smoothChildTiming: false });
3185+
child.fromTo(box, { opacity: 0 }, { ...options, opacity: 1, overwrite: false }, 0);
3186+
const main = gsap.timeline({ paused: true, smoothChildTiming: false });
3187+
main.add(child, 0);
3188+
main.fromTo(box, { opacity: 0.8 }, { ...options, opacity: 1, overwrite: false }, 0);
3189+
window.__timelines = { main, child };
3190+
initSandboxRuntimeModular();
3191+
3192+
window.__player?.renderSeek(1);
3193+
expect(Number(box.style.opacity)).toBeCloseTo(0.9, 5);
3194+
3195+
child.set({}, {}, 1.5);
3196+
window.__player?.renderSeek(1);
3197+
expect(Number(box.style.opacity)).toBeCloseTo(0.9, 5);
3198+
});
3199+
31803200
it("fires a call added after the first seek exactly once", () => {
31813201
const root = document.createElement("div");
31823202
root.setAttribute("data-composition-id", "main");

‎packages/core/src/runtime/init.ts‎

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import {
1616
import { initRuntimeAnalytics, emitAnalyticsEvent } from "./analytics";
1717
import { injectCompositionCssVariables } from "./getVariables";
1818
import { createCssAdapter } from "./adapters/css";
19-
import { createGsapAdapter, rerenderGsapTimelineAt } from "./adapters/gsap";
19+
import { createGsapAdapter, rerenderGsapTimelineAt, seekGsapTimeline } from "./adapters/gsap";
2020
import { createAnimeJsAdapter } from "./adapters/animejs";
2121
import { createLottieAdapter } from "./adapters/lottie";
2222
import { createThreeAdapter } from "./adapters/three";
@@ -1663,8 +1663,7 @@ export function initSandboxRuntimeModular(): void {
16631663
// Without this, children added after the root was created may still show initial styles.
16641664
if (autoNestedChildren.length > 0) {
16651665
try {
1666-
const currentTime = rootTimeline.time();
1667-
rootTimeline.seek(currentTime, false); // false = don't suppress events
1666+
seekGsapTimeline(rootTimeline, rootTimeline.time(), false);
16681667
} catch {
16691668
/* ignore */
16701669
}
@@ -2323,7 +2322,7 @@ export function initSandboxRuntimeModular(): void {
23232322
// abort restoring the transport time below (the catch would swallow it too).
23242323
pauseTimelineIfPossible(state.capturedTimeline);
23252324
if (typeof state.capturedTimeline.seek === "function") {
2326-
state.capturedTimeline.seek(previousTime, false);
2325+
seekGsapTimeline(state.capturedTimeline, previousTime, false);
23272326
}
23282327
} catch (err) {
23292328
// keep runtime resilient even if a timeline implementation throws
@@ -4240,11 +4239,7 @@ export function initSandboxRuntimeModular(): void {
42404239
const suppressEvents = options?.suppressEvents === true;
42414240
// Guarded: a partial timeline without pause() must still get its seek.
42424241
pauseTimelineIfPossible(timeline);
4243-
if (typeof timeline.totalTime === "function") {
4244-
timeline.totalTime(timeSeconds, suppressEvents);
4245-
} else {
4246-
timeline.seek(timeSeconds, suppressEvents);
4247-
}
4242+
seekGsapTimeline(timeline, timeSeconds, suppressEvents);
42484243
} catch (err) {
42494244
swallow(swallowLabel, err);
42504245
}
@@ -4399,8 +4394,8 @@ export function initSandboxRuntimeModular(): void {
43994394
}
44004395
try {
44014396
if (typeof tl.totalTime === "function") {
4402-
tl.totalTime(tlSeekTime, suppressEvents);
4403-
if (!suppressEvents && !hasZeroDurationCallbackTween(tl)) {
4397+
const redrawn = seekGsapTimeline(tl, tlSeekTime, suppressEvents);
4398+
if (!redrawn && !suppressEvents && !hasZeroDurationCallbackTween(tl)) {
44044399
// The first seek is the only eventful one; the re-render only refreshes styles.
44054400
rerenderGsapTimelineAt(
44064401
{

‎packages/producer/scripts/test-classification.mjs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ const INTEGRATION_TEST_FILES = new Set([
3030
"src/services/assetMediaType.test.ts",
3131
"src/services/htmlCompiler.mediaType.test.ts",
3232
"src/services/htmlCompiler.naturalDuration.test.ts",
33+
"src/services/render/firstFrameStartingState.integration.test.ts",
3334
"src/services/render/hlsRender.integration.test.ts",
3435
"src/services/render/motionBlurVideo.integration.test.ts",
3536
"src/services/render/renderCancel.integration.test.ts",
Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
// Frame 0 of a real render shows the starting state that a sub-composition's timeline sets at
2+
// t=0, not the page's pre-timeline styles. Needs Chrome + ffmpeg: integration lane.
3+
4+
import { copyFileSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
5+
import { tmpdir } from "node:os";
6+
import { join, resolve } from "node:path";
7+
import { afterAll, beforeAll, describe, expect, it } from "vitest";
8+
import { resolveConfig } from "@hyperframes/engine";
9+
import { createRenderJob, executeRenderJob } from "../renderOrchestrator.js";
10+
import { HAS_FFMPEG, frameLevels } from "./frameLevelsTestFixtures.js";
11+
12+
const WIDTH = 160;
13+
const HEIGHT = 90;
14+
const FPS = 30;
15+
const REVEAL_FRAME = 15;
16+
17+
const INDEX = `<!DOCTYPE html>
18+
<html lang="en">
19+
<head>
20+
<meta charset="UTF-8" />
21+
<script src="assets/gsap.min.js"></script>
22+
<style>* { margin: 0; padding: 0; } body { overflow: hidden; background: #000; }</style>
23+
</head>
24+
<body>
25+
<div id="root" data-composition-id="main" data-start="0" data-duration="1"
26+
data-width="${WIDTH}" data-height="${HEIGHT}" data-fps="${FPS}">
27+
<div id="s-words" data-composition-id="words" data-composition-src="compositions/words.html"
28+
data-start="0" data-duration="1" data-track-index="0"
29+
data-width="${WIDTH}" data-height="${HEIGHT}"></div>
30+
</div>
31+
<script>window.__timelines["main"] = gsap.timeline({ paused: true });</script>
32+
</body>
33+
</html>
34+
`;
35+
36+
// The words have no hidden CSS state: only the timeline's t=0 steps hide them.
37+
const WORDS = `<!DOCTYPE html>
38+
<html>
39+
<body>
40+
<template id="words-template">
41+
<style>
42+
@font-face { font-family: "Fixture"; src: url("assets/fixture.woff2") format("woff2"); font-weight: 500; }
43+
#words { position: absolute; inset: 0; background: #000; }
44+
#words .w { position: absolute; top: 20px; font: 500 40px "Fixture", serif; color: #fff; }
45+
</style>
46+
<div id="words" data-composition-id="words" data-width="${WIDTH}" data-height="${HEIGHT}" data-duration="1">
47+
<span class="w">Aa</span><span class="w">Bb</span>
48+
</div>
49+
<script>
50+
(() => {
51+
const tl = gsap.timeline({ paused: true });
52+
const words = [...document.querySelectorAll("#words .w")];
53+
words.forEach((w) => tl.set(w, { visibility: "hidden" }, 0));
54+
words.forEach((w, i) => tl.set(w, { visibility: "visible", left: 10 + i * 70 }, ${REVEAL_FRAME / FPS}));
55+
tl.set({}, {}, 1);
56+
window.__timelines["words"] = tl;
57+
})();
58+
</script>
59+
</template>
60+
</body>
61+
</html>
62+
`;
63+
64+
let root: string;
65+
66+
describe.skipIf(!HAS_FFMPEG)(
67+
"first frame of a real render — sub-composition starting state",
68+
() => {
69+
let levels: number[];
70+
71+
beforeAll(async () => {
72+
root = mkdtempSync(join(tmpdir(), "hf-first-frame-"));
73+
mkdirSync(join(root, "assets"), { recursive: true });
74+
mkdirSync(join(root, "compositions"), { recursive: true });
75+
copyFileSync(
76+
resolve(import.meta.dirname, "../../../../core/node_modules/gsap/dist/gsap.min.js"),
77+
join(root, "assets/gsap.min.js"),
78+
);
79+
copyFileSync(
80+
resolve(
81+
import.meta.dirname,
82+
"../../../tests/heygen-promo-preview-assets/src/TT_Norms_Pro_Medium.woff2",
83+
),
84+
join(root, "assets/fixture.woff2"),
85+
);
86+
writeFileSync(join(root, "index.html"), INDEX);
87+
writeFileSync(join(root, "compositions/words.html"), WORDS);
88+
const job = createRenderJob({
89+
fps: FPS,
90+
quality: "draft",
91+
format: "mp4",
92+
hdrMode: "force-sdr",
93+
workers: 1,
94+
producerConfig: resolveConfig({ browserGpuMode: "software" }),
95+
});
96+
const output = join(root, "out.mp4");
97+
await executeRenderJob(job, root, output);
98+
levels = frameLevels(output, WIDTH, HEIGHT);
99+
}, 120_000);
100+
101+
afterAll(() => {
102+
if (root) rmSync(root, { recursive: true, force: true });
103+
});
104+
105+
it("frame 0 matches frame 1: the words are already hidden", () => {
106+
expect(levels[0]).toBeCloseTo(levels[1]!, 0);
107+
expect(levels[0]).toBeLessThan(1);
108+
});
109+
110+
it("the words appear when the timeline reveals them", () => {
111+
expect(levels[REVEAL_FRAME]! - levels[0]!).toBeGreaterThan(2);
112+
});
113+
},
114+
);
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
import { spawnSync } from "node:child_process";
2+
import { getFfmpegBinary } from "@hyperframes/engine";
3+
4+
export const FFMPEG = getFfmpegBinary();
5+
export const HAS_FFMPEG = spawnSync(FFMPEG, ["-version"], { encoding: "utf-8" }).status === 0;
6+
7+
/** Mean grey level of every frame of an encoded video, 0-255. */
8+
export function frameLevels(videoPath: string, width: number, height: number): number[] {
9+
const raw = spawnSync(
10+
FFMPEG,
11+
["-v", "error", "-i", videoPath, "-f", "rawvideo", "-pix_fmt", "gray", "-"],
12+
{ maxBuffer: 64 * 1024 * 1024 },
13+
);
14+
if (raw.status !== 0) throw new Error(`decode failed: ${raw.stderr}`);
15+
const frameBytes = width * height;
16+
const levels: number[] = [];
17+
for (let offset = 0; offset + frameBytes <= raw.stdout.length; offset += frameBytes) {
18+
let sum = 0;
19+
for (let i = offset; i < offset + frameBytes; i++) sum += raw.stdout[i]!;
20+
levels.push(sum / frameBytes);
21+
}
22+
return levels;
23+
}

‎packages/producer/src/services/render/segmentedColorGrading.integration.test.ts‎

Lines changed: 3 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,9 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
77
import { tmpdir } from "node:os";
88
import { join } from "node:path";
99
import { afterAll, beforeAll, describe, expect, it } from "vitest";
10-
import { getFfmpegBinary, resolveConfig } from "@hyperframes/engine";
10+
import { resolveConfig } from "@hyperframes/engine";
1111
import { createRenderJob, executeRenderJob } from "../renderOrchestrator.js";
12-
13-
const FFMPEG = getFfmpegBinary();
14-
const HAS_FFMPEG = spawnSync(FFMPEG, ["-version"], { encoding: "utf-8" }).status === 0;
12+
import { FFMPEG, HAS_FFMPEG, frameLevels } from "./frameLevelsTestFixtures.js";
1513

1614
const WIDTH = 160;
1715
const HEIGHT = 90;
@@ -55,26 +53,6 @@ const COMPOSITION = `<!DOCTYPE html>
5553

5654
let root: string;
5755

58-
/** Mean RGB level of every frame of an encoded video, 0-255. */
59-
function frameLevels(videoPath: string): number[] {
60-
const raw = spawnSync(
61-
FFMPEG,
62-
["-v", "error", "-i", videoPath, "-f", "rawvideo", "-pix_fmt", "gray", "-"],
63-
{
64-
maxBuffer: 64 * 1024 * 1024,
65-
},
66-
);
67-
if (raw.status !== 0) throw new Error(`decode failed: ${raw.stderr}`);
68-
const frameBytes = WIDTH * HEIGHT;
69-
const levels: number[] = [];
70-
for (let offset = 0; offset + frameBytes <= raw.stdout.length; offset += frameBytes) {
71-
let sum = 0;
72-
for (let i = offset; i < offset + frameBytes; i++) sum += raw.stdout[i]!;
73-
levels.push(sum / frameBytes);
74-
}
75-
return levels;
76-
}
77-
7856
interface Render {
7957
levels: number[];
8058
phases: string[];
@@ -112,7 +90,7 @@ async function render(name: string, segmented: boolean, workers: number): Promis
11290
try {
11391
const output = join(root, `${name}.mp4`);
11492
await executeRenderJob(job, root, output);
115-
return { levels: frameLevels(output), phases, workerCount };
93+
return { levels: frameLevels(output, WIDTH, HEIGHT), phases, workerCount };
11694
} finally {
11795
if (saved.capture === undefined) delete process.env.HF_SEGMENTED_CAPTURE;
11896
else process.env.HF_SEGMENTED_CAPTURE = saved.capture;

0 commit comments

Comments
 (0)