Skip to content

Commit bf7f6de

Browse files
fix(cli): check warns when a video's browser-playable copy cannot be made (#5441)
* fix(cli): check warns when a video's browser-playable copy cannot be made * fix(cli): big projects stop failing proxy prep, and a failed copy is reported once * fix(cli): proxy failures name the real ffmpeg error, and a broken ffmpeg is reported once * chore(studio-server): shorten the batch proxy resolver doc comment
1 parent 489036c commit bf7f6de

6 files changed

Lines changed: 374 additions & 60 deletions

File tree

‎packages/cli/src/utils/checkBrowser.test.ts‎

Lines changed: 126 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import {
1313
captureOverviewShot,
1414
keepBrokenImageAborts,
1515
preResolveHostileMediaProxies,
16+
dropFailedProxyEchoes,
1617
runBrowserCheck,
1718
collectSeekClock,
1819
} from "./checkBrowser.js";
@@ -21,7 +22,9 @@ import type { ProjectDir } from "./project.js";
2122
const mocks = vi.hoisted(() => ({
2223
bundleWithLocalizedFonts: vi.fn(async () => "<html></html>"),
2324
serverClose: vi.fn(async () => undefined),
24-
resolveProxy: vi.fn<(projectDir: string, absoluteSourcePath: string) => Promise<string>>(),
25+
resolveProxy:
26+
vi.fn<(projectDir: string, absoluteSourcePath: string, variant?: string) => Promise<string>>(),
27+
FfmpegUnavailableError: class FfmpegUnavailableError extends Error {},
2528
scanProjectMediaCodecMap: vi.fn<
2629
(...args: unknown[]) => Promise<
2730
Record<
@@ -75,7 +78,11 @@ vi.mock("@hyperframes/studio-server/media-codec-map", async (importOriginal) =>
7578
proxyVariantFor: (facts: { hasAlpha?: boolean }) => (facts.hasAlpha ? "vp8" : "h264"),
7679
}));
7780
vi.mock("@hyperframes/studio-server/proxy-transcoder", () => ({
78-
resolveProxy: mocks.resolveProxy,
81+
FfmpegUnavailableError: mocks.FfmpegUnavailableError,
82+
resolveProxies: (projectDir: string, sources: Array<{ sourcePath: string; variant: string }>) =>
83+
Promise.allSettled(
84+
sources.map(({ sourcePath, variant }) => mocks.resolveProxy(projectDir, sourcePath, variant)),
85+
),
7986
}));
8087

8188
const PROJECT: ProjectDir = {
@@ -361,6 +368,40 @@ it("carries validate's clip-duration audit into the runtime findings", async ()
361368
]);
362369
});
363370

371+
it("reports each video whose browser-playable copy could not be made as a warning finding", async () => {
372+
mountCanvasFixture();
373+
mocks.scanProjectMediaCodecMap.mockResolvedValue({
374+
"/media/hlg.mp4": {
375+
codecName: "hevc",
376+
browserHostile: true,
377+
representativeMime: null,
378+
hasAlpha: false,
379+
},
380+
});
381+
mocks.resolveProxy.mockRejectedValue(
382+
new Error("HDR proxying requires ffmpeg zscale/tonemap filters (libzimg)"),
383+
);
384+
vi.spyOn(console, "error").mockImplementation(() => undefined);
385+
installSessionMock(fakePage());
386+
387+
const result = await runBrowserCheck(
388+
PROJECT,
389+
{ ...DEFAULT_CHECK_OPTIONS, samples: 1, contrast: false },
390+
{ kind: "none" },
391+
runAuditGrid,
392+
);
393+
394+
expect(result.runtimeFindings).toContainEqual(
395+
expect.objectContaining({
396+
code: "media_proxy_failed",
397+
severity: "warning",
398+
message: expect.stringContaining(
399+
"media/hlg.mp4: HDR proxying requires ffmpeg zscale/tonemap filters (libzimg)",
400+
),
401+
}),
402+
);
403+
});
404+
364405
it("surfaces the runtime's media-proxy-fallback console.info line as an info finding, ignoring unrelated info logs", async () => {
365406
vi.spyOn(Date, "now").mockReturnValue(100);
366407
mountCanvasFixture();
@@ -640,6 +681,53 @@ describe("keepBrokenImageAborts", () => {
640681
});
641682
});
642683

684+
describe("dropFailedProxyEchoes", () => {
685+
it("keeps one finding for a failed proxy and drops the preview's repeats of it", () => {
686+
const at = (code: string, message: string, url?: string) =>
687+
({ code, severity: "info", message, time: 0, url }) as const;
688+
const failed = at("media_proxy_failed", "Could not make a copy of media/a.mov");
689+
const unrelated502 = at(
690+
"http_error",
691+
"502 loading media/b.mov",
692+
"http://127.0.0.1:3000/media/b.mov?hf-proxy=h264",
693+
);
694+
const originalMissing = at(
695+
"http_error",
696+
"404 loading media/a.mov",
697+
"http://127.0.0.1:3000/media/a.mov",
698+
);
699+
700+
const kept = dropFailedProxyEchoes(
701+
[
702+
failed,
703+
at(
704+
"http_error",
705+
"502 loading media/my clip.mov",
706+
"http://127.0.0.1:3000/media/my%20clip.mov?hf-proxy=h264",
707+
),
708+
at(
709+
"http_error",
710+
"502 loading media/a.mov",
711+
"http://127.0.0.1:3000/media/a.mov?hf-proxy=h264",
712+
),
713+
at(
714+
"media_proxy_fallback",
715+
'[hyperframes] runtime_media_proxy_fallback: "media/a.mov" uses a codec (prores)',
716+
),
717+
at(
718+
"media_proxy_unavailable",
719+
'[hyperframes] runtime_media_proxy_unavailable: "http://127.0.0.1:3000/media/a.mov" (proxy_playback_failed): x',
720+
),
721+
unrelated502,
722+
originalMissing,
723+
],
724+
new Set(["/media/a.mov", "/media/my clip.mov"]),
725+
);
726+
727+
expect(kept).toEqual([failed, unrelated502, originalMissing]);
728+
});
729+
});
730+
643731
describe("preResolveHostileMediaProxies", () => {
644732
const dirs: string[] = [];
645733
const mkProjectDir = (): string => {
@@ -708,7 +796,7 @@ describe("preResolveHostileMediaProxies", () => {
708796
expect(mocks.resolveProxy).not.toHaveBeenCalled();
709797
});
710798

711-
it("swallows a resolveProxy rejection instead of throwing", async () => {
799+
it("returns a resolveProxy rejection as a warning instead of throwing", async () => {
712800
const projectDir = mkProjectDir();
713801
mocks.scanProjectMediaCodecMap.mockResolvedValue({
714802
"/clip.mp4": {
@@ -721,14 +809,42 @@ describe("preResolveHostileMediaProxies", () => {
721809
mocks.resolveProxy.mockRejectedValue(new Error("ffmpeg exited with code 1"));
722810
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
723811

724-
await expect(
725-
preResolveHostileMediaProxies(projectDir, "<html></html>"),
726-
).resolves.toBeUndefined();
812+
await expect(preResolveHostileMediaProxies(projectDir, "<html></html>")).resolves.toEqual({
813+
findings: [
814+
expect.objectContaining({
815+
code: "media_proxy_failed",
816+
severity: "warning",
817+
message: expect.stringContaining("clip.mp4: ffmpeg exited with code 1"),
818+
}),
819+
],
820+
failedPaths: new Set(["/clip.mp4"]),
821+
});
727822
expect(errorSpy).toHaveBeenCalledWith(
728823
expect.stringContaining("media proxy pre-resolve: 0/1 ready, 1 failed"),
729824
);
730825
});
731826

827+
it("reports an unusable ffmpeg once for every video, without promising a working render", async () => {
828+
const projectDir = mkProjectDir();
829+
const hevc = {
830+
codecName: "hevc",
831+
browserHostile: true,
832+
representativeMime: null,
833+
hasAlpha: false,
834+
};
835+
mocks.scanProjectMediaCodecMap.mockResolvedValue({ "/a.mp4": hevc, "/b.mp4": hevc });
836+
mocks.resolveProxy.mockRejectedValue(
837+
new mocks.FfmpegUnavailableError("ffmpeg binary not found"),
838+
);
839+
vi.spyOn(console, "error").mockImplementation(() => undefined);
840+
841+
const { findings } = await preResolveHostileMediaProxies(projectDir, "<html></html>");
842+
843+
expect(findings).toHaveLength(1);
844+
expect(findings[0]?.message).toContain("copies of a.mp4, b.mp4: ffmpeg binary not found");
845+
expect(findings[0]?.message).not.toContain("render");
846+
});
847+
732848
// `check --json` stdout must stay pure JSON, so these lines belong on stderr.
733849
it("writes the pre-resolve summary to stderr and leaves stdout untouched", async () => {
734850
const projectDir = mkProjectDir();
@@ -766,9 +882,10 @@ describe("preResolveHostileMediaProxies", () => {
766882
const infoSpy = vi.spyOn(console, "info").mockImplementation(() => undefined);
767883
const stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
768884

769-
await expect(
770-
preResolveHostileMediaProxies(projectDir, "<html></html>"),
771-
).resolves.toBeUndefined();
885+
await expect(preResolveHostileMediaProxies(projectDir, "<html></html>")).resolves.toEqual({
886+
findings: [],
887+
failedPaths: new Set(),
888+
});
772889

773890
expect(errorSpy).toHaveBeenCalledWith(
774891
"[hyperframes] media proxy pre-resolve: scan failed (ffprobe not found)",

‎packages/cli/src/utils/checkBrowser.ts‎

Lines changed: 100 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,10 @@ import {
2929
proxyVariantFor,
3030
scanProjectMediaCodecMap,
3131
} from "@hyperframes/studio-server/media-codec-map";
32-
import { resolveProxy } from "@hyperframes/studio-server/proxy-transcoder";
32+
import {
33+
FfmpegUnavailableError,
34+
resolveProxies,
35+
} from "@hyperframes/studio-server/proxy-transcoder";
3336
import { rectToBbox } from "./checkTypes.js";
3437
import type {
3538
AnchoredLayoutIssue,
@@ -110,43 +113,75 @@ interface FinishedContrast {
110113
* hostile-asset check (e.g. a fresh CI checkout) would race the timeout
111114
* instead of paying a bounded one-time transcode cost
112115
* (docs/plans/2026-07-14-002-feat-transparent-media-proxies-plan.md, unit U4).
113-
* Best-effort: a probe or transcode failure does not fail `check`; one summary
114-
* line records the pre-resolve outcome before the runtime attempts playback.
116+
* A failed copy is a warning, not an error: a default render decodes the original with
117+
* ffmpeg. One warning per failed file, or one for all of them when ffmpeg itself is unusable.
115118
*/
116119
export async function preResolveHostileMediaProxies(
117120
projectDir: string,
118121
html: string,
119122
autoProxyOverride?: boolean,
120-
): Promise<void> {
121-
if (!resolveAutoProxy(projectDir, autoProxyOverride)) return;
123+
): Promise<ProxyPreResolution> {
124+
const none: ProxyPreResolution = { findings: [], failedPaths: new Set() };
125+
if (!resolveAutoProxy(projectDir, autoProxyOverride)) return none;
122126
let codecMap: Awaited<ReturnType<typeof scanProjectMediaCodecMap>>;
123127
try {
124128
codecMap = await scanProjectMediaCodecMap(projectDir, [{ html }]);
125129
} catch (err) {
126130
console.error(
127131
`[hyperframes] media proxy pre-resolve: scan failed (${normalizeErrorMessage(err)})`,
128132
);
129-
return;
133+
return none;
130134
}
131135
const hostileEntries = Object.entries(codecMap).filter(
132136
([, facts]) => decideMediaProxyEligibility(facts).eligible,
133137
);
134-
if (hostileEntries.length === 0) return;
138+
if (hostileEntries.length === 0) return none;
135139

136140
const startedAt = Date.now();
137-
const results = await Promise.allSettled(
138-
hostileEntries.map(([pathname, facts]) =>
139-
resolveProxy(
140-
projectDir,
141-
resolve(projectDir, pathname.replace(/^\/+/, "")),
142-
proxyVariantFor(facts),
143-
),
144-
),
145-
);
146-
const failed = results.filter((result) => result.status === "rejected").length;
141+
const sources = hostileEntries.map(([pathname, facts]) => {
142+
const file = pathname.replace(/^\/+/, "");
143+
return {
144+
pathname,
145+
file,
146+
sourcePath: resolve(projectDir, file),
147+
variant: proxyVariantFor(facts),
148+
};
149+
});
150+
const results = await resolveProxies(projectDir, sources);
151+
const failures = sources.flatMap((source, index) => {
152+
const result = results[index]!;
153+
return result.status === "rejected" ? [{ ...source, reason: result.reason }] : [];
154+
});
155+
const total = hostileEntries.length;
147156
console.error(
148-
`[hyperframes] media proxy pre-resolve: ${results.length - failed}/${results.length} ready, ${failed} failed (${Date.now() - startedAt}ms)`,
157+
`[hyperframes] media proxy pre-resolve: ${total - failures.length}/${total} ready, ${failures.length} failed (${Date.now() - startedAt}ms)`,
149158
);
159+
const unusableFfmpeg = failures.filter(({ reason }) => reason instanceof FfmpegUnavailableError);
160+
const findings = failures
161+
.filter(({ reason }) => !(reason instanceof FfmpegUnavailableError))
162+
.map(({ file, reason }) =>
163+
proxyFailedDraft(
164+
`Could not make a browser-playable copy of ${file}: ${normalizeErrorMessage(reason)}. A default render decodes the original with ffmpeg and does not need it, but publish stops on it (unless run with --no-proxy) and a browser that cannot decode the original will not play it in preview.`,
165+
),
166+
);
167+
if (unusableFfmpeg[0]) {
168+
findings.unshift(
169+
proxyFailedDraft(
170+
`Could not make browser-playable copies of ${unusableFfmpeg.map(({ file }) => file).join(", ")}: ${normalizeErrorMessage(unusableFfmpeg[0].reason)}. Publish stops on them (unless run with --no-proxy) and a browser that cannot decode them will not play them in preview.`,
171+
),
172+
);
173+
}
174+
return { findings, failedPaths: new Set(failures.map(({ pathname }) => pathname)) };
175+
}
176+
177+
interface ProxyPreResolution {
178+
findings: RuntimeDraft[];
179+
/** Root-relative paths of the videos whose copy failed. */
180+
failedPaths: Set<string>;
181+
}
182+
183+
function proxyFailedDraft(message: string): RuntimeDraft {
184+
return { code: "media_proxy_failed", severity: "warning", message, time: 0 };
150185
}
151186

152187
export async function runBrowserCheck(
@@ -157,15 +192,18 @@ export async function runBrowserCheck(
157192
): Promise<CheckBrowserResult> {
158193
const { bundleWithLocalizedFonts } = await import("./bundleWithLocalizedFonts.js");
159194
const html = await bundleWithLocalizedFonts(project.dir);
160-
await preResolveHostileMediaProxies(project.dir, html, options.autoProxy);
195+
const { findings: drafts, failedPaths } = await preResolveHostileMediaProxies(
196+
project.dir,
197+
html,
198+
options.autoProxy,
199+
);
161200
const server = await serveStaticProjectHtml(
162201
project.dir,
163202
html,
164203
"Failed to bind check server",
165204
[],
166205
options.autoProxy,
167206
);
168-
const drafts: RuntimeDraft[] = [];
169207
let currentTime = 0;
170208
let chromeBrowser: import("puppeteer-core").Browser | undefined;
171209

@@ -201,9 +239,10 @@ export async function runBrowserCheck(
201239
return {
202240
...result,
203241
timings: { ...result.timings, launchSettleMs },
204-
runtimeFindings: keepBrokenImageAborts(drafts, broken).map((draft) =>
205-
runtimeFinding(draft, rootAnchor),
206-
),
242+
runtimeFindings: dropFailedProxyEchoes(
243+
keepBrokenImageAborts(drafts, broken),
244+
failedPaths,
245+
).map((draft) => runtimeFinding(draft, rootAnchor)),
207246
};
208247
} finally {
209248
await chromeBrowser?.close().catch(() => undefined);
@@ -377,6 +416,44 @@ export function keepBrokenImageAborts(drafts: RuntimeDraft[], broken: Set<string
377416
return drafts.filter((draft) => !draft.abortedImage || broken.has(draft.url ?? ""));
378417
}
379418

419+
/** One finding per failed proxy: the preview's own 502s and swap notes for that file repeat `media_proxy_failed`. */
420+
export function dropFailedProxyEchoes(
421+
drafts: RuntimeDraft[],
422+
failedPaths: ReadonlySet<string>,
423+
): RuntimeDraft[] {
424+
if (failedPaths.size === 0) return drafts;
425+
return drafts.filter((draft) => !failedPaths.has(proxyEchoPath(draft) ?? ""));
426+
}
427+
428+
function proxyEchoPath(draft: RuntimeDraft): string | undefined {
429+
if (draft.code === "http_error" || draft.code === "request_failed") {
430+
const url = parseUrl(draft.url);
431+
return url?.searchParams.has("hf-proxy") ? decodedPath(url) : undefined;
432+
}
433+
if (draft.code === "media_proxy_fallback" || draft.code === "media_proxy_unavailable") {
434+
return decodedPath(parseUrl(/"([^"]+)"/.exec(draft.message)?.[1]));
435+
}
436+
return undefined;
437+
}
438+
439+
function parseUrl(target: string | undefined): URL | undefined {
440+
if (!target) return undefined;
441+
try {
442+
return new URL(target, "http://check.invalid/");
443+
} catch {
444+
return undefined;
445+
}
446+
}
447+
448+
function decodedPath(url: URL | undefined): string | undefined {
449+
if (!url) return undefined;
450+
try {
451+
return decodeURIComponent(url.pathname);
452+
} catch {
453+
return undefined;
454+
}
455+
}
456+
380457
const IMAGE_DECODE_CAP_MS = 5000;
381458

382459
async function abortedImagesStillBroken(page: Page, drafts: RuntimeDraft[]): Promise<Set<string>> {

0 commit comments

Comments
 (0)