From d130faeb2776ba577beced1ebf7f54055528a465 Mon Sep 17 00:00:00 2001 From: Miguel Angel Simon Sierra Date: Sun, 27 Sep 2026 17:38:05 -0400 Subject: [PATCH] fix: a configured ffmpeg or ffprobe path that cannot run fails loudly --- .../cli/src/media-use/lib/ff-binaries.mjs | 18 ++++++++-- packages/cli/src/media-use/lib/probe.mjs | 3 +- packages/cli/src/media-use/lib/probe.test.mjs | 11 +++++++ .../src/media-use/lib/tts-local-provider.mjs | 3 +- packages/cli/src/media-use/resolve.mjs | 33 ++++++++++--------- packages/cli/src/media-use/resolve.test.mjs | 22 +++++++++++++ .../distributed/shared.ffmpegVersion.test.ts | 4 ++- .../src/services/distributed/shared.ts | 7 ++-- .../src/helpers/mediaValidation.test.ts | 6 ++-- .../src/helpers/mediaValidation.ts | 11 ++++--- packages/studio/src/hooks/useFileManager.ts | 2 +- .../src/hooks/useFileManager.upload.test.tsx | 33 ++++++++++++------- 12 files changed, 111 insertions(+), 42 deletions(-) diff --git a/packages/cli/src/media-use/lib/ff-binaries.mjs b/packages/cli/src/media-use/lib/ff-binaries.mjs index 84dfbf23a6..63b01c83fc 100644 --- a/packages/cli/src/media-use/lib/ff-binaries.mjs +++ b/packages/cli/src/media-use/lib/ff-binaries.mjs @@ -1,3 +1,17 @@ +import { accessSync, constants } from "node:fs"; + // The binaries media-use spawns: HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH when set, else PATH. -export const ffmpegBinary = () => process.env.HYPERFRAMES_FFMPEG_PATH?.trim() || "ffmpeg"; -export const ffprobeBinary = () => process.env.HYPERFRAMES_FFPROBE_PATH?.trim() || "ffprobe"; +// A set path that cannot run throws, so a broken override never reads as "no metadata". +function configuredOr(name, envVar) { + const path = process.env[envVar]?.trim(); + if (!path) return name; + try { + accessSync(path, constants.X_OK); + } catch { + throw new Error(`${envVar} names "${path}", which cannot run: fix it or unset it.`); + } + return path; +} + +export const ffmpegBinary = () => configuredOr("ffmpeg", "HYPERFRAMES_FFMPEG_PATH"); +export const ffprobeBinary = () => configuredOr("ffprobe", "HYPERFRAMES_FFPROBE_PATH"); diff --git a/packages/cli/src/media-use/lib/probe.mjs b/packages/cli/src/media-use/lib/probe.mjs index ddb544fc7c..836df6e126 100644 --- a/packages/cli/src/media-use/lib/probe.mjs +++ b/packages/cli/src/media-use/lib/probe.mjs @@ -8,11 +8,12 @@ export function probe(filePath) { const ext = extname(filePath).toLowerCase(); if (ext === ".svg") return { width: null, height: null, duration: null, codec: "svg" }; + const ffprobe = ffprobeBinary(); try { // execFileSync (no shell) so a hostile filename like `"; rm -rf ~; ".png` // can't break out of the quoting — filePath is passed as a literal argv entry. const raw = execFileSync( - ffprobeBinary(), + ffprobe, ["-v", "quiet", "-print_format", "json", "-show_format", "-show_streams", "--", filePath], { encoding: "utf8", timeout: 5000 }, ); diff --git a/packages/cli/src/media-use/lib/probe.test.mjs b/packages/cli/src/media-use/lib/probe.test.mjs index 52360fdaff..1be570d5a3 100644 --- a/packages/cli/src/media-use/lib/probe.test.mjs +++ b/packages/cli/src/media-use/lib/probe.test.mjs @@ -57,3 +57,14 @@ test( } }, ); + +test("probe refuses an HYPERFRAMES_FFPROBE_PATH that cannot run instead of reporting no metadata", () => { + const configured = process.env.HYPERFRAMES_FFPROBE_PATH; + process.env.HYPERFRAMES_FFPROBE_PATH = join(tmpdir(), "no-ffprobe-here", "ffprobe"); + try { + assert.throws(() => probe("clip.wav"), /HYPERFRAMES_FFPROBE_PATH names ".*no-ffprobe-here.*fix it or unset it/); + } finally { + if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH; + else process.env.HYPERFRAMES_FFPROBE_PATH = configured; + } +}); diff --git a/packages/cli/src/media-use/lib/tts-local-provider.mjs b/packages/cli/src/media-use/lib/tts-local-provider.mjs index 0944e29399..0632cc0953 100644 --- a/packages/cli/src/media-use/lib/tts-local-provider.mjs +++ b/packages/cli/src/media-use/lib/tts-local-provider.mjs @@ -15,9 +15,10 @@ import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs"; // re-implemented here. ffprobe reads the duration back for the ledger. function probeDurationSeconds(file) { + const ffprobe = ffprobeBinary(); try { const out = execFileSync( - ffprobeBinary(), + ffprobe, ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", "--", file], { encoding: "utf8", timeout: 15000 }, ); diff --git a/packages/cli/src/media-use/resolve.mjs b/packages/cli/src/media-use/resolve.mjs index 07c675ab88..4a7fcc22e8 100644 --- a/packages/cli/src/media-use/resolve.mjs +++ b/packages/cli/src/media-use/resolve.mjs @@ -1067,21 +1067,7 @@ function runDoctor() { checks.push(heygenAuthCheck()); } - const ffmpegProbe = runCommand(ffmpegBinary(), ["-version"]); - checks.push({ - name: "ffmpeg on PATH", - ok: ffmpegProbe.status === 0, - detail: ffmpegProbe.status === 0 ? firstLine(ffmpegProbe.stdout) : "ffmpeg not found", - fix: ffmpegProbe.status === 0 ? "" : "brew install ffmpeg", - }); - - const ffprobeProbe = runCommand(ffprobeBinary(), ["-version"]); - checks.push({ - name: "ffprobe on PATH", - ok: ffprobeProbe.status === 0, - detail: ffprobeProbe.status === 0 ? firstLine(ffprobeProbe.stdout) : "ffprobe not found", - fix: ffprobeProbe.status === 0 ? "" : "brew install ffmpeg", - }); + checks.push(ffDoctorCheck("ffmpeg", ffmpegBinary), ffDoctorCheck("ffprobe", ffprobeBinary)); const nodeOk = !versionLessThan(process.versions.node, MIN_NODE_VERSION); checks.push({ @@ -1147,6 +1133,23 @@ function printMap(label, values) { for (const [key, value] of entries) console.log(` ${key}: ${value}`); } +function ffDoctorCheck(name, binary) { + let bin; + try { + bin = binary(); + } catch (err) { + return { name: `${name} on PATH`, ok: false, detail: err.message, fix: "fix or unset that variable" }; + } + const probe = runCommand(bin, ["-version"]); + const ok = probe.status === 0; + return { + name: `${name} on PATH`, + ok, + detail: ok ? firstLine(probe.stdout) : `${name} not found`, + fix: ok ? "" : "brew install ffmpeg", + }; +} + function runCommand(bin, argv) { return spawnSync(bin, argv, { encoding: "utf8", diff --git a/packages/cli/src/media-use/resolve.test.mjs b/packages/cli/src/media-use/resolve.test.mjs index de65577b3c..899a7104e9 100644 --- a/packages/cli/src/media-use/resolve.test.mjs +++ b/packages/cli/src/media-use/resolve.test.mjs @@ -708,6 +708,28 @@ test("--doctor checks the ffmpeg and ffprobe that HYPERFRAMES_FFMPEG_PATH and HY } }); +test("--doctor fails a HYPERFRAMES_FFPROBE_PATH that cannot run and says to fix or unset it", () => { + const missing = join(tmpdir(), "mu-doctor-no-ffprobe", "ffprobe"); + const result = spawnResolve(["--doctor", "--json"], { env: { HYPERFRAMES_FFPROBE_PATH: missing } }); + const report = JSON.parse(result.stdout.trim()); + const check = report.checks.find((c) => c.name === "ffprobe on PATH"); + assert.equal(report.ok, false); + assert.deepEqual( + [check.ok, check.detail, check.fix], + [false, `HYPERFRAMES_FFPROBE_PATH names "${missing}", which cannot run: fix it or unset it.`, "fix or unset that variable"], + ); +}); + +test("--analyze refuses a HYPERFRAMES_FFPROBE_PATH that cannot run instead of reporting unknown", () => { + const missing = join(tmpdir(), "mu-analyze-no-ffprobe", "ffprobe"); + const result = spawnResolve(["--analyze", "--type", "grade", "--for", RESOLVE_CLI, "--json"], { + env: { HYPERFRAMES_FFPROBE_PATH: missing }, + }); + assert.notEqual(result.status, 0); + assert.match(result.stderr, /HYPERFRAMES_FFPROBE_PATH names ".*mu-analyze-no-ffprobe.*fix it or unset it/); + assert.doesNotMatch(result.stdout, /"ok":true/); +}); + test("one-line output format matches contract", () => { setup(); const record = makeRecord({ provenance: { prompt: "format test", provider: "test" } }); diff --git a/packages/producer/src/services/distributed/shared.ffmpegVersion.test.ts b/packages/producer/src/services/distributed/shared.ffmpegVersion.test.ts index cd263a5272..0f73cdf3ba 100644 --- a/packages/producer/src/services/distributed/shared.ffmpegVersion.test.ts +++ b/packages/producer/src/services/distributed/shared.ffmpegVersion.test.ts @@ -27,6 +27,8 @@ describe.skipIf(process.platform === "win32")("readFfmpegVersion", () => { dir = mkdtempSync(join(tmpdir(), "hf-ffmpeg-version-")); process.env.HYPERFRAMES_FFMPEG_PATH = join(dir, "no-ffmpeg-here"); - await expect(readFfmpegVersion()).rejects.toThrow(/no-ffmpeg-here.*HYPERFRAMES_FFMPEG_PATH/); + const failure = readFfmpegVersion(); + await expect(failure).rejects.toThrow(/no-ffmpeg-here.*HYPERFRAMES_FFMPEG_PATH/); + await expect(failure).rejects.toHaveProperty("code", "ENOENT"); }); }); diff --git a/packages/producer/src/services/distributed/shared.ts b/packages/producer/src/services/distributed/shared.ts index 0bac0a8830..70ccf4005d 100644 --- a/packages/producer/src/services/distributed/shared.ts +++ b/packages/producer/src/services/distributed/shared.ts @@ -345,8 +345,11 @@ export async function readFfmpegVersion(): Promise { })); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; - throw new Error( - `ffmpeg not found at "${binary}": install FFmpeg or set HYPERFRAMES_FFMPEG_PATH.`, + throw Object.assign( + new Error(`ffmpeg not found at "${binary}": install FFmpeg or set HYPERFRAMES_FFMPEG_PATH.`, { + cause: error, + }), + { code: "ENOENT" }, ); } const firstLine = stdout.split(/\r?\n/)[0]?.trim() ?? ""; diff --git a/packages/studio-server/src/helpers/mediaValidation.test.ts b/packages/studio-server/src/helpers/mediaValidation.test.ts index 15d6ddcc42..eab235ba8a 100644 --- a/packages/studio-server/src/helpers/mediaValidation.test.ts +++ b/packages/studio-server/src/helpers/mediaValidation.test.ts @@ -82,13 +82,13 @@ describe("validateUploadedMedia", () => { expect(runner).toHaveBeenCalledWith(ffprobe, expect.any(Array), expect.anything()); }); - it("says the upload was not checked when the ffprobe it names is missing", () => { + it("rejects the upload, naming the setting, when the ffprobe it names cannot run", () => { const missing = join(dir, "missing-ffprobe"); process.env.HYPERFRAMES_FFPROBE_PATH = missing; expect(validateUploadedMedia("/tmp/test.mp4")).toEqual({ - ok: true, - unchecked: expect.stringContaining(`not found at "${missing}"`), + ok: false, + reason: expect.stringContaining(`HYPERFRAMES_FFPROBE_PATH names "${missing}"`), }); }); }); diff --git a/packages/studio-server/src/helpers/mediaValidation.ts b/packages/studio-server/src/helpers/mediaValidation.ts index fd54368f8e..6807e638e5 100644 --- a/packages/studio-server/src/helpers/mediaValidation.ts +++ b/packages/studio-server/src/helpers/mediaValidation.ts @@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process"; import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { basename, join } from "node:path"; -import { findFfBinary } from "@hyperframes/parsers/ff-binaries"; +import { FFPROBE_PATH_ENV, findFfBinary } from "@hyperframes/parsers/ff-binaries"; const VIDEO_EXT = /\.(mp4|webm|mov|mkv|avi|m4v|mxf|mts|m2ts|ts)$/i; const AUDIO_EXT = /\.(mp3|wav|ogg|m4a|aac)$/i; @@ -42,12 +42,15 @@ export function validateUploadedMedia( { windowsHide: true }, ); - if (result.error?.code === "ENOENT") { + if (result.error && process.env[FFPROBE_PATH_ENV]?.trim()) { return { - ok: true, - unchecked: `not checked: ffprobe was not found at "${ffprobe}". Install FFmpeg or set HYPERFRAMES_FFPROBE_PATH.`, + ok: false, + reason: `${FFPROBE_PATH_ENV} names "${ffprobe}", which cannot run: fix it or unset it`, }; } + if (result.error?.code === "ENOENT") { + return { ok: true, unchecked: FFPROBE_MISSING }; + } if (result.status !== 0) { return { ok: false, reason: "ffprobe failed to read the media file" }; } diff --git a/packages/studio/src/hooks/useFileManager.ts b/packages/studio/src/hooks/useFileManager.ts index 0a74225de6..d2c7c130fd 100644 --- a/packages/studio/src/hooks/useFileManager.ts +++ b/packages/studio/src/hooks/useFileManager.ts @@ -208,7 +208,7 @@ export function useFileManager({ } if (data.invalid?.length) { const names = data.invalid.map((entry: { name: string }) => entry.name).join(", "); - showToast(`Unsupported media skipped: ${names}`); + showToast(`Not added: ${names}, ${data.invalid[0].reason}`); } if (data.unchecked?.length) { const names = data.unchecked.map((entry: { name: string }) => entry.name).join(", "); diff --git a/packages/studio/src/hooks/useFileManager.upload.test.tsx b/packages/studio/src/hooks/useFileManager.upload.test.tsx index 10f64c7df6..5a5c324f3a 100644 --- a/packages/studio/src/hooks/useFileManager.upload.test.tsx +++ b/packages/studio/src/hooks/useFileManager.upload.test.tsx @@ -33,20 +33,12 @@ afterEach(() => { vi.unstubAllGlobals(); }); -it("says which uploads were added without a media check, and why", async () => { - const reason = - "not checked: ffprobe was not found. Install FFmpeg or set HYPERFRAMES_FFPROBE_PATH."; +async function uploadClip(response: Record) { vi.stubGlobal( "fetch", vi.fn(async () => Response.json( - { - ok: true, - files: ["clip.mp4"], - skipped: [], - invalid: [], - unchecked: [{ name: "clip.mp4", reason }], - }, + { ok: true, files: [], skipped: [], invalid: [], ...response }, { status: 201 }, ), ), @@ -64,12 +56,29 @@ it("says which uploads were added without a media check, and why", async () => { } const root = createRoot(document.createElement("div")); await act(async () => root.render()); - const added = await act(() => captured.manager!.uploadProjectFiles([new File(["x"], "clip.mp4")]), ); + act(() => root.unmount()); + return { added, showToast }; +} + +it("says which uploads were added without a media check, and why", async () => { + const reason = + "not checked: ffprobe was not found. Install FFmpeg or set HYPERFRAMES_FFPROBE_PATH."; + const { added, showToast } = await uploadClip({ + files: ["clip.mp4"], + unchecked: [{ name: "clip.mp4", reason }], + }); expect(added).toEqual(["clip.mp4"]); expect(showToast).toHaveBeenCalledWith(`Added clip.mp4, ${reason}`, "info"); - act(() => root.unmount()); +}); + +it("says why an upload was not added", async () => { + const reason = 'HYPERFRAMES_FFPROBE_PATH names "/x/ffprobe", which cannot run: fix it or unset it'; + const { added, showToast } = await uploadClip({ invalid: [{ name: "clip.mp4", reason }] }); + + expect(added).toEqual([]); + expect(showToast).toHaveBeenCalledWith(`Not added: clip.mp4, ${reason}`); });