mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 11:26:02 +00:00
fix(producer): long, mostly still films reach their first frame before the stall check stops them (#7521)
* perf(engine): check still frames once per page and share the result with later sessions * perf(producer): the probe skips the still-frame check unless its session captures * chore(engine): keep the comment share of the deferred still-frame check files at their base * fix(producer): the probe session's deferred still-frame check counts as stall-watcher activity * docs(engine): the still-frame spot-check range is the task's span, not only its own frames * fix(engine): a reused fast-capture probe session keeps still-frame reuse
This commit is contained in:
@@ -52,6 +52,7 @@ export type {
|
||||
CaptureWarning,
|
||||
CaptureWarningCode,
|
||||
SubTimelineWaitMemo,
|
||||
StaticDedupMemo,
|
||||
SubTimelineWaitOutcome,
|
||||
} from "./types.js";
|
||||
|
||||
|
||||
@@ -0,0 +1,136 @@
|
||||
import { mkdtempSync, rmSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
armDeferredStaticDedup,
|
||||
armStaticDedup,
|
||||
prepareCaptureSessionForReuse,
|
||||
verifyStaticFramesSafe,
|
||||
type CaptureSession,
|
||||
} from "./frameCapture.js";
|
||||
import { pageScreenshotCapture } from "./screenshotService.js";
|
||||
|
||||
vi.mock("./screenshotService.js", async (importOriginal) => {
|
||||
const actual = await importOriginal<typeof import("./screenshotService.js")>();
|
||||
return { ...actual, pageScreenshotCapture: vi.fn(async () => Buffer.from("still")) };
|
||||
});
|
||||
|
||||
const dirs: string[] = [];
|
||||
afterEach(() => {
|
||||
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
/** A session that deferred a check predicting frames 5 and 6 still; unverified arming makes the check visible. */
|
||||
function deferredSession(deferred: boolean): CaptureSession {
|
||||
const stats = { eligible: true, staticFrameSet: new Set([5, 6]), totalFrames: 10 };
|
||||
return {
|
||||
captureMode: "screenshot",
|
||||
options: { fps: { num: 30, den: 1 } },
|
||||
page: {},
|
||||
...(deferred ? { staticDedupDeferred: stats } : {}),
|
||||
} as unknown as CaptureSession;
|
||||
}
|
||||
|
||||
describe("still-frame check activity", () => {
|
||||
it("reports every check screenshot to onStaticDedupActivity", async () => {
|
||||
const onStaticDedupActivity = vi.fn();
|
||||
const page = { evaluate: vi.fn(async () => {}) };
|
||||
const session = { options: { onStaticDedupActivity } } as unknown as CaptureSession;
|
||||
const frames = new Set(Array.from({ length: 100 }, (_, index) => index + 1));
|
||||
const result = await verifyStaticFramesSafe(
|
||||
session,
|
||||
page as unknown as Parameters<typeof verifyStaticFramesSafe>[1],
|
||||
frames,
|
||||
30,
|
||||
1,
|
||||
);
|
||||
expect(result.stats.screenshots).toBeGreaterThan(0);
|
||||
expect(onStaticDedupActivity).toHaveBeenCalledTimes(result.stats.screenshots);
|
||||
expect(vi.mocked(pageScreenshotCapture)).toHaveBeenCalledTimes(result.stats.screenshots);
|
||||
});
|
||||
});
|
||||
|
||||
/** A page whose timeline walk sees one tween in [0 s, 1 s) of a 4 s film; `inject()` adds the drawElement canvas. */
|
||||
function fastCapturePage() {
|
||||
let injected = false;
|
||||
const page = {
|
||||
evaluate: vi.fn(async (fn: unknown) => {
|
||||
const source = String(fn);
|
||||
if (source.includes("getChildren")) {
|
||||
return {
|
||||
intervals: [{ start: 0, end: 1, spatial: true }],
|
||||
tweenCount: 1,
|
||||
duration: 4,
|
||||
hasVideo: false,
|
||||
hasCanvas: injected,
|
||||
hasFrameSources: false,
|
||||
hasIframe: false,
|
||||
hasNonGsapAnim: false,
|
||||
hasUnresolvableClipStart: false,
|
||||
hasTimelineCall: false,
|
||||
};
|
||||
}
|
||||
if (source.includes("__hf_page_composite_prepare")) return false;
|
||||
return [];
|
||||
}),
|
||||
};
|
||||
return { page, inject: () => (injected = true) };
|
||||
}
|
||||
|
||||
describe("a probe session on the fast capture path", () => {
|
||||
it("keeps still-frame dedup when it is reused to capture after its canvas went in", async () => {
|
||||
const dir = mkdtempSync(join(tmpdir(), "hf-dedup-defer-"));
|
||||
dirs.push(dir);
|
||||
const { page, inject } = fastCapturePage();
|
||||
const session = {
|
||||
captureMode: "screenshot",
|
||||
options: { fps: { num: 30, den: 1 }, deferStaticDedup: true },
|
||||
config: {},
|
||||
page,
|
||||
deRiskFrames: new Set([90]),
|
||||
} as unknown as CaptureSession;
|
||||
vi.stubEnv("HF_STATIC_DEDUP_VERIFY", "false");
|
||||
let predicted = new Set<number>();
|
||||
try {
|
||||
await armStaticDedup(session, session.page, () => {});
|
||||
expect(session.staticFrames).toBeUndefined();
|
||||
predicted = new Set(session.staticDedupDeferred?.staticFrameSet ?? []);
|
||||
inject();
|
||||
session.captureMode = "drawelement";
|
||||
await prepareCaptureSessionForReuse(session, join(dir, "frames"), null);
|
||||
} finally {
|
||||
vi.unstubAllEnvs();
|
||||
}
|
||||
expect(session.staticDedupSkipReason).toBeUndefined();
|
||||
expect(predicted.has(90)).toBe(true);
|
||||
predicted.delete(90);
|
||||
expect(session.staticFrames).toEqual(predicted);
|
||||
expect(predicted.size).toBe(87);
|
||||
});
|
||||
});
|
||||
|
||||
describe("a deferred still-frame check", () => {
|
||||
beforeEach(() => vi.stubEnv("HF_STATIC_DEDUP_VERIFY", "false"));
|
||||
afterEach(() => vi.unstubAllEnvs());
|
||||
|
||||
it("runs only on a session that deferred it", async () => {
|
||||
const other = deferredSession(false);
|
||||
await armDeferredStaticDedup(other);
|
||||
expect(other.staticFrames).toBeUndefined();
|
||||
|
||||
const deferred = deferredSession(true);
|
||||
await armDeferredStaticDedup(deferred);
|
||||
expect(deferred.staticDedupDeferred).toBeUndefined();
|
||||
expect(deferred.staticFrames?.size).toBe(2);
|
||||
});
|
||||
|
||||
it("runs when the session is reused to capture", async () => {
|
||||
const dir = mkdtempSync(join(tmpdir(), "hf-dedup-defer-"));
|
||||
dirs.push(dir);
|
||||
const deferred = deferredSession(true);
|
||||
await prepareCaptureSessionForReuse(deferred, join(dir, "frames"), null);
|
||||
expect(deferred.staticDedupDeferred).toBeUndefined();
|
||||
expect(deferred.staticFrames?.size).toBe(2);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,241 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
armFromSharedStaticDedup,
|
||||
claimStaticDedupCheck,
|
||||
pickStaticSpotCheck,
|
||||
shareableStaticFrames,
|
||||
staticDedupMemoKey,
|
||||
type CaptureSession,
|
||||
type StaticVerificationResult,
|
||||
} from "./frameCapture.js";
|
||||
import type { CaptureOptions, StaticDedupMemo } from "../types.js";
|
||||
import { pageScreenshotCapture } from "./screenshotService.js";
|
||||
|
||||
vi.mock("./screenshotService.js", async (importOriginal) => {
|
||||
const actual = await importOriginal<typeof import("./screenshotService.js")>();
|
||||
return { ...actual, pageScreenshotCapture: vi.fn() };
|
||||
});
|
||||
|
||||
const fps = 30;
|
||||
|
||||
function framesOf(runs: Array<[number, number]>): number[] {
|
||||
return runs.flatMap(([a, b]) => Array.from({ length: b - a + 1 }, (_, index) => a + index));
|
||||
}
|
||||
|
||||
// Twenty still runs of 60 frames, one every 100 frames, across a 2,000-frame film.
|
||||
const STILL_RUNS: Array<[number, number]> = Array.from({ length: 20 }, (_, k) => [
|
||||
k * 100 + 10,
|
||||
k * 100 + 69,
|
||||
]);
|
||||
const STILL = framesOf(STILL_RUNS);
|
||||
|
||||
function sessionWith(memo: StaticDedupMemo, options: Partial<CaptureOptions> = {}): CaptureSession {
|
||||
return {
|
||||
captureMode: "screenshot",
|
||||
options: {
|
||||
width: 1920,
|
||||
height: 1080,
|
||||
fps: { num: 30, den: 1 },
|
||||
format: "png",
|
||||
transparent: true,
|
||||
staticDedupMemo: memo,
|
||||
compositionHash: "composition-a",
|
||||
...options,
|
||||
},
|
||||
} as unknown as CaptureSession;
|
||||
}
|
||||
|
||||
/** A fake verification page: seeks set the current frame, screenshots return `contentAt` of it. */
|
||||
function fakePage(contentAt: (frame: number) => string) {
|
||||
const seen: number[] = [];
|
||||
let frame = 0;
|
||||
const page = {
|
||||
evaluate: vi.fn(async (_fn: unknown, t: number) => {
|
||||
frame = Math.round(t * fps);
|
||||
}),
|
||||
close: vi.fn(async () => {}),
|
||||
};
|
||||
vi.mocked(pageScreenshotCapture).mockImplementation(async () => {
|
||||
seen.push(frame);
|
||||
return Buffer.from(contentAt(frame));
|
||||
});
|
||||
const openVerificationPage = vi.fn(async () => page as never);
|
||||
return { seen, openVerificationPage };
|
||||
}
|
||||
|
||||
function verdictOf(
|
||||
outcome: StaticVerificationResult["outcome"],
|
||||
frames: number[],
|
||||
): StaticVerificationResult {
|
||||
return {
|
||||
outcome,
|
||||
verifiedFrames: new Set(frames),
|
||||
stats: {} as StaticVerificationResult["stats"],
|
||||
};
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
vi.mocked(pageScreenshotCapture).mockReset();
|
||||
});
|
||||
|
||||
describe("staticDedupMemoKey", () => {
|
||||
it("matches only when every pixel-deciding input matches", () => {
|
||||
const memo: StaticDedupMemo = {};
|
||||
const base = staticDedupMemoKey(sessionWith(memo));
|
||||
expect(base).toBeDefined();
|
||||
expect(
|
||||
staticDedupMemoKey(sessionWith(memo, { staticDedupFrameRange: { start: 0, end: 9 } })),
|
||||
).toBe(base);
|
||||
for (const change of [
|
||||
{ compositionHash: "composition-b" },
|
||||
{ width: 1280 },
|
||||
{ deviceScaleFactor: 2 },
|
||||
{ transparent: false },
|
||||
{ format: "jpeg" as const },
|
||||
{ variables: { title: "other" } },
|
||||
{ hiddenElementIds: ["logo"] },
|
||||
]) {
|
||||
expect(staticDedupMemoKey(sessionWith(memo, change))).not.toBe(base);
|
||||
}
|
||||
const beginframe = { ...sessionWith(memo), captureMode: "beginframe" } as CaptureSession;
|
||||
expect(staticDedupMemoKey(beginframe)).not.toBe(base);
|
||||
});
|
||||
|
||||
it("is absent without a memo or a composition hash, so the session verifies for itself", () => {
|
||||
expect(staticDedupMemoKey(sessionWith(undefined as never))).toBeUndefined();
|
||||
expect(staticDedupMemoKey(sessionWith({}, { compositionHash: undefined }))).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("shareableStaticFrames", () => {
|
||||
it("shares the frames of a verdict that verified runs, including one stopped by its budget", () => {
|
||||
expect(shareableStaticFrames(verdictOf("time_budget", [10, 11, 12]))).toEqual([10, 11, 12]);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["no verdict at all", null],
|
||||
["a budget stop with no run verified", verdictOf("time_budget", [])],
|
||||
["a mismatch", verdictOf("mismatch", [])],
|
||||
["an infrastructure failure", verdictOf("infrastructure", [])],
|
||||
["an unprofitable plan", verdictOf("unprofitable", [])],
|
||||
])("shares dedup off after %s", (_label, verdict) => {
|
||||
expect(shareableStaticFrames(verdict)).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("claimStaticDedupCheck", () => {
|
||||
it("lets the first session for a key verify and the later ones wait for its result", async () => {
|
||||
const memo: StaticDedupMemo = {};
|
||||
const first = claimStaticDedupCheck(sessionWith(memo));
|
||||
const second = claimStaticDedupCheck(
|
||||
sessionWith(memo, { staticDedupFrameRange: { start: 0, end: 9 } }),
|
||||
);
|
||||
expect(first?.kind).toBe("verify");
|
||||
expect(second?.kind).toBe("reuse");
|
||||
if (first?.kind !== "verify" || second?.kind !== "reuse") throw new Error("unexpected claims");
|
||||
first.settle([10, 11]);
|
||||
await expect(second.check).resolves.toEqual([10, 11]);
|
||||
});
|
||||
|
||||
it("passes a failed check on as off, so a waiting session takes no screenshot", async () => {
|
||||
const memo: StaticDedupMemo = {};
|
||||
const first = claimStaticDedupCheck(sessionWith(memo));
|
||||
const second = claimStaticDedupCheck(sessionWith(memo));
|
||||
if (first?.kind !== "verify" || second?.kind !== "reuse") throw new Error("unexpected claims");
|
||||
first.settle(shareableStaticFrames(verdictOf("time_budget", [])));
|
||||
const { seen, openVerificationPage } = fakePage(() => "still");
|
||||
const session = sessionWith(memo);
|
||||
await armFromSharedStaticDedup(session, await second.check, new Set(STILL), fps, vi.fn(), {
|
||||
openVerificationPage,
|
||||
});
|
||||
expect(session.staticDedupSkipReason).toBe("verification_failed");
|
||||
expect(openVerificationPage).not.toHaveBeenCalled();
|
||||
expect(seen).toEqual([]);
|
||||
});
|
||||
|
||||
it("gives a session with a different page its own check", () => {
|
||||
const memo: StaticDedupMemo = {};
|
||||
claimStaticDedupCheck(sessionWith(memo));
|
||||
expect(
|
||||
claimStaticDedupCheck(sessionWith(memo, { compositionHash: "composition-b" }))?.kind,
|
||||
).toBe("verify");
|
||||
});
|
||||
|
||||
it("claims nothing without a memo or a composition hash", () => {
|
||||
expect(claimStaticDedupCheck(sessionWith(undefined as never))).toBeUndefined();
|
||||
expect(claimStaticDedupCheck(sessionWith({}, { compositionHash: undefined }))).toBeUndefined();
|
||||
});
|
||||
});
|
||||
|
||||
describe("pickStaticSpotCheck", () => {
|
||||
it("picks at most 4 runs of at most 48 frames, all inside the session's frames", () => {
|
||||
const picked = [...pickStaticSpotCheck(new Set(STILL), { start: 500, end: 1500 })];
|
||||
expect(picked.every((frame) => frame >= 500 && frame < 1500)).toBe(true);
|
||||
const runStarts = picked.filter((frame) => !picked.includes(frame - 1));
|
||||
expect(runStarts).toEqual([510, 810, 1110, 1410]);
|
||||
expect(picked.length).toBe(4 * 48);
|
||||
});
|
||||
|
||||
it("skips runs that start at frame 0 or are too short to verify", () => {
|
||||
const picked = pickStaticSpotCheck(new Set([0, 1, 2, 3, 20, 21, 40, 41, 42]), undefined);
|
||||
expect([...picked]).toEqual([40, 41, 42]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("armFromSharedStaticDedup", () => {
|
||||
const worker = (memo: StaticDedupMemo, options: Partial<CaptureOptions> = {}) =>
|
||||
sessionWith(memo, { staticDedupFrameRange: { start: 500, end: 1500 }, ...options });
|
||||
|
||||
it("reuses the shared set after a spot check of 12 screenshots inside the worker's frames", async () => {
|
||||
const { seen, openVerificationPage } = fakePage(() => "still");
|
||||
const session = worker({});
|
||||
const log = vi.fn();
|
||||
await armFromSharedStaticDedup(session, STILL, new Set(STILL), fps, log, {
|
||||
openVerificationPage,
|
||||
});
|
||||
expect(session.staticFrames).toEqual(new Set(STILL));
|
||||
expect(seen.length).toBe(12);
|
||||
expect(seen.every((frame) => frame >= 500 && frame < 1500)).toBe(true);
|
||||
expect(log).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("keeps only the shared frames this worker also predicts still", async () => {
|
||||
const { openVerificationPage } = fakePage(() => "still");
|
||||
const session = worker({});
|
||||
const predicted = new Set(framesOf(STILL_RUNS.slice(0, 10)));
|
||||
await armFromSharedStaticDedup(session, STILL, predicted, fps, vi.fn(), {
|
||||
openVerificationPage,
|
||||
});
|
||||
expect(session.staticFrames).toEqual(predicted);
|
||||
});
|
||||
|
||||
it("takes no screenshot when the render already found verification gives nothing", async () => {
|
||||
const { seen, openVerificationPage } = fakePage(() => "still");
|
||||
const session = worker({});
|
||||
const log = vi.fn();
|
||||
await armFromSharedStaticDedup(session, null, new Set(STILL), fps, log, {
|
||||
openVerificationPage,
|
||||
});
|
||||
expect(session.staticFrames).toBeUndefined();
|
||||
expect(session.staticDedupSkipReason).toBe("verification_failed");
|
||||
expect(openVerificationPage).not.toHaveBeenCalled();
|
||||
expect(seen).toEqual([]);
|
||||
expect(log).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("turns dedup off for the worker when the shared set is wrong for its page", async () => {
|
||||
// The shared set says these frames are still, but on this page everything from 800 on moves.
|
||||
const { openVerificationPage } = fakePage((frame) =>
|
||||
frame < 800 ? "still" : `frame ${frame}`,
|
||||
);
|
||||
const session = worker({});
|
||||
const log = vi.fn();
|
||||
await armFromSharedStaticDedup(session, STILL, new Set(STILL), fps, log, {
|
||||
openVerificationPage,
|
||||
});
|
||||
expect(session.staticFrames).toBeUndefined();
|
||||
expect(session.staticDedupSkipReason).toBe("verification_failed");
|
||||
expect(log).toHaveBeenCalledTimes(1);
|
||||
expect(log.mock.calls[0]![0]).toContain("spot check of the shared set: mismatch");
|
||||
});
|
||||
});
|
||||
@@ -120,6 +120,7 @@ import type {
|
||||
SubTimelineWaitMemo,
|
||||
SubTimelineWaitOutcome,
|
||||
} from "../types.js";
|
||||
import { PROVENANCE_VERSION } from "../utils/renderProvenance.js";
|
||||
import { cloneCaptureWarnings } from "./captureWarning.js";
|
||||
import { installMediaRenderIdBridge } from "./mediaRenderIdBridge.js";
|
||||
import {
|
||||
@@ -213,6 +214,8 @@ export interface CaptureSession {
|
||||
* Undefined when armed or disabled.
|
||||
*/
|
||||
staticDedupSkipReason?: string;
|
||||
/** The init-time page analysis of a check deferred by `deferStaticDedup`; `armDeferredStaticDedup` runs it. */
|
||||
staticDedupDeferred?: StaticFrameStats;
|
||||
// Tracks whether the page/browser handles have already been released by
|
||||
// closeCaptureSession. Used to make closeCaptureSession idempotent under
|
||||
// browser-pool semantics (see the function body for the full invariant).
|
||||
@@ -1311,9 +1314,6 @@ async function initDrawElementOrTransparentBackground(
|
||||
// passed) and the DOM is still normal (canvas not yet injected, so the
|
||||
// verification screenshots are valid). drawElement-path only; see armStaticDedup.
|
||||
await armStaticDedup(session, page, logInitPhase);
|
||||
// A static frame reuses the previous drawElement capture; a risk frame is captured by
|
||||
// another session, so its neighbours must not reuse across it.
|
||||
for (const f of session.deRiskFrames ?? []) session.staticFrames?.delete(f);
|
||||
// Video comps on injector-less sessions (probe sessions initialize before
|
||||
// video extraction) DEFER the rest of the drawElement init: ground-truth
|
||||
// screenshots would capture black <video> boxes, and once the canvas is
|
||||
@@ -3701,6 +3701,8 @@ export function isStaticDedupFrameAnalysisSafe(totalFrames: number): boolean {
|
||||
* comp on any signal the tween-walker can't see: video / canvas / webgl (redraw without
|
||||
* a tween), zero tweens (non-GSAP animation), or a running CSS/WAAPI animation.
|
||||
*/
|
||||
type StaticFrameStats = Awaited<ReturnType<typeof computeStaticFrameSet>>;
|
||||
|
||||
export async function computeStaticFrameSet(
|
||||
page: Page,
|
||||
fps: number,
|
||||
@@ -4240,6 +4242,7 @@ export async function verifyStaticFramesSafe(
|
||||
await seekToFrame(frameIdx);
|
||||
stats.screenshots++;
|
||||
const buf = await capture(page, session.options);
|
||||
session.options.onStaticDedupActivity?.();
|
||||
if (stats.screenshots === 1) firstShotMs = now() - shotStart;
|
||||
return buf;
|
||||
};
|
||||
@@ -4280,6 +4283,138 @@ export async function verifyStaticFramesSafe(
|
||||
}
|
||||
}
|
||||
|
||||
// A session reusing an earlier session's verified set re-verifies this many short runs of its own frames.
|
||||
const STATIC_SPOT_CHECK_RUNS = 4;
|
||||
const STATIC_SPOT_CHECK_FRAMES = 2 * STATIC_VERIFY_REFERENCE_STRIDE;
|
||||
|
||||
/** Sessions share a dedup verdict only when every input that decides their pixels is equal. */
|
||||
export function staticDedupMemoKey(session: CaptureSession): string | undefined {
|
||||
const options = session.options;
|
||||
if (!options.staticDedupMemo || !options.compositionHash) return undefined;
|
||||
return JSON.stringify([
|
||||
options.compositionHash,
|
||||
options.width,
|
||||
options.height,
|
||||
options.deviceScaleFactor ?? 1,
|
||||
session.captureMode,
|
||||
options.format ?? null,
|
||||
options.quality ?? null,
|
||||
options.transparent === true,
|
||||
options.fps,
|
||||
[...(options.hiddenElementIds ?? [])].sort(),
|
||||
options.variables ?? null,
|
||||
options.motionBlur ?? null,
|
||||
options.pageMotionBlur ?? null,
|
||||
PROVENANCE_VERSION,
|
||||
]);
|
||||
}
|
||||
|
||||
/** Up to STATIC_SPOT_CHECK_RUNS short runs of `frames` inside `range`: the first, the last and evenly between. */
|
||||
export function pickStaticSpotCheck(
|
||||
frames: ReadonlySet<number>,
|
||||
range?: { start: number; end: number },
|
||||
): Set<number> {
|
||||
const inRange = [...frames]
|
||||
.filter((frame) => !range || (frame >= range.start && frame < range.end))
|
||||
.sort((left, right) => left - right);
|
||||
const runs = contiguousStaticRuns(inRange).filter((run) => run.a >= 1 && run.b - run.a >= 2);
|
||||
const count = Math.min(STATIC_SPOT_CHECK_RUNS, runs.length);
|
||||
const picked = new Set<number>();
|
||||
for (let index = 0; index < count; index++) {
|
||||
const run = runs[count === 1 ? 0 : Math.round((index * (runs.length - 1)) / (count - 1))]!;
|
||||
const end = Math.min(run.b, run.a + STATIC_SPOT_CHECK_FRAMES - 1);
|
||||
for (let frame = run.a; frame <= end; frame++) picked.add(frame);
|
||||
}
|
||||
return picked;
|
||||
}
|
||||
|
||||
export interface SharedStaticDedupDependencies {
|
||||
openVerificationPage?: (session: CaptureSession) => Promise<Page>;
|
||||
}
|
||||
|
||||
export type StaticDedupClaim =
|
||||
| { kind: "verify"; settle: (frames: readonly number[] | null) => void }
|
||||
| { kind: "reuse"; check: Promise<readonly number[] | null> };
|
||||
|
||||
/** The first session for a key verifies and must settle; later sessions with that key reuse its check. */
|
||||
export function claimStaticDedupCheck(session: CaptureSession): StaticDedupClaim | undefined {
|
||||
const key = staticDedupMemoKey(session);
|
||||
const memo = session.options.staticDedupMemo;
|
||||
if (!key || !memo) return undefined;
|
||||
const checks = (memo.checks ??= new Map());
|
||||
const pending = checks.get(key);
|
||||
if (pending) return { kind: "reuse", check: pending };
|
||||
let settle!: (frames: readonly number[] | null) => void;
|
||||
checks.set(key, new Promise((resolve) => (settle = resolve)));
|
||||
return { kind: "verify", settle };
|
||||
}
|
||||
|
||||
/** What a verification gives later sessions: its fully verified frames, or null when it has none. */
|
||||
export function shareableStaticFrames(
|
||||
verdict: StaticVerificationResult | null,
|
||||
): readonly number[] | null {
|
||||
const usable =
|
||||
verdict !== null &&
|
||||
verdict.outcome !== "mismatch" &&
|
||||
verdict.outcome !== "infrastructure" &&
|
||||
verdict.outcome !== "unprofitable" &&
|
||||
verdict.verifiedFrames.size > 0;
|
||||
return usable ? [...verdict.verifiedFrames] : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* Arms dedup from an earlier session's check of the same page. The shared frames are narrowed to this
|
||||
* session's own prediction and spot-checked; any failure turns dedup off for this session only.
|
||||
*/
|
||||
export async function armFromSharedStaticDedup(
|
||||
session: CaptureSession,
|
||||
sharedFrames: readonly number[] | null,
|
||||
predicted: ReadonlySet<number>,
|
||||
fps: number,
|
||||
logInitPhase: (phase: string) => void,
|
||||
dependencies: SharedStaticDedupDependencies = {},
|
||||
): Promise<void> {
|
||||
if (!sharedFrames) {
|
||||
session.staticDedupSkipReason = "verification_failed";
|
||||
logInitPhase(
|
||||
"static-frame dedup: disabled (an earlier session of this render could not verify it)",
|
||||
);
|
||||
return;
|
||||
}
|
||||
const frames = new Set(sharedFrames.filter((frame) => predicted.has(frame)));
|
||||
const spot = pickStaticSpotCheck(frames, session.options.staticDedupFrameRange);
|
||||
if (spot.size === 0) {
|
||||
session.staticDedupSkipReason = "ineligible";
|
||||
logInitPhase("static-frame dedup: disabled (no shared static run in this session's frames)");
|
||||
return;
|
||||
}
|
||||
const openPage = dependencies.openVerificationPage ?? createStaticVerificationPage;
|
||||
let page: Page | undefined;
|
||||
let verdict: StaticVerificationResult | undefined;
|
||||
try {
|
||||
page = await openPage(session);
|
||||
verdict = await verifyStaticFramesSafe(session, page, spot, fps, 1);
|
||||
} catch {
|
||||
verdict = undefined;
|
||||
} finally {
|
||||
await page?.close().catch(() => {});
|
||||
}
|
||||
if (verdict?.outcome !== "verified" || verdict.verifiedFrames.size !== spot.size) {
|
||||
session.staticDedupSkipReason = "verification_failed";
|
||||
const at = verdict?.badFrame === undefined ? "" : ` at frame ${verdict.badFrame}`;
|
||||
logInitPhase(
|
||||
`static-frame dedup: disabled (spot check of the shared set: ${verdict?.outcome ?? "infrastructure"}${at})`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
session.staticDedupVerification = verdict;
|
||||
session.staticFrames = frames;
|
||||
logInitPhase(
|
||||
`static-frame dedup: ${frames.size}/${predicted.size} predicted frame(s) reusable (shared check, ` +
|
||||
`spot check ${spot.size} frame(s), screenshots=${verdict.stats.screenshots}, elapsedMs=${verdict.stats.elapsedMs})`,
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Arm static-frame dedup for this render (default-on; opt out with HF_STATIC_DEDUP=false).
|
||||
* Runs at init in normal DOM state so the verification screenshots are valid. Predicts
|
||||
@@ -4287,7 +4422,7 @@ export async function verifyStaticFramesSafe(
|
||||
* and on success stores it on the session for captureFrameCore to reuse. Sample budget
|
||||
* via HF_STATIC_DEDUP_SAMPLES (default 24).
|
||||
*/
|
||||
async function armStaticDedup(
|
||||
export async function armStaticDedup(
|
||||
session: CaptureSession,
|
||||
page: Page,
|
||||
logInitPhase: (phase: string) => void,
|
||||
@@ -4313,13 +4448,46 @@ async function armStaticDedup(
|
||||
);
|
||||
session.motionBlurNonSpatialFrames = sharedStaticFrameStats.nonSpatialOnlyFrameSet;
|
||||
}
|
||||
await armStaticDedupFrames(session, page, logInitPhase, sharedStaticFrameStats);
|
||||
}
|
||||
|
||||
/** Runs the still-frame check a session deferred at init; a no-op for any other session. */
|
||||
export async function armDeferredStaticDedup(session: CaptureSession): Promise<void> {
|
||||
const stats = session.staticDedupDeferred;
|
||||
if (!stats) return;
|
||||
session.staticDedupDeferred = undefined;
|
||||
const startedAt = Date.now();
|
||||
const logInitPhase = (phase: string) =>
|
||||
console.error(
|
||||
`[initSession:${session.captureMode}] ${phase} (deferred, ${Date.now() - startedAt}ms)`,
|
||||
);
|
||||
if (videoInjectionBlocksStaticDedup(session, logInitPhase)) return;
|
||||
await checkStaticFrames(session, stats, logInitPhase);
|
||||
}
|
||||
|
||||
function videoInjectionBlocksStaticDedup(
|
||||
session: CaptureSession,
|
||||
logInitPhase: (phase: string) => void,
|
||||
): boolean {
|
||||
if (!session.onBeforeCapture) return false;
|
||||
session.staticDedupSkipReason = "video_injection";
|
||||
logInitPhase("static-frame dedup: disabled (before-capture hook / video injection active)");
|
||||
return true;
|
||||
}
|
||||
|
||||
async function armStaticDedupFrames(
|
||||
session: CaptureSession,
|
||||
page: Page,
|
||||
logInitPhase: (phase: string) => void,
|
||||
sharedStaticFrameStats?: StaticFrameStats,
|
||||
): Promise<void> {
|
||||
// Idempotent: the drawElement init path arms dedup BEFORE canvas injection
|
||||
// (verification screenshots need the un-injected DOM), and initializeSession
|
||||
// calls this again unconditionally afterwards. Once staticFrames is
|
||||
// populated, re-running would overwrite the armed state with
|
||||
// skipReason="capture_mode" (captureMode is "drawelement" by then) —
|
||||
// contradictory telemetry — and re-run the verification seeks. No-op instead.
|
||||
if (session.staticFrames || session.staticDedupSkipReason) return;
|
||||
if (session.staticFrames || session.staticDedupSkipReason || session.staticDedupDeferred) return;
|
||||
// Default ON for everyone; opt out via HF_STATIC_DEDUP in {false,0,off} (resolved into
|
||||
// EngineConfig.staticFrameDedup by resolveConfig). Verification is the safety net at scale.
|
||||
// Default-on: only an explicit `staticFrameDedup === false` (resolved from
|
||||
@@ -4344,11 +4512,7 @@ async function armStaticDedup(
|
||||
);
|
||||
return;
|
||||
}
|
||||
if (session.onBeforeCapture) {
|
||||
session.staticDedupSkipReason = "video_injection";
|
||||
logInitPhase("static-frame dedup: disabled (before-capture hook / video injection active)");
|
||||
return;
|
||||
}
|
||||
if (videoInjectionBlocksStaticDedup(session, logInitPhase)) return;
|
||||
const pageComposite = await page
|
||||
.evaluate(
|
||||
() =>
|
||||
@@ -4370,6 +4534,34 @@ async function armStaticDedup(
|
||||
logInitPhase(`static-frame dedup: disabled (${stats.reason})`);
|
||||
return;
|
||||
}
|
||||
// Deferred after the page is read, so a later drawElement canvas cannot change the analysis.
|
||||
if (session.options.deferStaticDedup) {
|
||||
session.staticDedupDeferred = stats;
|
||||
logInitPhase("static-frame dedup: deferred until this session captures");
|
||||
return;
|
||||
}
|
||||
await checkStaticFrames(session, stats, logInitPhase);
|
||||
}
|
||||
|
||||
/** Verifies (or shares) the predicted still frames and arms them, without the risk frames. */
|
||||
async function checkStaticFrames(
|
||||
session: CaptureSession,
|
||||
stats: StaticFrameStats,
|
||||
logInitPhase: (phase: string) => void,
|
||||
): Promise<void> {
|
||||
try {
|
||||
await verifyOrShareStaticFrames(session, stats, logInitPhase);
|
||||
} finally {
|
||||
for (const f of session.deRiskFrames ?? []) session.staticFrames?.delete(f);
|
||||
}
|
||||
}
|
||||
|
||||
async function verifyOrShareStaticFrames(
|
||||
session: CaptureSession,
|
||||
stats: StaticFrameStats,
|
||||
logInitPhase: (phase: string) => void,
|
||||
): Promise<void> {
|
||||
const fps = fpsToNumber(session.options.fps);
|
||||
const rawSamples = Number(process.env.HF_STATIC_DEDUP_SAMPLES ?? "24");
|
||||
const samples = Number.isFinite(rawSamples) && rawSamples >= 1 ? rawSamples : 24;
|
||||
session.staticDedupPredictedCount = stats.staticFrameSet.size;
|
||||
@@ -4381,6 +4573,36 @@ async function armStaticDedup(
|
||||
);
|
||||
return;
|
||||
}
|
||||
const claim = claimStaticDedupCheck(session);
|
||||
if (claim?.kind === "reuse") {
|
||||
await armFromSharedStaticDedup(
|
||||
session,
|
||||
await claim.check,
|
||||
stats.staticFrameSet,
|
||||
fps,
|
||||
logInitPhase,
|
||||
);
|
||||
return;
|
||||
}
|
||||
// Every exit settles the claim, so sessions waiting on this check never hang.
|
||||
let shared: StaticVerificationResult | null = null;
|
||||
try {
|
||||
await verifyAndArmStaticDedup(session, stats, fps, samples, logInitPhase, (verdict) => {
|
||||
shared = verdict;
|
||||
});
|
||||
} finally {
|
||||
claim?.settle(shareableStaticFrames(shared));
|
||||
}
|
||||
}
|
||||
|
||||
async function verifyAndArmStaticDedup(
|
||||
session: CaptureSession,
|
||||
stats: Awaited<ReturnType<typeof computeStaticFrameSet>>,
|
||||
fps: number,
|
||||
samples: number,
|
||||
logInitPhase: (phase: string) => void,
|
||||
onVerdict: (verdict: StaticVerificationResult) => void,
|
||||
): Promise<void> {
|
||||
let verificationPage: Page | undefined;
|
||||
let verdict: StaticVerificationResult;
|
||||
try {
|
||||
@@ -4400,6 +4622,7 @@ async function armStaticDedup(
|
||||
await verificationPage?.close().catch(() => {});
|
||||
}
|
||||
session.staticDedupVerification = verdict;
|
||||
onVerdict(verdict);
|
||||
if (verdict.outcome === "mismatch" || verdict.outcome === "infrastructure") {
|
||||
session.staticDedupSkipReason = "verification_failed";
|
||||
logInitPhase(
|
||||
@@ -5662,11 +5885,11 @@ export async function closeCaptureSession(session: CaptureSession): Promise<void
|
||||
session.isInitialized = false;
|
||||
}
|
||||
|
||||
export function prepareCaptureSessionForReuse(
|
||||
export async function prepareCaptureSessionForReuse(
|
||||
session: CaptureSession,
|
||||
outputDir: string,
|
||||
onBeforeCapture: BeforeCaptureHook | null,
|
||||
): void {
|
||||
): Promise<void> {
|
||||
if (!existsSync(outputDir)) {
|
||||
mkdirSync(outputDir, { recursive: true });
|
||||
}
|
||||
@@ -5689,6 +5912,7 @@ export function prepareCaptureSessionForReuse(
|
||||
session.lastFrameBuffer = undefined;
|
||||
session.lastFrameAbsoluteIndex = undefined;
|
||||
session.staticDedupCount = 0;
|
||||
await armDeferredStaticDedup(session);
|
||||
}
|
||||
|
||||
export async function getCompositionDuration(session: CaptureSession): Promise<number> {
|
||||
|
||||
@@ -933,7 +933,7 @@ async function executeWorkerTask(
|
||||
const launch = createCaptureSession(
|
||||
serverUrl,
|
||||
task.outputDir,
|
||||
captureOptions,
|
||||
{ ...captureOptions, staticDedupFrameRange: { start: task.startFrame, end: task.endFrame } },
|
||||
createBeforeCaptureHook(),
|
||||
workerConfig,
|
||||
);
|
||||
|
||||
@@ -38,6 +38,14 @@ export interface SubTimelineWaitMemo {
|
||||
loggedSceneCallbackErrors?: string[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Shared by every capture session of one render: per key, the first session's static-frame dedup check,
|
||||
* which later sessions with that key wait for. It resolves to the verified frames, or null for none.
|
||||
*/
|
||||
export interface StaticDedupMemo {
|
||||
checks?: Map<string, Promise<readonly number[] | null>>;
|
||||
}
|
||||
|
||||
export type CaptureWarningCode =
|
||||
| "media_readiness_timeout"
|
||||
| "media_load_failed"
|
||||
@@ -226,6 +234,14 @@ export interface CaptureOptions {
|
||||
skipReadinessVideoIds?: readonly string[];
|
||||
/** Pass one object to every session of a render; see `SubTimelineWaitMemo`. */
|
||||
subTimelineWaitMemo?: SubTimelineWaitMemo;
|
||||
/** Pass one object to every session of a render, with `compositionHash`; see `StaticDedupMemo`. */
|
||||
staticDedupMemo?: StaticDedupMemo;
|
||||
/** Hash of the composition HTML this session loads; part of the static dedup sharing key. */
|
||||
compositionHash?: string;
|
||||
/** The frames of this session's task, [start, end); an interleaved task captures only some of them. */
|
||||
staticDedupFrameRange?: { start: number; end: number };
|
||||
deferStaticDedup?: boolean;
|
||||
onStaticDedupActivity?: () => void;
|
||||
/**
|
||||
* Render-time variable overrides for the composition. The engine injects
|
||||
* these as `window.__hfVariables` via `evaluateOnNewDocument` before any
|
||||
|
||||
Reference in New Issue
Block a user