Skip to content

Commit c5224ac

Browse files
feat(cli): snapshot --against pairs each frame with a reference video (#3637)
Rebuilding footage means checking the render against the source at the same timestamps. `--against <video>` saves the reference frame at every captured time (frame-exact seek: -ss after -i) plus a labelled render|reference pair sheet built with the existing contact-sheet helper. Reference frames and pair sheets are derived artifacts, kept out of the snapshot list like contact-sheet.jpg. No new dependencies.
1 parent e0007b8 commit c5224ac

3 files changed

Lines changed: 67 additions & 5 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -722,6 +722,7 @@ Capture specific frames as PNGs, without waiting for a full render.
722722
npx hyperframes snapshot my-project --at 2.9,10.4,18.7
723723
npx hyperframes snapshot my-project --frames 10
724724
npx hyperframes snapshot my-project --zoom '#headline'
725+
npx hyperframes snapshot my-project --at 1.5,4.3 --against ref.mp4
725726
```
726727

727728
```
@@ -740,6 +741,7 @@ npx hyperframes snapshot my-project --zoom '#headline'
740741
| `--output, -o` | Where the PNGs go (default `<project>/snapshots`) |
741742
| `--end` / `--no-end` | Always add a readable end-of-timeline frame (default: on). `--no-end` captures only your `--at` times. |
742743
| `--zoom` | Crop to a CSS selector or an exact `x,y,w,h` region, using a raised device scale factor. Layout is untouched — never CSS zoom or a resized viewport. A selector that matches nothing is an error. |
744+
| `--against` | A reference video, such as footage you are rebuilding. For every captured time also saves its frame-exact frame (`ref-XX-…png`) and a labelled render / reference pair (`pair-XX-…jpg`). |
743745
| `--zoom-scale` | Pixel density for `--zoom` crops (default 3) |
744746
| `--angle` | Orthogonal 3D camera for depth and occlusion checks: `front`, `iso`, `top`, `side`, or `yaw,pitch` in degrees. Tilts the whole stage, so you get real pixels. |
745747
| `--describe` | Gemini vision analysis of each frame. Runs by default when `GEMINI_API_KEY` is set. Pass a question to override the prompt, or `--describe false` to opt out. |

‎packages/cli/src/commands/snapshot.test.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,17 @@ describe("transparent snapshot capture", () => {
7777
expect(source).toContain("opts.autoProxy");
7878
});
7979

80+
it("pairs every frame with the frame-exact reference frame under --against", () => {
81+
const source = readFileSync(new URL("./snapshot.ts", import.meta.url), "utf8");
82+
expect(source).toContain("against: {");
83+
expect(source).toContain("extractVideoFrameToBuffer(opts.against, time, false, true)");
84+
expect(source).toContain('labels: ["render", "reference"]');
85+
// accurate seek = `-ss` after `-i`, never the keyframe-snap fast path
86+
expect(source).toContain(
87+
'accurateSeek ? ["-i", videoPath, ...seek] : [...seek, "-i", videoPath]',
88+
);
89+
});
90+
8091
it("resolves and forwards the shared local browser GPU policy", () => {
8192
const source = readFileSync(new URL("./snapshot.ts", import.meta.url), "utf8");
8293
expect(source).toContain("resolveLocalBrowserGpuMode");

‎packages/cli/src/commands/snapshot.ts‎

Lines changed: 54 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -137,22 +137,23 @@ async function extractVideoFrameToBuffer(
137137
videoPath: string,
138138
timeSeconds: number,
139139
useVp9AlphaDecoder = false,
140+
accurateSeek = false,
140141
): Promise<Buffer | null> {
141142
const tmp = mkdtempSync(join(tmpdir(), "hf-snapshot-frame-"));
142143
const outPath = join(tmp, "frame.png");
143144
try {
144145
const ffmpegPath = requireSnapshotFfmpeg(findFFmpeg());
145146
// `-ss` before `-i` performs a fast keyframe seek; adequate for snapshot accuracy
146147
// (±1 frame) and orders of magnitude faster than the decode-and-scan alternative.
148+
// `accurateSeek` puts `-ss` after `-i` (decode from the start) for frame-exact
149+
// reference pairs, where ±1 frame would read as a real mismatch.
147150
const args = ["-hide_banner", "-loglevel", "error"];
148151
if (useVp9AlphaDecoder) {
149152
args.push("-c:v", "libvpx-vp9");
150153
}
154+
const seek = ["-ss", String(Math.max(0, timeSeconds))];
151155
args.push(
152-
"-ss",
153-
String(Math.max(0, timeSeconds)),
154-
"-i",
155-
videoPath,
156+
...(accurateSeek ? ["-i", videoPath, ...seek] : [...seek, "-i", videoPath]),
156157
"-frames:v",
157158
"1",
158159
"-q:v",
@@ -181,6 +182,10 @@ export const examples: Example[] = [
181182
"Zoom into an exact pixel region at 2x density",
182183
"snapshot --zoom 100,50,400,300 --zoom-scale 2",
183184
],
185+
[
186+
"Pair each frame with the reference footage at the same time",
187+
"snapshot --at 1.5,4.3,8.1 --against ref.mp4",
188+
],
184189
];
185190

186191
/** `--zoom-scale`: the deviceScaleFactor used for zoomed crops. Defaults to 3;
@@ -264,6 +269,8 @@ async function captureSnapshots(
264269
zoomScale?: number;
265270
autoProxy?: boolean;
266271
browserGpuMode?: BrowserGpuMode;
272+
/** Reference video: save its frame at each captured time plus a render|reference pair. */
273+
against?: string;
267274
},
268275
): Promise<string[]> {
269276
const { bundleWithLocalizedFonts } = await import("../utils/bundleWithLocalizedFonts.js");
@@ -559,7 +566,8 @@ async function captureSnapshots(
559566
}
560567

561568
const timeLabel = formatSnapshotTimestamp(time);
562-
const filename = `frame-${String(i).padStart(2, "0")}-at-${timeLabel}.png`;
569+
const index = String(i).padStart(2, "0");
570+
const filename = `frame-${index}-at-${timeLabel}.png`;
563571
const framePath = join(snapshotDir, filename);
564572

565573
if (opts.zoom) {
@@ -585,6 +593,31 @@ async function captureSnapshots(
585593
} else {
586594
await page.screenshot({ path: framePath, type: "png", omitBackground: true });
587595
}
596+
if (opts.against) {
597+
// Frame-exact reference frame beside the render, so a rebuild can be
598+
// checked against its footage without hand-rolled ffmpeg + montage.
599+
const refPng = await extractVideoFrameToBuffer(opts.against, time, false, true);
600+
if (!refPng) {
601+
console.error(
602+
` ${c.warn("⚠")} --against has no frame at ${timeLabel} — reference pair skipped`,
603+
);
604+
} else {
605+
const refPath = join(snapshotDir, `ref-${index}-at-${timeLabel}.png`);
606+
writeFileSync(refPath, refPng);
607+
const pairPath = join(snapshotDir, `pair-${index}-at-${timeLabel}.jpg`);
608+
const { createContactSheet } = await import("../capture/contactSheet.js");
609+
await createContactSheet([framePath, refPath], pairPath, {
610+
cols: 2,
611+
maxImages: 2,
612+
cellWidth: 960,
613+
labelMode: "custom",
614+
labels: ["render", "reference"],
615+
});
616+
}
617+
}
618+
// Only the capture itself is a "snapshot": the reference frame and the
619+
// pair sheet are derived artifacts, like contact-sheet.jpg, so they stay
620+
// out of savedPaths (count, listing, and --describe all read it).
588621
const rel = relative(projectDir, framePath);
589622
savedPaths.push(rel.startsWith("..") || isAbsolute(rel) ? framePath : rel);
590623
}
@@ -649,6 +682,11 @@ export default defineCommand({
649682
description: "Device-scale-factor density for --zoom crops (default: 3)",
650683
default: "3",
651684
},
685+
against: {
686+
type: "string",
687+
description:
688+
"Reference video (e.g. footage being rebuilt): also save its frame at each captured time and a render|reference pair sheet",
689+
},
652690
describe: {
653691
type: "string",
654692
description:
@@ -718,6 +756,11 @@ export default defineCommand({
718756
const camera = args.angle ? parseAngle(String(args.angle)) : undefined;
719757
const zoomTarget = args.zoom ? parseZoomTarget(String(args.zoom)) : undefined;
720758
const zoomScale = parseZoomScale(args["zoom-scale"]);
759+
const against = args.against ? resolve(String(args.against)) : undefined;
760+
if (against && !existsSync(against)) {
761+
console.log(`${c.error("✗")} --against video not found: ${against}`);
762+
failCommand();
763+
}
721764

722765
const label = atTimestamps
723766
? `${atTimestamps.length} frames at [${atTimestamps.map(formatSnapshotTimestamp).join(", ")}]`
@@ -743,6 +786,7 @@ export default defineCommand({
743786
zoomScale,
744787
autoProxy: args.proxy as boolean | undefined,
745788
browserGpuMode: resolveLocalBrowserGpuMode(args["browser-gpu"] as boolean | undefined),
789+
against,
746790
});
747791

748792
if (paths.length === 0) {
@@ -758,6 +802,11 @@ export default defineCommand({
758802
for (const p of paths) {
759803
console.log(` ${p}`);
760804
}
805+
if (against) {
806+
console.log(
807+
` ${c.dim("ref-*.png + pair-*.jpg")} beside each frame (reference frame, render | reference sheet)`,
808+
);
809+
}
761810

762811
// Generate contact sheet for quick AI review
763812
try {

0 commit comments

Comments
 (0)