Skip to content

Write HTML. Render video. Built for agents.

fix(parsers): find FFmpeg and FFprobe installed by the project's npm installer packages (#5434)

Miguel Ángel748cda906976
diff --git a/packages/parsers/src/ffBinaries.test.ts b/packages/parsers/src/ffBinaries.test.ts
index dbb7e36c2c..4c7c1ef4db 100644
--- a/packages/parsers/src/ffBinaries.test.ts
+++ b/packages/parsers/src/ffBinaries.test.ts
@@ -1,4 +1,13 @@
-import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import {
+ type PathLike,
+ chmodSync,
+ mkdirSync,
+ mkdtempSync,
+ realpathSync,
+ rmSync,
+ symlinkSync,
+ writeFileSync,
+} from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
@@ -173,6 +182,103 @@ describe("findFfBinary", () => {
expect(findFfBinary("ffmpeg")).toBe(projectBinary);
});
+ function installerProject(
+ name: "ffmpeg" | "ffprobe",
+ { viaInstaller = false, mode = 0o755 } = {},
+ ) {
+ const project = realpathSync(mkdtempSync(join(tmpdir(), "hf-ff-installer-")));
+ const platformPackage = `@${name}-installer/${process.platform}-${process.arch}`;
+ const packageDir = viaInstaller
+ ? join(project, "store", "node_modules", platformPackage)
+ : join(project, "node_modules", platformPackage);
+ mkdirSync(packageDir, { recursive: true });
+ writeFileSync(join(packageDir, "package.json"), "{}");
+ if (viaInstaller) {
+ const installerDir = join(project, "store", "node_modules", `@${name}-installer`, name);
+ mkdirSync(installerDir, { recursive: true });
+ writeFileSync(join(installerDir, "package.json"), "{}");
+ mkdirSync(join(project, "node_modules", `@${name}-installer`), { recursive: true });
+ symlinkSync(
+ installerDir,
+ join(project, "node_modules", `@${name}-installer`, name),
+ "junction",
+ );
+ }
+ const binary = join(packageDir, process.platform === "win32" ? `${name}.exe` : name);
+ writeFileSync(binary, "");
+ chmodSync(binary, mode);
+ return { project, binary };
+ }
+
+ async function findInProjectDir(
+ project: string,
+ name: "ffmpeg" | "ffprobe",
+ systemBinaries: string[] = [],
+ ) {
+ vi.stubEnv("HYPERFRAMES_FFMPEG_PATH", "");
+ vi.stubEnv("HYPERFRAMES_FFPROBE_PATH", "");
+ process.env.PATH = "";
+ vi.spyOn(process, "cwd").mockReturnValue(project);
+ vi.resetModules();
+ vi.doMock("node:fs", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:fs")>();
+ const existsSync = (candidate: PathLike) =>
+ systemBinaries.includes(String(candidate)) ||
+ (String(candidate).startsWith(project) && actual.existsSync(candidate));
+ return { ...actual, existsSync, default: { ...actual, existsSync } };
+ });
+ vi.doMock("node:child_process", () => {
+ const mocked = {
+ execFileSync: () => {
+ throw new Error("not found");
+ },
+ };
+ return { ...mocked, default: mocked };
+ });
+ try {
+ const { findFfBinary } = await importFresh();
+ return findFfBinary(name);
+ } finally {
+ vi.unstubAllEnvs();
+ rmSync(project, { recursive: true, force: true });
+ }
+ }
+
+ it.each(["ffmpeg", "ffprobe"] as const)(
+ "falls back to the project's @%s-installer package",
+ async (name) => {
+ const { project, binary } = installerProject(name);
+
+ expect(await findInProjectDir(project, name)).toBe(binary);
+ },
+ );
+
+ it("finds the platform package next to the installer package (pnpm layout)", async () => {
+ const { project, binary } = installerProject("ffprobe", { viaInstaller: true });
+
+ expect(await findInProjectDir(project, "ffprobe")).toBe(binary);
+ });
+
+ it.skipIf(process.platform === "win32")(
+ "prefers a system install in a common dir over the installer package",
+ async () => {
+ const { project } = installerProject("ffprobe");
+
+ expect(await findInProjectDir(project, "ffprobe", ["/usr/bin/ffprobe"])).toBe(
+ "/usr/bin/ffprobe",
+ );
+ },
+ );
+
+ it.skipIf(process.platform === "win32")(
+ "skips an installer binary that is not executable",
+ async () => {
+ const { project } = installerProject("ffprobe", { mode: 0o644 });
+
+ expect(await findInProjectDir(project, "ffprobe")).toBeUndefined();
+ },
+ );
+
it("returns undefined when the binary is nowhere, and caches the miss until cleared", async () => {
delete process.env.HYPERFRAMES_FFMPEG_PATH;
Object.defineProperty(process, "platform", { value: "linux", configurable: true });
diff --git a/packages/parsers/src/ffBinaries.ts b/packages/parsers/src/ffBinaries.ts
index b9070af16b..fdff0ecbb8 100644
--- a/packages/parsers/src/ffBinaries.ts
+++ b/packages/parsers/src/ffBinaries.ts
@@ -1,6 +1,7 @@
import { execFileSync } from "node:child_process";
import { accessSync, constants, existsSync } from "node:fs";
-import { delimiter, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { delimiter, dirname, join, resolve } from "node:path";
/**
* Shared FFmpeg/FFprobe binary resolution for every package that shells out
@@ -87,20 +88,44 @@ const COMMON_BIN_DIRS =
? []
: ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin", "/snap/bin"];
-function findInCommonDirs(name: FfBinaryName): string | undefined {
+// The npm installer package comes last: its binaries are old builds, so any system install wins.
+function findInCommonDirsOrInstallerPackage(name: FfBinaryName): string | undefined {
for (const dir of COMMON_BIN_DIRS) {
const candidate = `${dir}/${name}`;
if (existsSync(candidate)) return candidate;
}
- return undefined;
+ return findInInstallerPackage(name);
+}
+
+function binaryFileName(name: FfBinaryName): string {
+ return process.platform === "win32" ? `${name}.exe` : name;
}
function findInProjectLocalBin(name: FfBinaryName): string | undefined {
- const extension = process.platform === "win32" ? ".exe" : "";
- const candidate = resolve(".hyperframes", "bin", `${name}${extension}`);
+ const candidate = resolve(".hyperframes", "bin", binaryFileName(name));
return existsSync(candidate) ? candidate : undefined;
}
+function tryResolve(fromFile: string, request: string): string | undefined {
+ try {
+ return createRequire(fromFile).resolve(request);
+ } catch {
+ return undefined;
+ }
+}
+
+// An @ffmpeg-installer / @ffprobe-installer package reachable from the current folder, located
+// but never loaded. The platform package is resolved via the installer package first (pnpm layout).
+function findInInstallerPackage(name: FfBinaryName): string | undefined {
+ const project = resolve("package.json");
+ const platformManifest = `@${name}-installer/${process.platform}-${process.arch}/package.json`;
+ const installer = tryResolve(project, `@${name}-installer/${name}/package.json`);
+ const manifest =
+ (installer && tryResolve(installer, platformManifest)) ?? tryResolve(project, platformManifest);
+ const candidate = manifest && join(dirname(manifest), binaryFileName(name));
+ return candidate && isExecutablePathCandidate(candidate) ? candidate : undefined;
+}
+
function lookupOnSystem(name: FfBinaryName): string | undefined {
if (pathLookupCache.has(name)) return pathLookupCache.get(name);
let found: string | undefined;
@@ -124,7 +149,7 @@ function lookupOnSystem(name: FfBinaryName): string | undefined {
}
}
found ??= findInProjectLocalBin(name);
- found ??= findInCommonDirs(name);
+ found ??= findInCommonDirsOrInstallerPackage(name);
const resolved = found ? resolve(found) : undefined;
pathLookupCache.set(name, resolved);
return resolved;
@@ -144,8 +169,8 @@ export interface FindFfBinaryOptions {
/**
* Resolve an FFmpeg-family binary: env override first, then a native
* current-directory/PATH scan on Windows or `which` plus PATH scan on Unix,
- * then a project-local
- * `.hyperframes/bin`, then well-known Unix install dirs. System lookups are
+ * then a project-local `.hyperframes/bin`, then well-known Unix install dirs, then an
+ * `@ffmpeg-installer`/`@ffprobe-installer` package reachable from the current folder. System lookups are
* cached per binary for the process lifetime; the env override is re-read on
* every call.
*/