Skip to content

Write HTML. Render video. Built for agents.

fix: run the configured ffmpeg and ffprobe everywhere and say when an upload was not checked (#4611)

Miguel Ángel7fedc689b824
diff --git a/packages/cli/src/media-use/lib/ff-binaries.mjs b/packages/cli/src/media-use/lib/ff-binaries.mjs
new file mode 100644
index 0000000000..d6002023b2
--- /dev/null
+++ b/packages/cli/src/media-use/lib/ff-binaries.mjs
@@ -0,0 +1,37 @@
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+
+// The binaries media-use spawns: HYPERFRAMES_FFMPEG_PATH / HYPERFRAMES_FFPROBE_PATH when set, else PATH.
+// A set path that is not a working ffmpeg/ffprobe throws, so a broken override never reads as "no metadata".
+const runsByPath = new Map();
+
+export class FfBinarySettingError extends Error {}
+
+function configuredOr(name, envVar) {
+ const setting = process.env[envVar]?.trim();
+ if (!setting) return name;
+ const path = resolve(setting);
+ if (!runsByPath.has(path)) runsByPath.set(path, isWorking(path, name));
+ if (!runsByPath.get(path)) {
+ const why = `${envVar} names "${path}", which is not a working ${name}: fix it or unset it.`;
+ throw new FfBinarySettingError(why);
+ }
+ return path;
+}
+
+function isWorking(path, name) {
+ try {
+ const out = execFileSync(path, ["-version"], {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "ignore"],
+ timeout: 15000,
+ windowsHide: true,
+ });
+ return out.startsWith(`${name} version`);
+ } catch {
+ return false;
+ }
+}
+
+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 f7e0a72224..836df6e126 100644
--- a/packages/cli/src/media-use/lib/probe.mjs
+++ b/packages/cli/src/media-use/lib/probe.mjs
@@ -1,5 +1,6 @@
import { execFileSync } from "node:child_process";
import { extname } from "node:path";
+import { ffprobeBinary } from "./ff-binaries.mjs";
const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".svg", ".ico"]);
@@ -7,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(
- "ffprobe",
+ 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 d4d896cc38..fe0f39e55d 100644
--- a/packages/cli/src/media-use/lib/probe.test.mjs
+++ b/packages/cli/src/media-use/lib/probe.test.mjs
@@ -1,6 +1,6 @@
import { test } from "node:test";
import assert from "node:assert/strict";
-import { mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { chmodSync, mkdtempSync, writeFileSync, existsSync, rmSync } from "node:fs";
import { join } from "node:path";
import { tmpdir } from "node:os";
import { probe } from "./probe.mjs";
@@ -29,3 +29,120 @@ test("probe does not execute shell metacharacters in a filename", () => {
rmSync(dir, { recursive: true, force: true });
}
});
+
+test(
+ "probe runs the ffprobe HYPERFRAMES_FFPROBE_PATH names",
+ { skip: process.platform === "win32" },
+ () => {
+ const dir = mkdtempSync(join(tmpdir(), "probe-ffprobe-path-"));
+ const fake = join(dir, "fake-ffprobe");
+ writeFileSync(
+ fake,
+ `#!/bin/sh\n[ "$1" = -version ] && echo 'ffprobe version fake' && exit 0\necho '{"streams":[{"width":7,"height":3,"codec_name":"fake"}]}'\n`,
+ );
+ chmodSync(fake, 0o755);
+ const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+ process.env.HYPERFRAMES_FFPROBE_PATH = fake;
+ try {
+ assert.deepEqual(probe(join(dir, "clip.png")), {
+ duration: null,
+ width: 7,
+ height: 3,
+ codec: "fake",
+ });
+ } finally {
+ if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+ else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+ rmSync(dir, { recursive: true, force: true });
+ }
+ },
+);
+
+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;
+ }
+});
+
+test("probe refuses an HYPERFRAMES_FFPROBE_PATH that names a folder", () => {
+ const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+ process.env.HYPERFRAMES_FFPROBE_PATH = tmpdir();
+ try {
+ assert.throws(() => probe("clip.wav"), /HYPERFRAMES_FFPROBE_PATH names .*fix it or unset it/);
+ } finally {
+ if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+ else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+ }
+});
+
+function withFfprobePath(value, run) {
+ const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+ process.env.HYPERFRAMES_FFPROBE_PATH = value;
+ try {
+ return run();
+ } finally {
+ if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+ else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+ }
+}
+
+test(
+ "probe refuses a configured ffprobe that cannot start, exits with an error, or is another tool",
+ {
+ skip: process.platform === "win32",
+ },
+ () => {
+ const dir = mkdtempSync(join(tmpdir(), "probe-broken-ffprobe-"));
+ try {
+ const noInterpreter = join(dir, "no-interpreter");
+ writeFileSync(noInterpreter, "#!/nonexistent/interpreter\n");
+ const failing = join(dir, "failing");
+ writeFileSync(failing, "#!/bin/sh\nexit 3\n");
+ const otherTool = join(dir, "other-tool");
+ writeFileSync(otherTool, "#!/bin/sh\necho 'ffmpeg version 9.9'\n");
+ for (const broken of [noInterpreter, failing, otherTool]) {
+ chmodSync(broken, 0o755);
+ withFfprobePath(broken, () =>
+ assert.throws(
+ () => probe("clip.wav"),
+ /HYPERFRAMES_FFPROBE_PATH names .*fix it or unset it/,
+ ),
+ );
+ }
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+ },
+);
+
+test(
+ "probe runs a relative HYPERFRAMES_FFPROBE_PATH from the working folder, not from PATH",
+ {
+ skip: process.platform === "win32",
+ },
+ () => {
+ const dir = mkdtempSync(join(tmpdir(), "probe-relative-ffprobe-"));
+ const prevCwd = process.cwd();
+ try {
+ writeFileSync(
+ join(dir, "local-ffprobe"),
+ `#!/bin/sh\n[ "$1" = -version ] && echo 'ffprobe version fake' && exit 0\necho '{"streams":[{"width":5,"height":4,"codec_name":"local"}]}'\n`,
+ );
+ chmodSync(join(dir, "local-ffprobe"), 0o755);
+ process.chdir(dir);
+ const meta = withFfprobePath("local-ffprobe", () => probe("clip.png"));
+ assert.deepEqual(meta, { duration: null, width: 5, height: 4, codec: "local" });
+ } finally {
+ process.chdir(prevCwd);
+ rmSync(dir, { recursive: true, force: true });
+ }
+ },
+);
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 b2058780f1..d5e9416a73 100644
--- a/packages/cli/src/media-use/lib/tts-local-provider.mjs
+++ b/packages/cli/src/media-use/lib/tts-local-provider.mjs
@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
import { existsSync, statSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { ffprobeBinary } from "./ff-binaries.mjs";
import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
// Local voiceover via the packaged Kokoro-82M TTS (the `hyperframes tts` CLI),
@@ -13,10 +14,10 @@ import { resolveSpawnCommand } from "../../audio/scripts/lib/tts.mjs";
// Delegated to the hyperframes CLI (same as transcribe / remove-background), not
// re-implemented here. ffprobe reads the duration back for the ledger.
-function probeDurationSeconds(file) {
+function probeDurationSeconds(ffprobe, file) {
try {
const out = execFileSync(
- "ffprobe",
+ ffprobe,
["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", "--", file],
{ encoding: "utf8", timeout: 15000 },
);
@@ -39,6 +40,7 @@ export async function localTtsGenerate(
env = process.env,
pathExists = existsSync,
) {
+ const ffprobe = ffprobeBinary();
const outPath = join(tmpdir(), `media-use-kokoro-${process.pid}-${Date.now()}.wav`);
const argv = ["hyperframes", "tts", intent, "--output", outPath];
if (ctx?.voice) argv.push("--voice", ctx.voice);
@@ -85,7 +87,7 @@ export async function localTtsGenerate(
metadata: {
description: intent,
provider: "kokoro.local",
- duration: probeDurationSeconds(outPath),
+ duration: probeDurationSeconds(ffprobe, outPath),
provenance: { engine: "kokoro-82m", prompt: intent },
},
};
diff --git a/packages/cli/src/media-use/resolve.mjs b/packages/cli/src/media-use/resolve.mjs
index cc2a4fc955..38659996b2 100644
--- a/packages/cli/src/media-use/resolve.mjs
+++ b/packages/cli/src/media-use/resolve.mjs
@@ -33,6 +33,7 @@ import { heygenAuthMethod } from "../audio/scripts/lib/heygen.mjs";
import { buildCube, paramsFromIntent } from "./lib/cube-build.mjs";
import { validateCubeFile } from "./lib/cube-validate.mjs";
import { analyzeMediaGrade, formatMeasuredNote } from "./lib/grade-analyzer.mjs";
+import { FfBinarySettingError, ffmpegBinary, ffprobeBinary } from "./lib/ff-binaries.mjs";
import {
freezeLibraryLut,
isLibraryLutOfflineMiss,
@@ -144,7 +145,12 @@ const entity = args.entity || null;
if (args.adopt) {
const { adoptExistingAssets } = await import("./lib/adopt.mjs");
- const adopted = adoptExistingAssets(projectDir);
+ let adopted;
+ try {
+ adopted = adoptExistingAssets(projectDir);
+ } catch (err) {
+ exitError(err.message);
+ }
if (args.json) {
console.log(JSON.stringify({ ok: true, adopted: adopted.length, assets: adopted }));
} else if (adopted.length === 0) {
@@ -218,7 +224,15 @@ if (args.analyze) {
console.error(`error: --for file not found: ${mediaPath}`);
process.exit(2);
}
- const analysis = analyzeMediaGrade(mediaPath);
+ let analysis;
+ try {
+ analysis = analyzeMediaGrade(mediaPath, {
+ ffmpegPath: ffmpegBinary(),
+ ffprobePath: ffprobeBinary(),
+ });
+ } catch (err) {
+ exitError(err.message);
+ }
if (args.json) {
console.log(JSON.stringify({ ok: true, type: "grade-analysis", ...analysis }));
} else {
@@ -503,7 +517,8 @@ async function run() {
// brand stays local: no frame.md/design.md -> upsell the HyperFrames design
// flow rather than reporting a generic miss (B5).
const msg =
- providerFailure instanceof BundledSfxAssetsError
+ providerFailure instanceof BundledSfxAssetsError ||
+ providerFailure instanceof FfBinarySettingError
? providerFailure.message
: type === "brand"
? "no brand spec found — add a frame.md or design.md (colors/font/logo) to this project. Run the HyperFrames design flow to create one; brand tokens are read locally for deterministic rendering."
@@ -594,7 +609,10 @@ function mergeSmartAdjust(block) {
const mediaPath = resolve(args.for);
// Clear upfront error beats an ffmpeg "No such file" stack on a typo'd path.
if (!existsSync(mediaPath)) throw new Error(`--for file not found: ${mediaPath}`);
- const analysis = analyzeMediaGrade(mediaPath);
+ const analysis = analyzeMediaGrade(mediaPath, {
+ ffmpegPath: ffmpegBinary(),
+ ffprobePath: ffprobeBinary(),
+ });
console.error(formatMeasuredNote(mediaPath, analysis.measured));
return {
...block,
@@ -1060,21 +1078,7 @@ function runDoctor() {
checks.push(heygenAuthCheck());
}
- const ffmpegProbe = runCommand("ffmpeg", ["-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("ffprobe", ["-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({
@@ -1140,6 +1144,28 @@ 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 c06007a32e..c4cb2c25f9 100644
--- a/packages/cli/src/media-use/resolve.test.mjs
+++ b/packages/cli/src/media-use/resolve.test.mjs
@@ -514,6 +514,22 @@ test("--adopt registers existing assets/ files", () => {
cleanup();
});
+test("--adopt stops, adopting nothing, when HYPERFRAMES_FFPROBE_PATH cannot run", () => {
+ setup();
+ mkdirSync(join(tmp, "assets/bgm"), { recursive: true });
+ writeFileSync(join(tmp, "assets/bgm/track.mp3"), "fake mp3");
+
+ const result = spawnResolve(["--adopt", "--project", tmp, "--json"], {
+ env: { HYPERFRAMES_FFPROBE_PATH: join(tmp, "no-ffprobe") },
+ });
+ assert.equal(result.status, 1);
+ const report = JSON.parse(result.stdout.trim());
+ assert.equal(report.ok, false);
+ assert.match(report.error, /HYPERFRAMES_FFPROBE_PATH names .*no-ffprobe.*fix it or unset it/);
+ assert.equal(readManifest(tmp).length, 0);
+ cleanup();
+});
+
test("--adopt skips already-registered assets", () => {
setup();
mkdirSync(join(tmp, "assets/bgm"), { recursive: true });
@@ -688,6 +704,110 @@ test("--doctor --json reports dependency checks and top-level ok requires ffmpeg
assert.equal(result.status, strictOk ? 0 : 1);
});
+test("--doctor checks the ffmpeg and ffprobe that HYPERFRAMES_FFMPEG_PATH and HYPERFRAMES_FFPROBE_PATH name", () => {
+ const dir = mkdtempSync(join(tmpdir(), "mu-doctor-ff-"));
+ for (const tool of ["ffmpeg", "ffprobe"]) {
+ writeFileSync(join(dir, tool), `#!/bin/sh\necho '${tool} version 9.9-fake'\n`);
+ chmodSync(join(dir, tool), 0o755);
+ }
+ try {
+ const result = spawnResolve(["--doctor", "--json"], {
+ env: {
+ HYPERFRAMES_FFMPEG_PATH: join(dir, "ffmpeg"),
+ HYPERFRAMES_FFPROBE_PATH: join(dir, "ffprobe"),
+ },
+ });
+ const byName = new Map(JSON.parse(result.stdout.trim()).checks.map((c) => [c.name, c]));
+ for (const tool of ["ffmpeg", "ffprobe"])
+ assert.deepEqual(
+ [byName.get(`${tool} on PATH`).ok, byName.get(`${tool} on PATH`).detail],
+ [true, `${tool} version 9.9-fake`],
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+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 is not a working ffprobe: 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.equal(result.status, 1);
+ const report = JSON.parse(result.stdout.trim());
+ assert.equal(report.ok, false);
+ assert.match(
+ report.error,
+ /HYPERFRAMES_FFPROBE_PATH names ".*mu-analyze-no-ffprobe.*fix it or unset it/,
+ );
+});
+
+test("--doctor fails a configured ffprobe that exists but exits with an error", () => {
+ const dir = mkdtempSync(join(tmpdir(), "mu-doctor-bad-ff-"));
+ const broken = join(dir, "ffprobe");
+ writeFileSync(broken, "#!/bin/sh\nexit 3\n");
+ chmodSync(broken, 0o755);
+ try {
+ const result = spawnResolve(["--doctor", "--json"], {
+ env: { HYPERFRAMES_FFPROBE_PATH: broken },
+ });
+ const check = JSON.parse(result.stdout.trim()).checks.find((c) => c.name === "ffprobe on PATH");
+ assert.deepEqual(
+ [check.ok, check.detail, check.fix],
+ [
+ false,
+ `HYPERFRAMES_FFPROBE_PATH names "${broken}", which is not a working ffprobe: fix it or unset it.`,
+ "fix or unset that variable",
+ ],
+ );
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("a broken HYPERFRAMES_FFPROBE_PATH is named when local voice cannot run, not a generic miss", () => {
+ setup();
+ const missing = join(tmp, "no-ffprobe");
+ const result = spawnResolve(
+ [
+ "--type",
+ "voice",
+ "--intent",
+ "hello",
+ "--provider",
+ "kokoro.local",
+ "--project",
+ tmp,
+ "--json",
+ ],
+ { env: { HYPERFRAMES_FFPROBE_PATH: missing } },
+ );
+ assert.equal(result.status, 1);
+ assert.equal(
+ JSON.parse(result.stdout.trim()).error,
+ `HYPERFRAMES_FFPROBE_PATH names "${missing}", which is not a working ffprobe: fix it or unset it.`,
+ );
+ cleanup();
+});
+
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
new file mode 100644
index 0000000000..0f73cdf3ba
--- /dev/null
+++ b/packages/producer/src/services/distributed/shared.ffmpegVersion.test.ts
@@ -0,0 +1,34 @@
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { readFfmpegVersion } from "./shared.js";
+
+describe.skipIf(process.platform === "win32")("readFfmpegVersion", () => {
+ const configured = process.env.HYPERFRAMES_FFMPEG_PATH;
+ let dir: string;
+ afterEach(() => {
+ if (configured === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH;
+ else process.env.HYPERFRAMES_FFMPEG_PATH = configured;
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ it("reads the ffmpeg that HYPERFRAMES_FFMPEG_PATH names", async () => {
+ dir = mkdtempSync(join(tmpdir(), "hf-ffmpeg-version-"));
+ const fake = join(dir, "ffmpeg");
+ writeFileSync(fake, "#!/bin/sh\necho 'ffmpeg version 9.9-fake'\n");
+ chmodSync(fake, 0o755);
+ process.env.HYPERFRAMES_FFMPEG_PATH = fake;
+
+ expect(await readFfmpegVersion()).toBe("ffmpeg version 9.9-fake");
+ });
+
+ it("names the configured binary and the setting when it is missing", async () => {
+ dir = mkdtempSync(join(tmpdir(), "hf-ffmpeg-version-"));
+ process.env.HYPERFRAMES_FFMPEG_PATH = join(dir, "no-ffmpeg-here");
+
+ 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 eec68cd248..70ccf4005d 100644
--- a/packages/producer/src/services/distributed/shared.ts
+++ b/packages/producer/src/services/distributed/shared.ts
@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { type Fps } from "@hyperframes/core";
import {
+ getFfmpegBinary,
MIXED_AUDIO_FILENAME,
type VideoElement,
type VideoFrameFormat,
@@ -323,7 +324,7 @@ const execFile = promisify(execFileCallback);
* same process (Cloud Run Jobs, Temporal activity workers) would otherwise
* spawn ffmpeg once per chunk just to read the version — ~20-50ms each.
*/
-let cachedFfmpegVersion: string | null = null;
+const cachedFfmpegVersions = new Map<string, string>();
/**
* Read `ffmpeg -version` first line. The string is opaque — `planHash`
@@ -332,23 +333,36 @@ let cachedFfmpegVersion: string | null = null;
* disagree with the plan's baked-in encoder args.
*/
export async function readFfmpegVersion(): Promise<string> {
- if (cachedFfmpegVersion !== null) return cachedFfmpegVersion;
- const { stdout } = await execFile("ffmpeg", ["-version"], {
- maxBuffer: 1024 * 1024,
- // See runFfmpeg.ts: keeps a console window off the user's desktop on Windows.
- windowsHide: true,
- });
+ const binary = getFfmpegBinary();
+ const cached = cachedFfmpegVersions.get(binary);
+ if (cached !== undefined) return cached;
+ let stdout: string;
+ try {
+ ({ stdout } = await execFile(binary, ["-version"], {
+ maxBuffer: 1024 * 1024,
+ // See runFfmpeg.ts: keeps a console window off the user's desktop on Windows.
+ windowsHide: true,
+ }));
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+ 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() ?? "";
if (!firstLine) {
throw new Error("ffmpeg -version returned empty output");
}
- cachedFfmpegVersion = firstLine;
+ cachedFfmpegVersions.set(binary, firstLine);
return firstLine;
}
/** Test-only: clear the cached ffmpeg version so a fresh probe runs. */
function _resetFfmpegVersionCacheForTests(): void {
- cachedFfmpegVersion = null;
+ cachedFfmpegVersions.clear();
}
/**
diff --git a/packages/studio-server/src/helpers/mediaValidation.test.ts b/packages/studio-server/src/helpers/mediaValidation.test.ts
index 02c3210f39..eab235ba8a 100644
--- a/packages/studio-server/src/helpers/mediaValidation.test.ts
+++ b/packages/studio-server/src/helpers/mediaValidation.test.ts
@@ -1,4 +1,7 @@
-import { describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, describe, expect, it, vi } from "vitest";
import { validateUploadedMedia, validateUploadedMediaBuffer } from "./mediaValidation.js";
describe("validateUploadedMedia", () => {
@@ -19,7 +22,7 @@ describe("validateUploadedMedia", () => {
expect(validateUploadedMedia("/tmp/test.mp4", runner)).toEqual({ ok: true });
expect(runner).toHaveBeenCalledWith(
- "ffprobe",
+ expect.stringMatching(/ffprobe/),
expect.any(Array),
expect.objectContaining({ windowsHide: true }),
);
@@ -45,7 +48,7 @@ describe("validateUploadedMedia", () => {
).toEqual({ ok: true });
});
- it("does not block upload when ffprobe is unavailable", () => {
+ it("accepts the upload but says it was not checked when ffprobe is unavailable", () => {
expect(
validateUploadedMedia("/tmp/test.mp4", () => ({
status: null,
@@ -53,7 +56,41 @@ describe("validateUploadedMedia", () => {
stderr: "",
error: { code: "ENOENT" } as NodeJS.ErrnoException,
})),
- ).toEqual({ ok: true });
+ ).toEqual({ ok: true, unchecked: expect.stringMatching(/ffprobe was not found/) });
+ });
+
+ describe("with HYPERFRAMES_FFPROBE_PATH", () => {
+ const configured = process.env.HYPERFRAMES_FFPROBE_PATH;
+ const dir = mkdtempSync(join(tmpdir(), "hf-ffprobe-path-"));
+ afterEach(() => {
+ if (configured === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+ else process.env.HYPERFRAMES_FFPROBE_PATH = configured;
+ });
+ afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+ it("runs the ffprobe it names", () => {
+ const ffprobe = join(dir, "ffprobe");
+ writeFileSync(ffprobe, "");
+ process.env.HYPERFRAMES_FFPROBE_PATH = ffprobe;
+ const runner = vi.fn(() => ({
+ status: 0,
+ stdout: JSON.stringify({ streams: [{ codec_type: "video" }] }),
+ stderr: "",
+ }));
+
+ expect(validateUploadedMedia("/tmp/test.mp4", runner)).toEqual({ ok: true });
+ expect(runner).toHaveBeenCalledWith(ffprobe, expect.any(Array), expect.anything());
+ });
+
+ 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: 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 4a302ea96c..01c29980dd 100644
--- a/packages/studio-server/src/helpers/mediaValidation.ts
+++ b/packages/studio-server/src/helpers/mediaValidation.ts
@@ -2,6 +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 { 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;
@@ -17,33 +18,49 @@ type FfprobeRunner = (
error?: NodeJS.ErrnoException;
};
+type MediaCheck = { ok: true; unchecked?: string } | { ok: false; reason: string };
+
+const defaultRunner = spawnSync as unknown as FfprobeRunner;
+const FFPROBE_MISSING =
+ "not checked: ffprobe was not found. Install FFmpeg or set HYPERFRAMES_FFPROBE_PATH.";
+
export function validateUploadedMedia(
filePath: string,
- runner: FfprobeRunner = spawnSync as unknown as FfprobeRunner,
-): { ok: true } | { ok: false; reason: string } {
+ runner: FfprobeRunner = defaultRunner,
+): MediaCheck {
const isVideo = VIDEO_EXT.test(filePath);
const isAudio = AUDIO_EXT.test(filePath);
if (!isVideo && !isAudio) {
return { ok: true };
}
+ const ffprobe = findFfBinary("ffprobe") ?? (runner === defaultRunner ? undefined : "ffprobe");
+ if (!ffprobe) return { ok: true, unchecked: FFPROBE_MISSING };
const result = runner(
- "ffprobe",
+ ffprobe,
["-v", "error", "-show_entries", "stream=codec_type", "-of", "json", "--", filePath],
{ windowsHide: true },
);
+ if (result.error && process.env[FFPROBE_PATH_ENV]?.trim()) {
+ return {
+ ok: false,
+ reason: `${FFPROBE_PATH_ENV} names "${ffprobe}", which cannot run: fix it or unset it`,
+ };
+ }
if (result.error?.code === "ENOENT") {
- return { ok: true };
+ return { ok: true, unchecked: FFPROBE_MISSING };
}
if (result.status !== 0) {
return { ok: false, reason: "ffprobe failed to read the media file" };
}
+ return checkStreams(String(result.stdout || "{}"), isVideo, isAudio);
+}
+
+function checkStreams(stdout: string, isVideo: boolean, isAudio: boolean): MediaCheck {
try {
- const parsed = JSON.parse(String(result.stdout || "{}")) as {
- streams?: Array<{ codec_type?: string }>;
- };
+ const parsed = JSON.parse(stdout) as { streams?: Array<{ codec_type?: string }> };
const streams = parsed.streams ?? [];
const hasVideo = streams.some((stream) => stream.codec_type === "video");
const hasAudio = streams.some((stream) => stream.codec_type === "audio");
@@ -63,8 +80,8 @@ export function validateUploadedMedia(
export function validateUploadedMediaBuffer(
fileName: string,
buffer: Uint8Array,
- runner: FfprobeRunner = spawnSync as unknown as FfprobeRunner,
-): { ok: true } | { ok: false; reason: string } {
+ runner: FfprobeRunner = defaultRunner,
+): MediaCheck {
const tempDir = mkdtempSync(join(tmpdir(), "hyperframes-upload-"));
const tempPath = join(tempDir, basename(fileName));
diff --git a/packages/studio-server/src/routes/files.ts b/packages/studio-server/src/routes/files.ts
index 5079f9b53d..f789b8290e 100644
--- a/packages/studio-server/src/routes/files.ts
+++ b/packages/studio-server/src/routes/files.ts
@@ -2227,11 +2227,13 @@ async function processUploadedFiles(
uploaded: string[];
skipped: string[];
invalid: Array<{ name: string; reason: string }>;
+ unchecked: Array<{ name: string; reason: string }>;
}> {
const MAX_UPLOAD_BYTES = 500 * 1024 * 1024; // 500 MB per file
const uploaded: string[] = [];
const skipped: string[] = [];
const invalid: Array<{ name: string; reason: string }> = [];
+ const unchecked: Array<{ name: string; reason: string }> = [];
// @types/node v25 narrows the ambient `FormData.entries()` to
// `[string, string]` in workspaces where another dep declares an
@@ -2326,12 +2328,13 @@ async function processUploadedFiles(
}
const relativePath = subDir ? join(subDir, finalName) : finalName;
uploaded.push(relativePath);
+ if (validation.unchecked) unchecked.push({ name: finalName, reason: validation.unchecked });
if (isAudioFile(finalName)) {
generateWaveformCache(projectDir, relativePath).catch(() => {});
}
}
- return { uploaded, skipped, invalid };
+ return { uploaded, skipped, invalid, unchecked };
}
// ── Route registration ──────────────────────────────────────────────────────
@@ -3258,7 +3261,13 @@ export function registerFileRoutes(api: Hono, adapter: StudioApiAdapter): void {
const result = await processUploadedFiles(formData, targetDir, project.dir);
return c.json(
- { ok: true, files: result.uploaded, skipped: result.skipped, invalid: result.invalid },
+ {
+ ok: true,
+ files: result.uploaded,
+ skipped: result.skipped,
+ invalid: result.invalid,
+ unchecked: result.unchecked,
+ },
201,
);
},
diff --git a/packages/studio/src/hooks/useFileManager.projectOwnership.test.tsx b/packages/studio/src/hooks/useFileManager.projectOwnership.test.tsx
index f78886f5ce..dd5e04c4a1 100644
--- a/packages/studio/src/hooks/useFileManager.projectOwnership.test.tsx
+++ b/packages/studio/src/hooks/useFileManager.projectOwnership.test.tsx
@@ -31,19 +31,19 @@ import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
-function useTestFileManager(projectId: string) {
+function useTestFileManager(projectId: string, showToast = vi.fn()) {
return useFileManager({
projectId,
- showToast: vi.fn(),
+ showToast,
recordEdit: vi.fn(async () => {}),
setRefreshKey: vi.fn(),
});
}
-async function mountTestFileManager(projectId = "project-a") {
+async function mountTestFileManager(projectId = "project-a", showToast = vi.fn()) {
const captured: { manager: ReturnType<typeof useFileManager> | null } = { manager: null };
function Probe() {
- captured.manager = useTestFileManager(projectId);
+ captured.manager = useTestFileManager(projectId, showToast);
return null;
}
const root = createRoot(document.createElement("div"));
@@ -237,3 +237,50 @@ describe("useFileManager project ownership", () => {
await act(async () => root.unmount());
});
});
+
+describe("useFileManager uploads", () => {
+ afterEach(() => vi.unstubAllGlobals());
+
+ async function uploadClip(response: Record<string, unknown>) {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async () =>
+ Response.json(
+ { ok: true, files: [], skipped: [], invalid: [], ...response },
+ { status: 201 },
+ ),
+ ),
+ );
+ const showToast = vi.fn();
+ const { manager, root } = await mountTestFileManager("project-a", showToast);
+ const added = await act(() => manager.uploadProjectFiles([new File(["x"], "clip.mp4")]));
+ await act(async () => 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");
+ });
+
+ it("says why each upload was not added", async () => {
+ const { added, showToast } = await uploadClip({
+ invalid: [
+ { name: "clip.mp4", reason: "no supported video stream found" },
+ { name: "song.mp3", reason: "no supported audio stream found" },
+ ],
+ });
+
+ expect(added).toEqual([]);
+ expect(showToast).toHaveBeenCalledWith(
+ "Not added: clip.mp4 (no supported video stream found), song.mp3 (no supported audio stream found)",
+ );
+ });
+});
diff --git a/packages/studio/src/hooks/useFileManager.ts b/packages/studio/src/hooks/useFileManager.ts
index 9010ffb175..d96aa535fd 100644
--- a/packages/studio/src/hooks/useFileManager.ts
+++ b/packages/studio/src/hooks/useFileManager.ts
@@ -210,8 +210,14 @@ export function useFileManager({
showToast(`Skipped (too large): ${data.skipped.join(", ")}`);
}
if (data.invalid?.length) {
- const names = data.invalid.map((entry: { name: string }) => entry.name).join(", ");
- showToast(`Unsupported media skipped: ${names}`);
+ const why = data.invalid
+ .map((entry: { name: string; reason: string }) => `${entry.name} (${entry.reason})`)
+ .join(", ");
+ showToast(`Not added: ${why}`);
+ }
+ if (data.unchecked?.length) {
+ const names = data.unchecked.map((entry: { name: string }) => entry.name).join(", ");
+ showToast(`Added ${names}, ${data.unchecked[0].reason}`, "info");
}
await refreshFileTree();
setRefreshKey((k) => k + 1);