Skip to content

Write HTML. Render video. Built for agents.

fix(cli): capture snapshot --at at the exact requested instant (#4827)

HEOJUNFO8aefd91bf82c
diff --git a/packages/cli/src/capture/captureCompositionFrame.test.ts b/packages/cli/src/capture/captureCompositionFrame.test.ts
index 1fd125fbcc..7c3c0699cb 100644
--- a/packages/cli/src/capture/captureCompositionFrame.test.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.test.ts
@@ -56,7 +56,7 @@ describe("seekCompositionTimeline", () => {
expect(waitForFunction).not.toHaveBeenCalled();
expect(evaluate).toHaveBeenCalledTimes(4);
- expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 1.25, false);
+ expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 1.25, false, false);
expect(evaluate).toHaveBeenNthCalledWith(2, expect.any(Function));
expect(evaluate.mock.calls[2]?.[0]).toContain("window.setTimeout(finish, 100)");
// Post-seek font settle: a seek can reveal glyphs whose unicode-range
@@ -93,6 +93,17 @@ describe("seekCompositionTimeline", () => {
expect(timelineSeek).not.toHaveBeenCalled();
});
+ it("asks renderSeek for the exact instant when exactTime is set", async () => {
+ const { page, evaluate } = fakeSeekPage();
+ const renderSeek = vi.fn();
+ vi.stubGlobal("window", { __player: { renderSeek } });
+
+ await seekCompositionTimeline(page, 19.019018, { exactTime: true });
+ runBrowserSeek(evaluate);
+
+ expect(renderSeek).toHaveBeenCalledWith(19.019018, { exact: true });
+ });
+
function fakeBridgeOnlySeekPage() {
const { page, evaluate } = fakeSeekPage();
const bridgeSeek = vi.fn();
@@ -150,7 +161,7 @@ describe("seekCompositionTimeline", () => {
expect(waitForFunction).toHaveBeenCalledWith(expect.any(Function), { timeout: 500 });
expect(evaluate).toHaveBeenCalledTimes(2);
- expect(evaluate).toHaveBeenCalledWith(expect.any(Function), 3, true);
+ expect(evaluate).toHaveBeenCalledWith(expect.any(Function), 3, true, false);
});
it("supports layout's ordered double-frame, bounded font, and sleep settles", async () => {
@@ -167,7 +178,7 @@ describe("seekCompositionTimeline", () => {
await pending;
expect(evaluate).toHaveBeenCalledTimes(4);
- expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 4, true);
+ expect(evaluate).toHaveBeenNthCalledWith(1, expect.any(Function), 4, true, false);
expect(evaluate).toHaveBeenNthCalledWith(2, expect.any(Function));
expect(evaluate).toHaveBeenNthCalledWith(3, expect.any(Function));
expect(evaluate).toHaveBeenNthCalledWith(4, expect.any(Function), 500);
diff --git a/packages/cli/src/capture/captureCompositionFrame.ts b/packages/cli/src/capture/captureCompositionFrame.ts
index df0b49b4eb..4b0aa39211 100644
--- a/packages/cli/src/capture/captureCompositionFrame.ts
+++ b/packages/cli/src/capture/captureCompositionFrame.ts
@@ -37,6 +37,7 @@ export const DENSE_GEOMETRY_SEEK_OPTIONS = {
export interface SeekCompositionTimelineOptions {
fallbackToBridgeAndTimelines?: boolean;
+ exactTime?: boolean;
waitForPreferredSeekTargetMs?: number;
animationFrameSettle?: "race" | "double" | "none";
waitForFontsMs?: number;
@@ -47,13 +48,14 @@ type CompositionPageFunction =
| string
| (() => unknown)
| ((value: number) => unknown)
- | ((value: number, fallbackToBridgeAndTimelines: boolean) => unknown);
+ | ((value: number, fallbackToBridgeAndTimelines: boolean, exactTime: boolean) => unknown);
export interface CompositionEvaluationPage {
evaluate(
pageFunction: CompositionPageFunction,
value?: number,
fallbackToBridgeAndTimelines?: boolean,
+ exactTime?: boolean,
): Promise<unknown>;
}
@@ -247,7 +249,7 @@ export async function seekCompositionTimeline(
await page.evaluate(
// Serialized into the page; the seek-target cascade must stay one function.
// fallow-ignore-next-line complexity
- (t: number, fallbackToBridgeAndTimelines: boolean) => {
+ (t: number, fallbackToBridgeAndTimelines: boolean, exactTime: boolean) => {
const getProperty = (target: unknown, key: string): unknown => {
if ((typeof target !== "object" || target === null) && typeof target !== "function") {
return undefined;
@@ -271,7 +273,7 @@ export async function seekCompositionTimeline(
// Prefer renderSeek because it also runs the runtime's data-start/data-duration
// visibility sync; raw timeline seeks leave off-window clips visible to audits.
- if (call(renderSeek, player, [safe])) {
+ if (call(renderSeek, player, exactTime ? [safe, { exact: true }] : [safe])) {
// Preferred runtime target handled the seek.
} else if (fallbackToBridgeAndTimelines && call(bridgeSeek, hf, [safe])) {
// Producer bridge handled the seek.
@@ -294,6 +296,7 @@ export async function seekCompositionTimeline(
},
timeSeconds,
options.fallbackToBridgeAndTimelines === true,
+ options.exactTime === true,
);
await page.evaluate(async () => {
diff --git a/packages/cli/src/commands/snapshot.test.ts b/packages/cli/src/commands/snapshot.test.ts
index 7fd4db398c..992de2bbc9 100644
--- a/packages/cli/src/commands/snapshot.test.ts
+++ b/packages/cli/src/commands/snapshot.test.ts
@@ -8,15 +8,19 @@ import { findFFmpeg } from "../browser/ffmpeg.js";
import { sourceTimeAt } from "@hyperframes/core";
const snapshotState = vi.hoisted(() => ({
- openSettledPage: vi.fn(async () => {
+ openSettledPage: vi.fn(async (): Promise<unknown> => {
throw new Error("browser capture reached");
}),
+ seek: vi.fn(async (_page: unknown, _time: number, _options?: unknown): Promise<void> => {
+ throw new Error("seek reached");
+ }),
closeServer: vi.fn(async () => undefined),
}));
vi.mock("../capture/captureCompositionFrame.js", async (importOriginal) => ({
...(await importOriginal<typeof import("../capture/captureCompositionFrame.js")>()),
openSettledCompositionPage: snapshotState.openSettledPage,
+ seekCompositionTimeline: snapshotState.seek,
}));
vi.mock("../utils/staticProjectServer.js", () => ({
@@ -150,6 +154,44 @@ describe("snapshot lint preflight", () => {
});
});
+describe("snapshot --at seeks", () => {
+ it("asks the runtime for the exact requested instant, not its 30fps grid", async () => {
+ const project = mkdtempSync(join(tmpdir(), "hf-snapshot-exact-at-"));
+ writeFileSync(
+ join(project, "index.html"),
+ `<html><body><div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="20" data-fps="29.97"><div class="clip" data-start="0" data-duration="20">Visible</div></div></body></html>`,
+ );
+ const evaluate = vi
+ .fn()
+ .mockResolvedValueOnce({ loaded: [], errored: [], unused: [] })
+ .mockResolvedValueOnce(20)
+ .mockResolvedValueOnce(true);
+ const close = vi.fn(async () => undefined);
+ snapshotState.openSettledPage.mockResolvedValueOnce({
+ browser: { close },
+ page: { evaluate },
+ renderReadyTimedOut: false,
+ });
+ snapshotState.seek.mockClear();
+ const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
+
+ try {
+ await expect(
+ snapshotCommand.run?.({
+ args: { dir: project, at: "19.019018", end: false, output: join(project, "out") },
+ } as never),
+ ).rejects.toBeDefined();
+ expect(snapshotState.seek).toHaveBeenCalledWith(expect.anything(), 19.019018, {
+ exactTime: true,
+ });
+ expect(close).toHaveBeenCalled();
+ } finally {
+ log.mockRestore();
+ rmSync(project, { recursive: true, force: true });
+ }
+ });
+});
+
describe("resolveSnapshotVideoFrameTime", () => {
it("holds a clip ending with the composition on its last decodable frame", () => {
expect(
diff --git a/packages/cli/src/commands/snapshot.ts b/packages/cli/src/commands/snapshot.ts
index b091b3c6c1..f086ae6b3c 100644
--- a/packages/cli/src/commands/snapshot.ts
+++ b/packages/cli/src/commands/snapshot.ts
@@ -453,7 +453,7 @@ async function captureSnapshots(
for (let i = 0; i < positions.length; i++) {
const time = positions[i]!;
- await seekCompositionTimeline(page, time);
+ await seekCompositionTimeline(page, time, { exactTime: true });
if (cameraExpr) await page.evaluate(cameraExpr);
@@ -684,7 +684,8 @@ export default defineCommand({
},
at: {
type: "string",
- description: "Comma-separated timestamps in seconds (e.g., --at 3.0,10.5,18.0)",
+ description:
+ "Comma-separated timestamps in seconds (e.g., --at 3.0,10.5,18.0). Each is captured at that exact instant, not snapped to a frame.",
},
timeout: {
type: "string",
diff --git a/packages/core/src/runtime/init.test.ts b/packages/core/src/runtime/init.test.ts
index 76a95cbb2d..dcdf597591 100644
--- a/packages/core/src/runtime/init.test.ts
+++ b/packages/core/src/runtime/init.test.ts
@@ -1023,6 +1023,42 @@ describe("initSandboxRuntimeModular", () => {
expect(timeline.time()).toBe(0);
});
+ describe("issue #4430 sweep on a 29.97fps project", () => {
+ // `snapshot --at` times from the issue, with where the 30fps grid floors each one.
+ const sweep = [
+ { at: 19.019018, grid: 19 },
+ { at: 19.05, grid: 571 / 30 },
+ ];
+
+ function seekOnNtscProject(at: number, options?: { exact?: boolean }): number {
+ const root = document.createElement("div");
+ root.setAttribute("data-composition-id", "main");
+ root.setAttribute("data-root", "true");
+ root.setAttribute("data-start", "0");
+ root.setAttribute("data-duration", "20");
+ root.setAttribute("data-fps", "29.97");
+ root.setAttribute("data-width", "1920");
+ root.setAttribute("data-height", "1080");
+ document.body.appendChild(root);
+
+ const timeline = createMockTimeline(20);
+ window.__timelines = { main: timeline };
+
+ initSandboxRuntimeModular();
+ window.__player?.renderSeek(at, options);
+ return timeline.time();
+ }
+
+ it.each(sweep)("an exact renderSeek to $at lands on $at", ({ at }) => {
+ expect(seekOnNtscProject(at, { exact: true })).toBe(at);
+ });
+
+ // Frame export never passes `exact`, so its seeks keep flooring onto the frame grid.
+ it.each(sweep)("a default renderSeek to $at still floors to $grid", ({ at, grid }) => {
+ expect(seekOnNtscProject(at)).toBeCloseTo(grid, 9);
+ });
+ });
+
it("uses live child timeline duration when a composition host has no authored duration", () => {
const root = document.createElement("div");
root.setAttribute("data-composition-id", "main");
diff --git a/packages/core/src/runtime/init.ts b/packages/core/src/runtime/init.ts
index e5b60f33d5..8e10b5b0eb 100644
--- a/packages/core/src/runtime/init.ts
+++ b/packages/core/src/runtime/init.ts
@@ -44,7 +44,7 @@ import {
import { handleErrorForProxy, handleMetadataForProxy, maybeProxyProactively } from "./mediaProxy";
import { probeAndCacheElementVolume, type VolumeKeyframe } from "./mediaVolumeEnvelope.js";
import { createPickerModule } from "./picker";
-import { createRuntimePlayer, type RuntimePlayerTransport } from "./player";
+import { createRuntimePlayer, resolveRenderSeekTime, type RuntimePlayerTransport } from "./player";
import { createRuntimeState } from "./state";
import {
collectRuntimeTimelinePayload,
@@ -97,7 +97,7 @@ import {
isMemberGroupHidden,
} from "../audioGroups";
import { clampNativeMediaVolume } from "../audioGain";
-import { quantizeSeekTime, quantizeTimeToFrame } from "../inline-scripts/parityContract";
+import { quantizeTimeToFrame } from "../inline-scripts/parityContract";
import { createManualEditGestureWatch } from "./manualEditGestureWatch";
import type {
HeldSeek,
@@ -3905,15 +3905,15 @@ export function initSandboxRuntimeModular(): void {
renderSeek: (timeSeconds, options) => {
heldSeek = null;
renderCaptureSeekStarted = true;
- const quantized = quantizeSeekTime(
+ const seekTime = resolveRenderSeekTime(
Math.max(0, Number(timeSeconds) || 0),
state.canonicalFps,
- options?.subFrameDivisions,
+ options,
);
webAudio.stopAll();
clock.detachAudioSource();
if (clock.isPlaying()) clock.pause();
- clock.seek(quantized);
+ clock.seek(seekTime);
state.currentTime = clock.now();
state.isPlaying = false;
state.mediaForceSyncNextTick = true;
diff --git a/packages/core/src/runtime/player.test.ts b/packages/core/src/runtime/player.test.ts
index fde3b30e61..0a29309172 100644
--- a/packages/core/src/runtime/player.test.ts
+++ b/packages/core/src/runtime/player.test.ts
@@ -709,6 +709,15 @@ describe("renderSeek sub-frame grid (issue #4010 motion blur)", () => {
expect(timeline.time()).toBe(10 / 30);
});
+ it("lands on the requested instant, off every frame grid, for an exact seek", () => {
+ const timeline = createMockTimeline();
+ const player = createRuntimePlayer(createMockDeps(timeline));
+
+ player.renderSeek(10 / 30 + 0.017, { exact: true });
+
+ expect(timeline.time()).toBe(10 / 30 + 0.017);
+ });
+
it("suppresses timeline events on a sub-frame sample seek", () => {
const timeline = createMockTimeline();
const player = createRuntimePlayer(createMockDeps(timeline));
diff --git a/packages/core/src/runtime/player.ts b/packages/core/src/runtime/player.ts
index 7217dcea47..89a13e665d 100644
--- a/packages/core/src/runtime/player.ts
+++ b/packages/core/src/runtime/player.ts
@@ -83,13 +83,24 @@ function forEachSiblingTimeline(
}
}
+export function resolveRenderSeekTime(
+ timeSeconds: number,
+ canonicalFps: number,
+ options?: RuntimeSeekOptions,
+): number {
+ if (options?.exact === true) {
+ return Number.isFinite(timeSeconds) && timeSeconds > 0 ? timeSeconds : 0;
+ }
+ return quantizeSeekTime(timeSeconds, canonicalFps, options?.subFrameDivisions);
+}
+
function seekTimelineDeterministically(
timeline: RuntimeTimelineLike,
timeSeconds: number,
canonicalFps: number,
options?: RuntimeSeekOptions,
): number {
- const quantized = quantizeSeekTime(timeSeconds, canonicalFps, options?.subFrameDivisions);
+ const quantized = resolveRenderSeekTime(timeSeconds, canonicalFps, options);
const suppressEvents = options?.suppressEvents === true;
safeVoid(timeline, "pause");
if (typeof timeline.totalTime === "function") {
@@ -248,11 +259,7 @@ export function createRuntimePlayer(deps: PlayerDeps): RuntimePlayer {
activateSiblingTimelines(deps.getTimelineRegistry?.(), timeline);
return seekTimelineDeterministically(timeline, timeSeconds, canonicalFps, options);
})()
- : quantizeSeekTime(
- Math.max(0, Number(timeSeconds) || 0),
- canonicalFps,
- options?.subFrameDivisions,
- );
+ : resolveRenderSeekTime(Math.max(0, Number(timeSeconds) || 0), canonicalFps, options);
deps.onDeterministicSeek(quantized, options);
deps.setIsPlaying(false);
deps.onSyncMedia(quantized, false);
diff --git a/packages/core/src/runtime/types.ts b/packages/core/src/runtime/types.ts
index eecdda6ce4..1c38578372 100644
--- a/packages/core/src/runtime/types.ts
+++ b/packages/core/src/runtime/types.ts
@@ -286,6 +286,7 @@ export type RuntimeSeekOptions = {
* engine's sub-frame tick count so a fractional sample time survives quantization.
*/
subFrameDivisions?: number;
+ exact?: boolean;
};
export type RuntimeTimelineChildLike = {
diff --git a/packages/engine/src/services/frameCapture-motionBlur.test.ts b/packages/engine/src/services/frameCapture-motionBlur.test.ts
index 15c7db60bd..320d6c3204 100644
--- a/packages/engine/src/services/frameCapture-motionBlur.test.ts
+++ b/packages/engine/src/services/frameCapture-motionBlur.test.ts
@@ -28,13 +28,14 @@ interface RecordedSeek {
time: number;
suppressEvents?: boolean;
subFrameDivisions?: number;
+ exact?: boolean;
}
function installPageGlobals(seeks: RecordedSeek[]): void {
const root = globalThis as Record<string, unknown>;
root.window = {
__hf: {
- seek: (time: number, options?: { suppressEvents?: boolean; subFrameDivisions?: number }) => {
+ seek: (time: number, options?: Omit<RecordedSeek, "time">) => {
seeks.push({ time, ...options });
},
},
@@ -175,6 +176,23 @@ describe("sub-frame accumulation reaches the page with distinct sample times", (
});
});
+describe("frame export keeps its frame grid (issue #4430)", () => {
+ // `exact` is the snapshot-only opt-out of the runtime's seek quantization. Export must
+ // never send it, or frames would land between grid points instead of on them.
+ it("never asks for an exact seek with motion blur off", async () => {
+ await captureFrameToBuffer(makeSession({ motionBlur: undefined }), 10, 10 / 30);
+
+ expect(seeks).toEqual([{ time: 10 / 30 }]);
+ });
+
+ it("never asks for an exact seek on any motion-blur sample", async () => {
+ await captureFrameToBuffer(makeSession(), 10, 10 / 30);
+
+ expect(seeks.length).toBeGreaterThan(1);
+ expect(seeks.every((s) => !("exact" in s))).toBe(true);
+ });
+});
+
describe("accumulation composes with static-frame dedup", () => {
// 720 degrees is the widest shutter After Effects offers, and the AD5 reference export
// uses it, so it is the case a reader is most likely to check the frame ranges against.
diff --git a/packages/parsers/src/types.ts b/packages/parsers/src/types.ts
index d6588ae977..9f964a7ff6 100644
--- a/packages/parsers/src/types.ts
+++ b/packages/parsers/src/types.ts
@@ -439,7 +439,7 @@ export interface PlayerAPI {
disableRenderMode(): void;
renderSeek(
time: number,
- options?: { suppressEvents?: boolean; subFrameDivisions?: number },
+ options?: { suppressEvents?: boolean; subFrameDivisions?: number; exact?: boolean },
): void;
getElementVisibility(elementId: string): { visible: boolean; opacity?: number };
getVisibleElements(): Array<{ id: string; tagName: string; start: number; end: number }>;