Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.mjsnew file mode 100644index 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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 ffmpegassert.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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 fileconst 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.tsxindex 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.tsindex 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);