Skip to content

Commit 4857a94

Browse files
Merge 161cd60 into 471e90c
2 parents 471e90c + 161cd60 commit 4857a94

8 files changed

Lines changed: 118 additions & 27 deletions

File tree

‎packages/engine/src/services/extractionCache.test.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,8 @@ function seedPartialDir(entry: { dir: string; keyHash: string }, frameContent: s
6565
}
6666

6767
describe("extractionCache constants", () => {
68-
it("exposes the v5 schema prefix", () => {
69-
expect(SCHEMA_PREFIX).toBe("hfcache-v5-");
68+
it("exposes the v6 schema prefix", () => {
69+
expect(SCHEMA_PREFIX).toBe("hfcache-v6-");
7070
});
7171

7272
it("exposes the frame filename prefix shared with the extractor", () => {

‎packages/engine/src/services/extractionCache.ts‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -58,16 +58,10 @@ export const COMPLETE_SENTINEL = ".hf-complete";
5858
export const GC_MARKER = ".hf-last-gc";
5959

6060
/**
61-
* Current schema version. Bump when the cache-contents invariant changes.
62-
* v2 -> v3: one-pass VFR extraction (-fps_mode cfr) replaces the two-pass
63-
* VFR-to-CFR re-encode, changing frame contents for VFR sources under
64-
* identical key tuples. Without the bump, warm v2 entries (two-pass frames)
65-
* would keep being served across the deploy boundary.
66-
* v3 -> v4: the target fps identity is the exact FFmpeg argument instead of
67-
* a JavaScript number. This invalidates entries created after rational NTSC
68-
* rates had already been rounded to a decimal.
61+
* Current schema version. Bump it whenever extraction writes different frames for the same key,
62+
* or warm entries keep serving the old frames across a deploy. Each bump's commit says why.
6963
*/
70-
export const SCHEMA_PREFIX = "hfcache-v5-";
64+
export const SCHEMA_PREFIX = "hfcache-v6-";
7165

7266
/** Truncated hex chars of SHA-256 used for the entry directory name. */
7367
const KEY_HEX_CHARS = 16;

‎packages/engine/src/services/videoFrameExtractor.test.ts‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1786,6 +1786,98 @@ describe.skipIf(!HAS_FFMPEG)("video frame extraction format", () => {
17861786
}, 60_000);
17871787
});
17881788

1789+
// Each output slot shows the frame on screen at its time, as the preview does.
1790+
describe.skipIf(!HAS_FFMPEG)("frame sampling at the output frame rate", () => {
1791+
const FIXTURE_DIR = mkdtempSync(join(tmpdir(), "hf-video-frame-sampling-"));
1792+
const WIDTH = 32;
1793+
const HEIGHT = 16;
1794+
// Matroska stores whole-millisecond timestamps (a 30 fps frame at 66.67 ms reads 67 ms);
1795+
// a 1/30 timescale stores each frame exactly on a coarse tick.
1796+
const SOURCES = {
1797+
"mp4-60": { fps: 60, file: "index-60fps.mp4", muxer: [] },
1798+
"mkv-30": { fps: 30, file: "index-30fps.mkv", muxer: [] },
1799+
"mp4-30-timescale-30": {
1800+
fps: 30,
1801+
file: "index-30fps-ts30.mp4",
1802+
muxer: ["-video_track_timescale", "30"],
1803+
},
1804+
} as const;
1805+
type SourceName = keyof typeof SOURCES;
1806+
const sourcePath = (name: SourceName) => join(FIXTURE_DIR, SOURCES[name].file);
1807+
1808+
beforeAll(async () => {
1809+
for (const name of Object.keys(SOURCES) as SourceName[]) {
1810+
// Frame k carries luma 16 + 2k, so each extracted frame names its source index.
1811+
const result = await runFfmpeg([
1812+
"-y",
1813+
"-hide_banner",
1814+
"-loglevel",
1815+
"error",
1816+
"-f",
1817+
"lavfi",
1818+
"-i",
1819+
`nullsrc=s=${WIDTH}x${HEIGHT}:r=${SOURCES[name].fps}:d=1.5,geq=lum='16+2*N':cb=128:cr=128`,
1820+
"-c:v",
1821+
"libx264",
1822+
"-qp",
1823+
"0",
1824+
"-pix_fmt",
1825+
"yuv420p",
1826+
...SOURCES[name].muxer,
1827+
sourcePath(name),
1828+
]);
1829+
if (!result.success) throw new Error(`index fixture synthesis failed: ${result.stderr}`);
1830+
}
1831+
}, 30_000);
1832+
1833+
afterAll(() => {
1834+
rmSync(FIXTURE_DIR, { recursive: true, force: true });
1835+
});
1836+
1837+
function sourceIndexes(extracted: ExtractedFrames): number[] {
1838+
const decoded = spawnSync("ffmpeg", [
1839+
"-v",
1840+
"error",
1841+
"-i",
1842+
join(extracted.outputDir, extracted.framePattern),
1843+
"-f",
1844+
"rawvideo",
1845+
"-pix_fmt",
1846+
"gray",
1847+
"pipe:1",
1848+
]);
1849+
if (decoded.status !== 0) throw new Error(decoded.stderr.toString());
1850+
const indexes: number[] = [];
1851+
for (let offset = 0; offset < decoded.stdout.length; offset += WIDTH * HEIGHT) {
1852+
indexes.push(Math.round(((decoded.stdout[offset] ?? 0) * 219) / 255 / 2));
1853+
}
1854+
return indexes;
1855+
}
1856+
1857+
it.each([
1858+
{ source: "mp4-60", fps: 24, startTime: 0, duration: 0.5 },
1859+
{ source: "mp4-60", fps: 10, startTime: 0.37, duration: 0.6 },
1860+
{ source: "mkv-30", fps: 30, startTime: 0, duration: 0.5 },
1861+
{ source: "mp4-30-timescale-30", fps: 60, startTime: 0, duration: 0.5 },
1862+
] as const)(
1863+
"$source: samples the frame on screen at each $fps fps slot from $startTime s",
1864+
async (c) => {
1865+
const extracted = await extractVideoFramesRange(
1866+
sourcePath(c.source),
1867+
`${c.source}-${c.fps}`,
1868+
c.startTime,
1869+
c.duration,
1870+
{ fps: c.fps, outputDir: FIXTURE_DIR, format: "png" },
1871+
);
1872+
const onScreen = Array.from({ length: Math.round(c.duration * c.fps) }, (_, i) =>
1873+
Math.floor((c.startTime + i / c.fps) * SOURCES[c.source].fps + 1e-9),
1874+
);
1875+
expect(sourceIndexes(extracted)).toEqual(onScreen);
1876+
},
1877+
30_000,
1878+
);
1879+
});
1880+
17891881
describe.skipIf(!HAS_FFMPEG)("held tails on sparse-timestamp sources", () => {
17901882
const fixtureDir = mkdtempSync(join(tmpdir(), "hf-sparse-held-tail-"));
17911883
const cfrFixture = join(fixtureDir, "sub-1fps-cfr.mp4");

‎packages/engine/src/services/videoFrameExtractor.ts‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -827,12 +827,7 @@ export async function extractVideoFramesRange(
827827
options: ExtractionOptions,
828828
signal?: AbortSignal,
829829
config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout">>,
830-
/**
831-
* Override the output directory for this extraction. When provided, frames
832-
* are written directly into `outputDirOverride` (no per-videoId subdir).
833-
* Used by the cache layer to materialize frames straight into the keyed
834-
* cache entry directory.
835-
*/
830+
/** Frames go straight here, with no per-videoId subdir (the cache layer's keyed entry). */
836831
outputDirOverride?: string,
837832
): Promise<ExtractedFrames> {
838833
const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
@@ -877,6 +872,8 @@ export async function extractVideoFramesRange(
877872
const isHdr = isHdrColorSpaceUtil(metadata.colorSpace);
878873
const isMacOS = process.platform === "darwin";
879874

875+
const sampleCfrAtOutputFps = !options.finalFrameOnly && !metadata.isVFR;
876+
880877
const args: string[] = [];
881878
if (isHdr && isMacOS) {
882879
args.push("-hwaccel", "videotoolbox");
@@ -900,6 +897,8 @@ export async function extractVideoFramesRange(
900897
// a negative timestamp base) can seek to EOF and emit zero frames.
901898
args.push("-i", videoPath, "-ss", String(startTime), "-frames:v", "1");
902899
} else {
900+
// An accurate seek drops the frame on screen at startTime; the fps sampling below needs it.
901+
if (sampleCfrAtOutputFps) args.push("-noaccurate_seek");
903902
args.push("-ss", String(startTime), "-i", videoPath, "-t", String(duration));
904903
}
905904

@@ -908,8 +907,14 @@ export async function extractVideoFramesRange(
908907
// VideoToolbox tone-maps during decode; force output to bt709 SDR format
909908
vfFilters.push("format=nv12");
910909
}
911-
if (!options.finalFrameOnly && !metadata.isVFR) {
912-
vfFilters.push(`fps=${ffmpegFps}`);
910+
if (sampleCfrAtOutputFps) {
911+
// Each slot takes the last frame starting at or before its time. Ticks of 2 ms or finer
912+
// first shift half a tick, absorbing container rounding (WebM/MKV use whole ms).
913+
vfFilters.push(
914+
"settb=intb/2",
915+
"setpts=PTS-lte(TB\\,0.001)",
916+
`fps=${ffmpegFps}:start_time=0:round=up`,
917+
);
913918
}
914919
if (options.sdrToHdrTransfer) {
915920
// Ordering intent: fps sampling runs BEFORE the colorspace remap so only
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
version https://git-lfs.github.com/spec/v1
2-
oid sha256:21fde191f0b1c2e89f4dace8419b3f2274e44652a35d1ecaddd8fac5774413e8
3-
size 11095224
2+
oid sha256:7978a2502f3c187419ef7fd404f5f48998cf6799f5b565a588ea189a4665812a
3+
size 11712255
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
version https://git-lfs.github.com/spec/v1
2-
oid sha256:a0809b9b98e70674bef3da96055fd0c33f807bf26eac9e14c42acd13e270f2e4
3-
size 14425452
2+
oid sha256:af9dca1109886deef88b0400ed8d5cf0516e6e9b236fae166215ce7387d46877
3+
size 15006441
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
version https://git-lfs.github.com/spec/v1
2-
oid sha256:13e7dd6d0dbeca86db4b69ca00d985f331572166aeacfd1af7d0fb4abf6abe84
3-
size 22376857
2+
oid sha256:41e09a7519f56d573096ba01d2e5c9cf59956f5b54e9da5bb0a1467a49f48039
3+
size 22661197
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
version https://git-lfs.github.com/spec/v1
2-
oid sha256:c722ec4fc2496581eaedb5d86662f2a4a2eb4903099d870caf2877d8548eafb1
3-
size 15245778
2+
oid sha256:f917e469fd0d80c2393e153239254ba2bc9faf68bffc57cde4cc8dbb4e4ab986
3+
size 17512767

0 commit comments

Comments
 (0)