Skip to content

Commit 3f42dc1

Browse files
feat(cli): diff --offset compares the original at t with yours at t + offset (heygen-com#7057)
* feat(cli): diff --offset compares the original at t with yours at t + offset Every per-frame measure (SSIM per frame and per cell, frames.tsv, cuts, missing content) reads yours offset seconds later, and a project folder is captured at the shifted times. The window keeps to where both sides have frames and says so in warnings; an offset with no overlap, or one that is not a number, is refused with a fix. Sound keeps its own offset reading, duration is reported as not measured, and the result echoes offset. * refactor(cli): trim diff offset comments under the file's comment share * fix(cli): rebase full-length diff offsets and reject overflow Keep offset streams on a zero-based clock even when every frame is selected. Cover an untrimmed delayed render and reject non-finite offsets before file or project processing. — Jerrai * refactor(cli): remove redundant offset filter comment — Jerrai
1 parent 7ae1080 commit 3f42dc1

5 files changed

Lines changed: 434 additions & 52 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1574,13 +1574,23 @@ npx hyperframes diff original.mp4 renders/final.mp4 --segments segments.md --sbs
15741574
| ----------------------------------------- | -------------------------------------------------------------------- |
15751575
| `--at` | Compare only these seconds |
15761576
| `--range` | Compare every frame of `start,end` seconds |
1577+
| `--offset` | Compare the original at t with yours at t + offset seconds |
15771578
| `--segments` | A verdict per `## S01 · a–b s` segment of a file |
15781579
| `--drawn` | Score one drawn element's box `x,y,w,h[,a-b]` by itself (repeatable) |
15791580
| `--min-mean` / `--min-p05` / `--min-cell` | The SSIM bars to pass |
15801581
| `--sbs` | Also write an original-beside-yours video |
15811582
| `--out` | Folder for the sheet and log (default `.hyperframes/diff/<yours>`) |
15821583
| `--json` | Print one JSON result |
15831584

1585+
`--offset` takes seconds, negative when yours runs ahead of the original. Every
1586+
per-frame score, cut and missing-content span is then read from yours at
1587+
t + offset, and a project folder is captured at those times. The comparison keeps
1588+
to the stretch where both sides have frames: `window` reports it and `warnings`
1589+
says when frames were left out. `frames.tsv` keeps the original's time in `t`;
1590+
yours' time is t + offset. The sound keeps its own offset measurement, the
1591+
duration is reported as not measured, and the JSON result echoes `offset`. An
1592+
offset that leaves no overlap is refused with a fix.
1593+
15841594
## Edit from the command line
15851595

15861596
### `timeline`

‎packages/cli/src/commands/diff.exit.test.ts‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,45 @@ describe("diff ends the process once its result is out", () => {
2424
expect(scheduleCliExit).toHaveBeenLastCalledWith(1);
2525
});
2626

27+
it("prints ok: false with a fix for an --offset that is not a number", async () => {
28+
const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
29+
const missing = join(dir, "missing.mp4");
30+
await expect(
31+
diffCommand.run?.({
32+
args: { reference: missing, yours: missing, json: true, offset: "soon" },
33+
rawArgs: [],
34+
} as never),
35+
).rejects.toThrow();
36+
expect(JSON.parse(String(log.mock.calls.at(-1)?.[0]))).toMatchObject({
37+
ok: false,
38+
error: '--offset must be a number of seconds, got "soon"',
39+
fix: expect.stringContaining("--offset 0.5"),
40+
});
41+
expect(scheduleCliExit).toHaveBeenLastCalledWith(1);
42+
});
43+
44+
it.each([
45+
{ kind: "video", yours: join(dir, "missing.mp4"), offset: "1e309" },
46+
{ kind: "project folder", yours: dir, offset: "+1e309" },
47+
])(
48+
"refuses a non-finite --offset for a $kind before reading media",
49+
async ({ yours, offset }) => {
50+
const log = vi.spyOn(console, "log").mockImplementation(() => undefined);
51+
await expect(
52+
diffCommand.run?.({
53+
args: { reference: join(dir, "missing.mp4"), yours, json: true, offset },
54+
rawArgs: [],
55+
} as never),
56+
).rejects.toThrow();
57+
expect(JSON.parse(String(log.mock.calls.at(-1)?.[0]))).toMatchObject({
58+
ok: false,
59+
error: `--offset must be a number of seconds, got "${offset}"`,
60+
fix: expect.stringContaining("--offset 0.5"),
61+
});
62+
expect(scheduleCliExit).toHaveBeenLastCalledWith(1);
63+
},
64+
);
65+
2766
describe.skipIf(noTools)("with a clip", () => {
2867
loadOpenCvFirst();
2968

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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import {
1111
DEFAULT_MIN_P05,
1212
diffVideos,
1313
findLedger,
14+
parseOffset,
1415
type DiffResult,
1516
} from "../measure/diff.js";
1617
import { Fix, formatJson, outDir, parseNumbers, parseRange } from "../measure/media.js";
@@ -98,7 +99,7 @@ function printHuman(r: DiffResult) {
9899
);
99100
if (r.duration)
100101
console.log(
101-
` duration: original ${r.duration.reference} s, yours ${r.duration.yours} s${r.duration.pass ? "" : " (differ)"}`,
102+
` duration: original ${r.duration.reference} s, yours ${r.duration.yours} s${r.duration.pass === null ? ` (${r.duration.note})` : r.duration.pass ? "" : " (differ)"}`,
102103
);
103104
if (r.sound)
104105
console.log(
@@ -164,6 +165,10 @@ export default defineCommand({
164165
},
165166
at: { type: "string", description: "Compare only these seconds, e.g. 0.5,2.4" },
166167
range: { type: "string", description: "Compare every frame of start,end seconds" },
168+
offset: {
169+
type: "string",
170+
description: "Compare the original at t with yours at t + offset seconds (may be negative)",
171+
},
167172
segments: {
168173
type: "string",
169174
description:
@@ -236,6 +241,7 @@ export default defineCommand({
236241
: resolve(String(args.ledger)),
237242
project: args.project === undefined ? undefined : resolve(String(args.project)),
238243
drawn: repeated(rawArgs, "--drawn").map(parseDrawn),
244+
offset: args.offset === undefined ? undefined : parseOffset(args.offset),
239245
thresholds: {
240246
mean: number(args["min-mean"], "--min-mean"),
241247
p05: number(args["min-p05"], "--min-p05"),
Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
import { readFileSync } from "node:fs";
2+
import { join } from "node:path";
3+
import { describe, expect, it } from "vitest";
4+
import {
5+
captureTimes,
6+
clipPick,
7+
diffVideos,
8+
overlapFrames,
9+
parseOffset,
10+
yoursFilters,
11+
type DiffResult,
12+
} from "./diff.js";
13+
import {
14+
clipFolder,
15+
diffVerdicts,
16+
loadOpenCvFirst,
17+
noTools,
18+
REF_ARGS,
19+
} from "./diff.test-helpers.js";
20+
import { Fix } from "./media.js";
21+
22+
const { dir, clip } = clipFolder("hf-diff-offset-test-");
23+
24+
describe("offset frame times", () => {
25+
it("reads yours from t + offset, and as before with no offset", () => {
26+
expect(yoursFilters({ kind: "all" }, "30")).toEqual(["fps=30"]);
27+
expect(yoursFilters({ kind: "all" }, "30", 0)).toEqual(["fps=30"]);
28+
expect(yoursFilters({ kind: "range", k0: 3, k1: 6 }, "30", 0.5)).toEqual([
29+
"fps=30:start_time=0.5",
30+
"select=between(n\\,3\\,5)",
31+
"setpts=N/(30)/TB",
32+
]);
33+
expect(yoursFilters({ kind: "all" }, "30000/1001", -0.25)).toEqual([
34+
"fps=30000/1001:start_time=-0.25",
35+
"setpts=N/(30000/1001)/TB",
36+
]);
37+
expect(yoursFilters({ kind: "all" }, "30", 0.5)).toEqual([
38+
"fps=30:start_time=0.5",
39+
"setpts=N/(30)/TB",
40+
]);
41+
});
42+
43+
it("captures a project at each frame's time plus the offset", () => {
44+
expect(captureTimes([0, 15, 30], 30)).toEqual([0, 0.5, 1]);
45+
expect(captureTimes([0, 15, 30], 30, 0.5)).toEqual([0.5, 1, 1.5]);
46+
expect(captureTimes([15, 30], 30, -0.5)).toEqual([0, 0.5]);
47+
});
48+
49+
it("keeps the original's frames that land on yours, for either sign", () => {
50+
// 3 s at 30 fps on both sides.
51+
expect(overlapFrames(90, 30, 0.5, 90)).toEqual([0, 75]);
52+
expect(overlapFrames(90, 30, -0.5, 90)).toEqual([15, 90]);
53+
// Yours 3.5 s: a half-second lead-in leaves every frame of the original inside it.
54+
expect(overlapFrames(90, 30, 0.5, 105)).toEqual([0, 90]);
55+
expect(overlapFrames(90, 30, -0.1, 90)).toEqual([3, 90]);
56+
// A project's end is not known before capture: only its start bounds the window.
57+
expect(overlapFrames(90, 30, 2, undefined)).toEqual([0, 90]);
58+
expect(overlapFrames(90, 30, -2, undefined)).toEqual([60, 90]);
59+
expect(overlapFrames(90, 30, 5, 90)).toEqual([0, 0]);
60+
expect(overlapFrames(90, 30, -5, 90)).toEqual([90, 90]);
61+
});
62+
63+
it("clips each kind of pick to the overlap", () => {
64+
expect(clipPick({ kind: "all" }, 90, [0, 90])).toEqual({ kind: "all" });
65+
expect(clipPick({ kind: "all" }, 90, [15, 90])).toEqual({ kind: "range", k0: 15, k1: 90 });
66+
expect(clipPick({ kind: "range", k0: 10, k1: 80 }, 90, [0, 75])).toEqual({
67+
kind: "range",
68+
k0: 10,
69+
k1: 75,
70+
});
71+
expect(clipPick({ kind: "at", ks: [3, 20, 80] }, 90, [15, 75])).toEqual({
72+
kind: "at",
73+
ks: [20],
74+
});
75+
});
76+
77+
it("reads a number of seconds, negative too, and refuses anything else with a fix", () => {
78+
expect(parseOffset("0.5")).toBe(0.5);
79+
expect(parseOffset("-0.5")).toBe(-0.5);
80+
expect(parseOffset(" 2 ")).toBe(2);
81+
for (const bad of [
82+
"",
83+
"abc",
84+
"0.5s",
85+
"1,2",
86+
"0x10",
87+
"Infinity",
88+
"1e309",
89+
"+1e309",
90+
"-1e309",
91+
true,
92+
])
93+
expect(() => parseOffset(bad)).toThrow(Fix);
94+
try {
95+
parseOffset("abc");
96+
} catch (err) {
97+
expect(err instanceof Fix && err.fix).toContain("--offset 0.5");
98+
}
99+
});
100+
});
101+
102+
describe.skipIf(noTools)("diffVideos with an offset", () => {
103+
loadOpenCvFirst();
104+
const ref = noTools ? "" : clip("ref.mp4", REF_ARGS);
105+
// Half a second of black, then the original's first 2.5 s: yours runs 0.5 s behind, 3 s long.
106+
const late = noTools
107+
? ""
108+
: clip("late.mp4", [
109+
...["-f", "lavfi", "-i", "color=c=black:s=320x180:r=30:d=0.5", "-i", ref],
110+
...["-filter_complex", "[0][1]concat=n=2:v=1[v]", "-map", "[v]", "-t", "3"],
111+
]);
112+
// The original from 0.5 s: yours runs 0.5 s ahead.
113+
const early = noTools ? "" : clip("early.mp4", ["-ss", "0.5", "-i", ref]);
114+
115+
it("compares the original at t with a late render at t + offset, clipped to its end", async () => {
116+
const off = await diffVerdicts({ reference: ref, yours: late, outDir: join(dir, "late-0") });
117+
expect(off.pass).toBe(false);
118+
const r = await diffVerdicts({
119+
reference: ref,
120+
yours: late,
121+
offset: 0.5,
122+
outDir: join(dir, "late"),
123+
});
124+
expect(r.offset).toBe(0.5);
125+
expect(r.ssim.frames).toBe(75);
126+
expect(r.ssim.mean).toBeGreaterThan(0.99);
127+
expect(r.window).toEqual([0, 2.5]);
128+
expect(r.warnings.join(" ")).toContain("15 of 90 frames fall outside yours");
129+
expect(r.duration).toMatchObject({ pass: null });
130+
expect(r.duration?.note).toContain("not measured");
131+
expect(r.pass).toBe(true);
132+
const rows = readFileSync(r.frames, "utf8").trim().split("\n");
133+
expect(rows[0]).toBe("t\tframe\tssim\tworst_cell\tcell");
134+
expect(rows).toHaveLength(76);
135+
expect(rows[1]!.split("\t").slice(0, 2)).toEqual(["0", "0"]);
136+
});
137+
138+
it("compares every original frame with an untrimmed late render", async () => {
139+
const yours = clip("late-full.mp4", ["-i", ref, "-vf", "tpad=start_duration=0.5"]);
140+
const r = await diffVerdicts({
141+
reference: ref,
142+
yours,
143+
offset: 0.5,
144+
outDir: join(dir, "late-full"),
145+
});
146+
expect(r.ssim.mean).toBeGreaterThan(0.99);
147+
expect(r.ssim.frames).toBe(90);
148+
expect(r.window).toEqual([0, 3]);
149+
expect(r.warnings).toEqual([]);
150+
expect(r.pass).toBe(true);
151+
});
152+
153+
it("compares an early render with a negative offset, clipped to its start", async () => {
154+
const r = await diffVerdicts({
155+
reference: ref,
156+
yours: early,
157+
offset: -0.5,
158+
outDir: join(dir, "early"),
159+
});
160+
expect(r.ssim.frames).toBe(75);
161+
expect(r.ssim.mean).toBeGreaterThan(0.99);
162+
expect(r.window).toEqual([0.5, 3]);
163+
expect(r.missing_content.pass).toBe(true);
164+
expect(r.pass).toBe(true);
165+
const first = readFileSync(r.frames, "utf8").split("\n")[1]!.split("\t");
166+
expect(first.slice(0, 2)).toEqual(["0.5", "15"]);
167+
});
168+
169+
it("matches yours' cuts after taking the offset off them", async () => {
170+
const cut = (name: string, lead: number) =>
171+
clip(name, [
172+
...["-f", "lavfi", "-i", `color=c=0x2050c0:s=320x180:r=30:d=${1 + lead}`],
173+
...["-f", "lavfi", "-i", `color=c=0xe0c040:s=320x180:r=30:d=2`],
174+
...["-filter_complex", "[0][1]concat=n=2:v=1[v]", "-map", "[v]"],
175+
]);
176+
const [reference, yours] = [cut("cut-ref.mp4", 0), cut("cut-late.mp4", 0.5)];
177+
const plain = await diffVerdicts({ reference, yours, outDir: join(dir, "cut-0") });
178+
expect(plain.cuts).toMatchObject({ missing: [1], extra: [1.5], pass: false });
179+
const r = await diffVerdicts({ reference, yours, offset: 0.5, outDir: join(dir, "cut") });
180+
expect(r.cuts).toMatchObject({
181+
reference: [1],
182+
yours: [1],
183+
missing: [],
184+
extra: [],
185+
pass: true,
186+
});
187+
});
188+
189+
it("refuses an offset that leaves no overlap", async () => {
190+
for (const options of [{ offset: 5 }, { offset: -5 }, { offset: 0.5, at: [2.8] }])
191+
await expect(
192+
diffVerdicts({ reference: ref, yours: late, outDir: join(dir, "none"), ...options }),
193+
).rejects.toThrow(/leaves no overlap/);
194+
});
195+
196+
it("writes the same frames and result at offset 0 as with none", async () => {
197+
const yours = clip("box.mp4", [
198+
...["-i", ref, "-vf"],
199+
"drawbox=x=40:y=40:w=80:h=60:color=red:t=fill:enable='between(t,1,2)'",
200+
]);
201+
const out = join(dir, "zero");
202+
const read = () => ["frames.tsv", "ssim.log"].map((f) => readFileSync(join(out, f)));
203+
const none = await diffVideos({ reference: ref, yours, outDir: out });
204+
const before = read();
205+
const zero = await diffVideos({ reference: ref, yours, offset: 0, outDir: out });
206+
expect(read()).toEqual(before);
207+
expect("offset" in none).toBe(false);
208+
const { offset, ...rest }: DiffResult = zero;
209+
expect(offset).toBe(0);
210+
expect(JSON.stringify(rest)).toBe(JSON.stringify(none));
211+
});
212+
});

0 commit comments

Comments
 (0)