Skip to content

Commit b6467d9

Browse files
perf(engine): re-renders reuse the extracted frames of remote videos (#5408)
* perf(engine): re-renders reuse the extracted frames of remote videos A remote video is downloaded into the render's own work dir, so its path and mtime are new on every render. The extraction cache keyed on both, so a re-render of a composition with a remote video never hit the cache and ran ffmpeg over the whole clip again. Key a downloaded source on the SHA-256 of its bytes instead. Keys of local sources are unchanged. * fix(engine): key the video copies a render writes itself by content The producer downloads a remote video at compile time and copies it into the render's compiled dir, so the extractor never sees the https src. Key any source inside the compiled dir or the extractor's own output dir by content, and skip the cache for one that cannot be read. * perf(engine): hash a render-written video only when its cache lookup runs Distributed planning copies the whole project into the compiled dir and defers long video extractions, which never look up the cache. Hash render-written sources just before the lookup, once per file, so deferred ranges and repeated sources are not hashed. * fix(engine): cache only downloaded media by content, not distributed project copies A distributed plan copies the whole project into the compiled dir, so keying everything there by content would hash every project video on the planner. Content-key the extractor's own downloads and the dirs the caller names; the producer names its remote media dir. Hashing stops on abort, and a source with no hash skips the cache. * style(engine): keep the extraction cache's comment share at its base * test(engine): pin no hashing with the cache off and the producer's remote-media dir * test(engine): run the cache-off case through the shared render helper
1 parent 165be85 commit b6467d9

8 files changed

Lines changed: 298 additions & 17 deletions

File tree

‎.fallowrc.jsonc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -466,6 +466,9 @@
466466
// require intrusive middleware changes beyond this PR's scope.
467467
"minLines": 6,
468468
"ignore": [
469+
// Pre-existing clone with extractVideosStage.ffmpegTimeout.test.ts: both mock the engine's whole
470+
// ExtractionResult. Touching the mock to record another option re-flags it.
471+
"packages/producer/src/services/render/stages/extractVideosStage.timelineBound.test.ts",
469472
// AWS Lambda and GCP Cloud Run deliberately mirror the same distributed
470473
// rendering lifecycle while retaining provider-specific SDK, storage, and
471474
// retry semantics. The Plan v2 AWS adapter extends that existing symmetry;

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import { afterEach, beforeEach, describe, expect, it } from "vitest";
2+
import { createHash } from "node:crypto";
23
import {
34
existsSync,
45
mkdirSync,
@@ -24,6 +25,7 @@ import {
2425
markCacheEntryComplete,
2526
partialCacheEntryDir,
2627
publishCacheEntry,
28+
readContentSha256,
2729
readKeyStat,
2830
rehydrateCacheEntry,
2931
touchCacheDir,
@@ -139,6 +141,34 @@ describe("computeCacheKey", () => {
139141
expect(key).toMatch(/^[0-9a-f]{64}$/);
140142
});
141143

144+
it("keys a path-keyed source exactly as before content keys existed", () => {
145+
const input = base(sourceFile);
146+
const legacyBlob = JSON.stringify({
147+
p: input.videoPath,
148+
m: input.mtimeMs,
149+
s: input.size,
150+
ms: 0,
151+
d: 3,
152+
f: "30",
153+
fmt: "jpg",
154+
});
155+
expect(computeCacheKey(input)).toBe(createHash("sha256").update(legacyBlob).digest("hex"));
156+
});
157+
158+
it("keys a content-addressed source by its bytes, not its path or mtime", () => {
159+
const moved = join(tmpRoot, "moved.mp4");
160+
writeFileSync(moved, "fake-video-bytes", "utf-8");
161+
const original = computeCacheKey({ ...base(sourceFile), contentSha256: "a1" });
162+
expect(computeCacheKey({ ...base(moved), mtimeMs: 1, contentSha256: "a1" })).toBe(original);
163+
expect(computeCacheKey({ ...base(sourceFile), contentSha256: "b2" })).not.toBe(original);
164+
});
165+
166+
it("hashes a file's bytes for its content key, or skips the cache when unreadable", async () => {
167+
const expected = createHash("sha256").update("fake-video-bytes").digest("hex");
168+
expect(await readContentSha256(sourceFile)).toBe(expected);
169+
expect(await readContentSha256(join(tmpRoot, "missing.mp4"))).toBeNull();
170+
});
171+
142172
it("changes when path changes (moved files re-extract)", () => {
143173
const other = join(tmpRoot, "other.mp4");
144174
writeFileSync(other, "fake-video-bytes", "utf-8");

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

Lines changed: 23 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@
3434

3535
import { createHash, randomUUID } from "node:crypto";
3636
import {
37+
createReadStream,
3738
existsSync,
3839
lstatSync,
3940
mkdirSync,
@@ -88,6 +89,8 @@ export interface CacheKeyInput {
8889
format: CacheFrameFormat;
8990
/** Optional source transform applied during extraction. */
9091
transform?: string;
92+
/** SHA-256 of the source bytes, in place of path and mtime (downloaded media gets new ones each render). */
93+
contentSha256?: string;
9194
}
9295

9396
export interface CacheEntry {
@@ -110,6 +113,19 @@ export interface CachePublishResult {
110113
published: boolean;
111114
}
112115

116+
export async function readContentSha256(
117+
path: string,
118+
signal?: AbortSignal,
119+
): Promise<string | null> {
120+
try {
121+
const hash = createHash("sha256");
122+
for await (const chunk of createReadStream(path, { signal })) hash.update(chunk);
123+
return hash.digest("hex");
124+
} catch {
125+
return null;
126+
}
127+
}
128+
113129
/**
114130
* Read `(mtimeMs, size)` for a path. Returns `null` if the file is missing —
115131
* callers should skip the cache path for that entry so the extractor surfaces
@@ -128,18 +144,13 @@ export function readKeyStat(videoPath: string): { mtimeMs: number; size: number
128144

129145
function canonicalKeyBlob(input: CacheKeyInput): string {
130146
const durationForKey = Number.isFinite(input.duration) ? input.duration : -1;
131-
const blob: {
132-
p: string;
133-
m: number;
134-
s: number;
135-
ms: number;
136-
d: number;
137-
f: string;
138-
fmt: CacheFrameFormat;
139-
t?: string;
140-
} = {
141-
p: input.videoPath,
142-
m: input.mtimeMs,
147+
// Identity first, so keys of path-keyed entries stay byte-identical.
148+
const identity: Record<string, string | number> =
149+
input.contentSha256 !== undefined
150+
? { c: input.contentSha256 }
151+
: { p: input.videoPath, m: input.mtimeMs };
152+
const blob: Record<string, string | number> = {
153+
...identity,
143154
s: input.size,
144155
ms: input.mediaStart,
145156
d: durationForKey,
Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
2+
import { tmpdir } from "node:os";
3+
import { join } from "node:path";
4+
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
5+
import type { VideoElement } from "../types.js";
6+
import { runFfmpeg } from "../utils/runFfmpeg.js";
7+
8+
// Each render gets its own copy of the clip: new path and mtime, same bytes.
9+
const source = vi.hoisted(() => ({ clip: "" }));
10+
vi.mock("../utils/urlDownloader.js", async (importOriginal) => ({
11+
...(await importOriginal<typeof import("../utils/urlDownloader.js")>()),
12+
downloadToTemp: async (_url: string, destDir: string) => {
13+
const local = join(destDir, "clip.mp4");
14+
copyFileSync(source.clip, local);
15+
return local;
16+
},
17+
}));
18+
19+
const hashing = vi.hoisted(() => ({ paths: [] as string[] }));
20+
vi.mock("./extractionCache.js", async (importOriginal) => {
21+
const actual = await importOriginal<typeof import("./extractionCache.js")>();
22+
return {
23+
...actual,
24+
readContentSha256: async (path: string) => {
25+
hashing.paths.push(path);
26+
return actual.readContentSha256(path);
27+
},
28+
};
29+
});
30+
31+
const { extractAllVideoFrames } = await import("./videoFrameExtractor.js");
32+
33+
describe.skipIf(process.platform === "win32")("extractAllVideoFrames downloaded sources", () => {
34+
const dir = mkdtempSync(join(tmpdir(), "hf-extract-render-owned-"));
35+
const cacheDir = join(dir, "cache");
36+
let red = "";
37+
let blue = "";
38+
let green = "";
39+
40+
async function synth(color: string, seconds = 1): Promise<string> {
41+
const clip = join(dir, `${color}-${seconds}s.mp4`);
42+
const made = await runFfmpeg([
43+
...["-y", "-v", "error", "-f", "lavfi", "-i", `color=c=${color}:s=32x16:d=${seconds}:r=30`],
44+
...["-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", clip],
45+
]);
46+
expect(made.success, made.stderr).toBe(true);
47+
return clip;
48+
}
49+
50+
function clipElement(src: string, id = "clip", end = 1): VideoElement {
51+
return { id, src, start: 0, end, mediaStart: 0, loop: false, hasAudio: false };
52+
}
53+
54+
// The producer downloads a remote src at compile time into the render's compiled dir;
55+
// a distributed plan also copies the whole project there (`subdir: "."`).
56+
function renderCompiledCopy(
57+
name: string,
58+
videos = [clipElement("_remote_media/clip.mp4")],
59+
{
60+
deferRangeExtraction = false,
61+
subdir = "_remote_media",
62+
config = { extractCacheDir: cacheDir } as { extractCacheDir?: string },
63+
} = {},
64+
) {
65+
const compiledDir = join(dir, name, "compiled");
66+
mkdirSync(join(compiledDir, subdir), { recursive: true });
67+
copyFileSync(source.clip, join(compiledDir, subdir, "clip.mp4"));
68+
const outputDir = join(compiledDir, "frames");
69+
return extractAllVideoFrames(
70+
videos,
71+
join(dir, "project"),
72+
{
73+
...{ fps: 30, outputDir, deferRangeExtraction },
74+
contentKeyedDirs: [join(compiledDir, "_remote_media")],
75+
},
76+
undefined,
77+
config,
78+
compiledDir,
79+
);
80+
}
81+
82+
function firstFrameBytes(result: Awaited<ReturnType<typeof extractAllVideoFrames>>): Buffer {
83+
const frame = result.extracted[0]?.framePaths.get(0);
84+
if (!frame) throw new Error("missing first frame");
85+
return readFileSync(frame);
86+
}
87+
88+
function renderRemoteSrc(name: string) {
89+
const outputDir = join(dir, name);
90+
mkdirSync(outputDir, { recursive: true });
91+
return extractAllVideoFrames(
92+
[clipElement("https://cdn.example.com/clip.mp4")],
93+
dir,
94+
{ fps: 30, outputDir },
95+
undefined,
96+
{ extractCacheDir: cacheDir },
97+
);
98+
}
99+
100+
beforeAll(async () => {
101+
mkdirSync(join(dir, "project"), { recursive: true });
102+
red = await synth("red");
103+
blue = await synth("blue");
104+
green = await synth("green");
105+
});
106+
107+
afterAll(() => rmSync(dir, { recursive: true, force: true }));
108+
109+
it("a re-render reuses the frames of a video copied into its compiled dir", async () => {
110+
source.clip = red;
111+
const first = await renderCompiledCopy("compiled-1");
112+
const second = await renderCompiledCopy("compiled-2");
113+
expect(first.errors).toEqual([]);
114+
expect(first.phaseBreakdown.cacheMisses).toBe(1);
115+
expect(second.errors).toEqual([]);
116+
expect(second.phaseBreakdown.cacheHits).toBe(1);
117+
expect(second.phaseBreakdown.cacheMisses).toBe(0);
118+
expect(second.extracted[0]?.totalFrames).toBe(first.extracted[0]?.totalFrames);
119+
expect(firstFrameBytes(second).equals(firstFrameBytes(first))).toBe(true);
120+
});
121+
122+
it("a re-render reuses the frames of a video the extractor downloaded itself", async () => {
123+
source.clip = blue;
124+
await renderRemoteSrc("remote-1");
125+
const second = await renderRemoteSrc("remote-2");
126+
expect(second.errors).toEqual([]);
127+
expect(second.phaseBreakdown.cacheHits).toBe(1);
128+
});
129+
130+
it("a render-owned video whose bytes changed extracts again", async () => {
131+
source.clip = red;
132+
await renderCompiledCopy("changed-1");
133+
source.clip = green;
134+
const changed = await renderCompiledCopy("changed-2");
135+
expect(changed.errors).toEqual([]);
136+
expect(changed.phaseBreakdown.cacheHits).toBe(0);
137+
expect(changed.phaseBreakdown.cacheMisses).toBe(1);
138+
});
139+
140+
it("hashes a file once however many videos use it", async () => {
141+
source.clip = red;
142+
hashing.paths = [];
143+
const result = await renderCompiledCopy("shared", [
144+
clipElement("_remote_media/clip.mp4", "a"),
145+
{ ...clipElement("_remote_media/clip.mp4", "b"), start: 1, mediaStart: 0.5, end: 1.5 },
146+
]);
147+
expect(result.errors).toEqual([]);
148+
expect(hashing.paths).toHaveLength(1);
149+
});
150+
151+
it("does not hash a video whose extraction is deferred", async () => {
152+
source.clip = await synth("yellow", 3);
153+
hashing.paths = [];
154+
const result = await renderCompiledCopy(
155+
"deferred",
156+
[clipElement("_remote_media/clip.mp4", "clip", 3)],
157+
{ deferRangeExtraction: true },
158+
);
159+
expect(result.errors).toEqual([]);
160+
expect(result.extracted[0]?.deferredRange).toBeDefined();
161+
expect(hashing.paths).toEqual([]);
162+
});
163+
164+
it("keeps a project copy outside the download dirs on its path key", async () => {
165+
source.clip = red;
166+
hashing.paths = [];
167+
const first = await renderCompiledCopy("copy-1", [clipElement("clip.mp4")], { subdir: "." });
168+
const second = await renderCompiledCopy("copy-2", [clipElement("clip.mp4")], { subdir: "." });
169+
expect(second.errors).toEqual([]);
170+
expect(first.phaseBreakdown.cacheHits + second.phaseBreakdown.cacheHits).toBe(0);
171+
expect(hashing.paths).toEqual([]);
172+
});
173+
174+
it("does not hash when the cache is off", async () => {
175+
source.clip = red;
176+
hashing.paths = [];
177+
const result = await renderCompiledCopy("cache-off", undefined, { config: {} });
178+
expect(result.errors).toEqual([]);
179+
expect(hashing.paths).toEqual([]);
180+
});
181+
});

0 commit comments

Comments
 (0)