Skip to content

Commit c019def

Browse files
committed
feat(studio-server): probe media codec facts for proxy decisions
Adds the codec manifest: one ffprobe-backed answer to what codec an asset uses, whether a browser can decode it, and whether it carries alpha. Migrates the existing prober to the shared ff-binaries resolver and to async execFile so a scan pool runs off the event loop. No consumer yet; the preview weld wires it up later in the stack.
1 parent d7b38da commit c019def

7 files changed

Lines changed: 756 additions & 28 deletions

File tree

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,330 @@
1+
import { afterEach, beforeEach, describe, expect, it } from "vitest";
2+
import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
3+
import { join } from "node:path";
4+
import { tmpdir } from "node:os";
5+
import type { FfprobeRunner } from "./mediaMetadata.js";
6+
import {
7+
BROWSER_HOSTILE_CODECS,
8+
decideMediaProxyEligibility,
9+
createMediaCodecProbeCache,
10+
probeAssetCodec,
11+
scanProjectMediaCodecMap,
12+
} from "./mediaCodecMap.js";
13+
14+
// Any real, existing file works as a stand-in ffprobe path — the runner
15+
// passed to probeMediaMetadata is what's actually invoked, mirroring
16+
// packages/lint/src/project.test.ts's hevc_preview_codec pattern (keeps this
17+
// test independent of whether the host actually has ffprobe installed).
18+
const FAKE_FFPROBE_PATH = process.execPath;
19+
20+
function makeRunner(
21+
codecByPath: Record<string, string | { codecName: string; pixFmt?: string }>,
22+
): FfprobeRunner {
23+
return (_command, args) => {
24+
const filePath = args[args.length - 1] ?? "";
25+
const entry = codecByPath[filePath];
26+
const normalized = typeof entry === "string" ? { codecName: entry } : entry;
27+
const streams = normalized
28+
? [
29+
{
30+
codec_type: "video",
31+
codec_name: normalized.codecName,
32+
pix_fmt: normalized.pixFmt,
33+
},
34+
]
35+
: [];
36+
return { status: 0, stdout: JSON.stringify({ streams }), stderr: "" };
37+
};
38+
}
39+
40+
function countingRunner(runner: FfprobeRunner): {
41+
runner: FfprobeRunner;
42+
calls: () => number;
43+
} {
44+
let calls = 0;
45+
return {
46+
runner: (command, args, options) => {
47+
calls++;
48+
return runner(command, args, options);
49+
},
50+
calls: () => calls,
51+
};
52+
}
53+
54+
function videoHtml(...srcs: string[]): string {
55+
const tags = srcs
56+
.map(
57+
(src, i) =>
58+
`<video id="v${i}" class="clip" src="${src}" muted data-start="0" data-duration="5"></video>`,
59+
)
60+
.join("\n");
61+
return `<html><body><div data-composition-id="main" data-width="1920" data-height="1080" data-start="0" data-duration="10">${tags}</div></body></html>`;
62+
}
63+
64+
let dirs: string[] = [];
65+
66+
function tmpProject(): string {
67+
const dir = mkdtempSync(join(tmpdir(), "hf-media-codec-map-test-"));
68+
dirs.push(dir);
69+
return dir;
70+
}
71+
72+
beforeEach(() => {
73+
process.env.HYPERFRAMES_FFPROBE_PATH = FAKE_FFPROBE_PATH;
74+
});
75+
76+
afterEach(() => {
77+
delete process.env.HYPERFRAMES_FFPROBE_PATH;
78+
for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
79+
dirs = [];
80+
});
81+
82+
describe("probeAssetCodec", () => {
83+
it("reports an HEVC asset as browser-hostile with the pinned representative mime", async () => {
84+
const project = tmpProject();
85+
const videoPath = join(project, "clip.mp4");
86+
writeFileSync(videoPath, "fake video bytes");
87+
88+
const facts = await probeAssetCodec(videoPath, makeRunner({ [videoPath]: "hevc" }));
89+
90+
expect(facts).toEqual({
91+
codecName: "hevc",
92+
browserHostile: true,
93+
representativeMime: BROWSER_HOSTILE_CODECS.hevc,
94+
hasAlpha: false,
95+
});
96+
});
97+
98+
it("reports an H.264 asset as not browser-hostile", async () => {
99+
const project = tmpProject();
100+
const videoPath = join(project, "clip.mp4");
101+
writeFileSync(videoPath, "fake video bytes");
102+
103+
const facts = await probeAssetCodec(videoPath, makeRunner({ [videoPath]: "h264" }));
104+
105+
expect(facts).toEqual({
106+
codecName: "h264",
107+
browserHostile: false,
108+
representativeMime: null,
109+
hasAlpha: false,
110+
});
111+
});
112+
113+
it("treats VP9 as conditionally hostile so unsupported browsers can request a proxy", async () => {
114+
const project = tmpProject();
115+
const videoPath = join(project, "clip.webm");
116+
writeFileSync(videoPath, "fake video bytes");
117+
118+
const facts = await probeAssetCodec(videoPath, makeRunner({ [videoPath]: "vp9" }));
119+
120+
expect(facts).toEqual({
121+
codecName: "vp9",
122+
browserHostile: true,
123+
representativeMime: BROWSER_HOSTILE_CODECS.vp9,
124+
hasAlpha: false,
125+
});
126+
});
127+
128+
it("reports ProRes as browser-hostile with no representative mime", async () => {
129+
const project = tmpProject();
130+
const videoPath = join(project, "clip.mov");
131+
writeFileSync(videoPath, "fake video bytes");
132+
133+
const facts = await probeAssetCodec(videoPath, makeRunner({ [videoPath]: "prores" }));
134+
135+
expect(facts).toEqual({
136+
codecName: "prores",
137+
browserHostile: true,
138+
representativeMime: null,
139+
hasAlpha: false,
140+
});
141+
});
142+
143+
it("flags an alpha-bearing pix_fmt (ProRes 4444) with hasAlpha", async () => {
144+
const project = tmpProject();
145+
const videoPath = join(project, "clip.mov");
146+
writeFileSync(videoPath, "fake video bytes");
147+
148+
const facts = await probeAssetCodec(
149+
videoPath,
150+
makeRunner({
151+
[videoPath]: { codecName: "prores", pixFmt: "yuva444p10le" },
152+
}),
153+
);
154+
155+
expect(facts).toEqual({
156+
codecName: "prores",
157+
browserHostile: true,
158+
representativeMime: null,
159+
hasAlpha: true,
160+
});
161+
});
162+
163+
it("returns null (never throws) when ffprobe is unresolvable", async () => {
164+
const project = tmpProject();
165+
const videoPath = join(project, "clip.mp4");
166+
writeFileSync(videoPath, "fake video bytes");
167+
process.env.HYPERFRAMES_FFPROBE_PATH = join(project, "missing-ffprobe");
168+
169+
await expect(
170+
probeAssetCodec(videoPath, makeRunner({ [videoPath]: "hevc" })),
171+
).resolves.toBeNull();
172+
});
173+
});
174+
175+
describe("decideMediaProxyEligibility", () => {
176+
it("allows only hostile opaque video through the H.264 proxy path", () => {
177+
expect(
178+
decideMediaProxyEligibility({
179+
codecName: "hevc",
180+
browserHostile: true,
181+
representativeMime: null,
182+
hasAlpha: false,
183+
}),
184+
).toEqual({ eligible: true });
185+
});
186+
187+
it("rejects alpha and browser-safe sources before transcoding", () => {
188+
expect(
189+
decideMediaProxyEligibility({
190+
codecName: "prores",
191+
browserHostile: true,
192+
representativeMime: null,
193+
hasAlpha: true,
194+
}),
195+
).toEqual({ eligible: false, reason: "alpha_source" });
196+
expect(
197+
decideMediaProxyEligibility({
198+
codecName: "h264",
199+
browserHostile: false,
200+
representativeMime: null,
201+
hasAlpha: false,
202+
}),
203+
).toEqual({ eligible: false, reason: "browser_safe_codec" });
204+
expect(decideMediaProxyEligibility(null)).toEqual({
205+
eligible: false,
206+
reason: "unknown_codec",
207+
});
208+
});
209+
});
210+
211+
describe("scanProjectMediaCodecMap", () => {
212+
it("omits an asset from the map (no throw) when ffprobe is unresolvable", async () => {
213+
const project = tmpProject();
214+
writeFileSync(join(project, "clip.mp4"), "fake video bytes");
215+
process.env.HYPERFRAMES_FFPROBE_PATH = join(project, "missing-ffprobe");
216+
217+
const map = await scanProjectMediaCodecMap(project, [{ html: videoHtml("clip.mp4") }], {
218+
runner: makeRunner({ [join(project, "clip.mp4")]: "hevc" }),
219+
});
220+
221+
expect(map).toEqual({});
222+
});
223+
224+
it("keys the map by project-root-relative URL pathnames: decoded, forward-slash, leading-slash", async () => {
225+
const project = tmpProject();
226+
mkdirSync(join(project, "assets", "sub"), { recursive: true });
227+
writeFileSync(join(project, "assets", "sub", "clip.mp4"), "fake video bytes");
228+
writeFileSync(join(project, "assets", "my clip.mp4"), "fake video bytes");
229+
230+
const html = videoHtml("assets/sub/clip.mp4", "assets/my%20clip.mp4");
231+
const map = await scanProjectMediaCodecMap(project, [{ html }], {
232+
runner: makeRunner({
233+
[join(project, "assets", "sub", "clip.mp4")]: "hevc",
234+
[join(project, "assets", "my clip.mp4")]: "h264",
235+
}),
236+
});
237+
238+
expect(Object.keys(map)).toEqual(["/assets/sub/clip.mp4"]);
239+
expect(map["/assets/sub/clip.mp4"]?.browserHostile).toBe(true);
240+
expect(map["/assets/my clip.mp4"]).toBeUndefined();
241+
});
242+
243+
it("rewrites a sub-composition's ../-traversing src via compSrcPath before resolving (rewriteAssetPath)", async () => {
244+
const project = tmpProject();
245+
mkdirSync(join(project, "assets"), { recursive: true });
246+
mkdirSync(join(project, "compositions"), { recursive: true });
247+
writeFileSync(join(project, "assets", "clip.mp4"), "fake video bytes");
248+
249+
const map = await scanProjectMediaCodecMap(
250+
project,
251+
[
252+
{
253+
html: videoHtml("../assets/clip.mp4"),
254+
compSrcPath: "compositions/scene.html",
255+
},
256+
],
257+
{ runner: makeRunner({ [join(project, "assets", "clip.mp4")]: "hevc" }) },
258+
);
259+
260+
// The key is root-relative (what the served DOM resolves to), not the
261+
// sub-composition-relative authored src.
262+
expect(Object.keys(map)).toEqual(["/assets/clip.mp4"]);
263+
expect(map["/assets/clip.mp4"]?.browserHostile).toBe(true);
264+
});
265+
266+
it("caches by path + mtime + size, invalidating same-mtime re-exports and touched files", async () => {
267+
const project = tmpProject();
268+
const videoPath = join(project, "clip.mp4");
269+
writeFileSync(videoPath, "fake video bytes");
270+
const pinnedMtime = new Date(Date.now() - 60_000);
271+
utimesSync(videoPath, pinnedMtime, pinnedMtime);
272+
const html = videoHtml("clip.mp4");
273+
const cache = createMediaCodecProbeCache();
274+
const probe = countingRunner(makeRunner({ [videoPath]: "hevc" }));
275+
276+
const first = await scanProjectMediaCodecMap(project, [{ html }], {
277+
cache,
278+
runner: probe.runner,
279+
});
280+
expect(first["/clip.mp4"]?.codecName).toBe("hevc");
281+
expect(probe.calls()).toBe(1);
282+
283+
const second = await scanProjectMediaCodecMap(project, [{ html }], {
284+
cache,
285+
runner: probe.runner,
286+
});
287+
expect(second["/clip.mp4"]?.codecName).toBe("hevc");
288+
expect(probe.calls()).toBe(1);
289+
290+
writeFileSync(videoPath, "larger fake video bytes");
291+
utimesSync(videoPath, pinnedMtime, pinnedMtime);
292+
const resized = await scanProjectMediaCodecMap(project, [{ html }], {
293+
cache,
294+
runner: probe.runner,
295+
});
296+
expect(resized["/clip.mp4"]?.codecName).toBe("hevc");
297+
expect(probe.calls()).toBe(2);
298+
299+
const future = new Date(Date.now() + 60_000);
300+
utimesSync(videoPath, future, future);
301+
302+
const third = await scanProjectMediaCodecMap(project, [{ html }], {
303+
cache,
304+
runner: probe.runner,
305+
});
306+
expect(third["/clip.mp4"]?.codecName).toBe("hevc");
307+
expect(probe.calls()).toBe(3);
308+
});
309+
310+
it("bounds the long-lived probe cache while retaining the newest assets", async () => {
311+
const project = tmpProject();
312+
const cache = createMediaCodecProbeCache();
313+
const paths = Array.from({ length: 513 }, (_, index) => `clip-${index}.mp4`);
314+
const codecByPath: Record<string, string> = {};
315+
for (const path of paths) {
316+
const absolutePath = join(project, path);
317+
writeFileSync(absolutePath, "fake video bytes");
318+
codecByPath[absolutePath] = "hevc";
319+
}
320+
321+
await scanProjectMediaCodecMap(project, [{ html: videoHtml(...paths) }], {
322+
cache,
323+
runner: makeRunner(codecByPath),
324+
});
325+
326+
expect(cache.size).toBe(512);
327+
expect(paths.slice(0, 8).some((path) => !cache.has(join(project, path)))).toBe(true);
328+
expect(cache.has(join(project, "clip-512.mp4"))).toBe(true);
329+
});
330+
});

0 commit comments

Comments
 (0)