@hyperframes/engine 0.6.93 → 0.6.94

package/src/utils/ffprobe.ts

@@ -1,11 +1,14 @@
+// fallow-ignore-file code-duplication complexity
 import { spawn } from "child_process";
 import { readFileSync } from "fs";
 import { extname } from "path";
+import { FFPROBE_PATH_ENV, getFfprobeBinary } from "./ffmpegBinaries.js";
 
 /** Spawn ffprobe with given args, return stdout. Throws on non-zero exit or missing binary. */
 function runFfprobe(args: string[]): Promise<string> {
   return new Promise((resolve, reject) => {
-    const proc = spawn("ffprobe", args);
+    const command = getFfprobeBinary();
+    const proc = spawn(command, args);
     let stdout = "";
     let stderr = "";
     proc.stdout.on("data", (data) => {
@@ -23,7 +26,14 @@ function runFfprobe(args: string[]): Promise<string> {
     });
     proc.on("error", (err) => {
       if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-        reject(new Error("[FFmpeg] ffprobe not found. Please install FFmpeg."));
+        const configured = process.env[FFPROBE_PATH_ENV]?.trim();
+        reject(
+          new Error(
+            configured
+              ? `[FFmpeg] ffprobe not found at ${FFPROBE_PATH_ENV}="${configured}". Please install FFmpeg.`
+              : "[FFmpeg] ffprobe not found. Please install FFmpeg.",
+          ),
+        );
       } else {
         reject(err);
       }

package/src/utils/gpuEncoder.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file complexity
 /**
  * GPU Encoder Detection
  *
@@ -6,6 +7,7 @@
  */
 
 import { spawn } from "child_process";
+import { getFfmpegBinary } from "./ffmpegBinaries.js";
 
 export type ConcreteGpuEncoder = "nvenc" | "videotoolbox" | "vaapi" | "qsv" | "amf";
 export type GpuEncoder = ConcreteGpuEncoder | null;
@@ -59,7 +61,7 @@ export async function selectUsableGpuEncoder(
 
 export async function detectGpuEncoder(): Promise<GpuEncoder> {
   return new Promise((resolve) => {
-    const ffmpeg = spawn("ffmpeg", ["-encoders"], {
+    const ffmpeg = spawn(getFfmpegBinary(), ["-encoders"], {
       stdio: ["pipe", "pipe", "pipe"],
     });
     let stdout = "";
@@ -147,7 +149,7 @@ async function canUseGpuEncoder(encoder: ConcreteGpuEncoder): Promise<boolean> {
       if (killTimer) clearTimeout(killTimer);
       resolve(usable);
     };
-    const ffmpeg = spawn("ffmpeg", getProbeArgs(encoder), {
+    const ffmpeg = spawn(getFfmpegBinary(), getProbeArgs(encoder), {
       stdio: ["ignore", "ignore", "pipe"],
     });
 

package/src/utils/runFfmpeg.test.ts

@@ -1,8 +1,16 @@
-import { describe, expect, it } from "vitest";
+import { EventEmitter } from "node:events";
+import { resolve } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
 
 import { formatFfmpegError } from "./runFfmpeg.js";
 
 describe("formatFfmpegError", () => {
+  const originalPlatform = process.platform;
+
+  afterEach(() => {
+    Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
+  });
+
   it("reports exit code alone when stderr is empty", () => {
     expect(formatFfmpegError(-22, "")).toBe("FFmpeg exited with code -22");
   });
@@ -43,4 +51,52 @@ describe("formatFfmpegError", () => {
   it("wraps stderr in [FFmpeg] prefix when exit code is null (spawn failure)", () => {
     expect(formatFfmpegError(null, "spawn ffmpeg ENOENT")).toBe("[FFmpeg] spawn ffmpeg ENOENT");
   });
+
+  it("maps Windows invalid-image exit codes to an actionable architecture hint", () => {
+    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+
+    expect(formatFfmpegError(3221225595, "")).toContain("wrong architecture");
+  });
+});
+
+function createSpawnSpy() {
+  const calls: Array<{ command: string; args: string[] }> = [];
+  const spawn = vi.fn((command: string, args: string[]) => {
+    calls.push({ command, args });
+    const proc = new EventEmitter() as EventEmitter & {
+      stderr: EventEmitter;
+      kill: ReturnType<typeof vi.fn>;
+      killed: boolean;
+    };
+    proc.stderr = new EventEmitter();
+    proc.kill = vi.fn();
+    proc.killed = false;
+    process.nextTick(() => proc.emit("close", 0));
+    return proc;
+  });
+  return { spawn, calls };
+}
+
+describe("runFfmpeg binary resolution", () => {
+  const originalFfmpegPath = process.env.HYPERFRAMES_FFMPEG_PATH;
+
+  afterEach(() => {
+    vi.resetModules();
+    vi.doUnmock("child_process");
+    if (originalFfmpegPath === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH;
+    else process.env.HYPERFRAMES_FFMPEG_PATH = originalFfmpegPath;
+  });
+
+  it("spawns the configured absolute FFmpeg path when HYPERFRAMES_FFMPEG_PATH is set", async () => {
+    process.env.HYPERFRAMES_FFMPEG_PATH = "/tools/ffmpeg.exe";
+    const { spawn, calls } = createSpawnSpy();
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { runFfmpeg } = await import("./runFfmpeg.js");
+    const result = await runFfmpeg(["-version"]);
+
+    expect(result.success).toBe(true);
+    expect(calls[0]).toEqual({ command: resolve("/tools/ffmpeg.exe"), args: ["-version"] });
+  });
 });

package/src/utils/runFfmpeg.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 /**
  * Shared FFmpeg process runner.
  *
@@ -6,6 +7,7 @@
  */
 
 import { spawn } from "child_process";
+import { getFfmpegBinary } from "./ffmpegBinaries.js";
 import { trackChildProcess } from "./processTracker.js";
 
 export interface RunFfmpegOptions {
@@ -25,6 +27,23 @@ const DEFAULT_TIMEOUT = 300_000;
 
 const DEFAULT_STDERR_TAIL_LINES = 15;
 
+function formatWindowsFfmpegExit(exitCode: number | null): string | undefined {
+  if (process.platform !== "win32" || exitCode === null) return undefined;
+  if (exitCode === 3221225595 || exitCode === -1073741701) {
+    return (
+      "[FFmpeg] Windows could not start ffmpeg.exe (STATUS_INVALID_IMAGE_FORMAT). " +
+      "The binary may be corrupted or the wrong architecture. Reinstall a 64-bit Windows FFmpeg build."
+    );
+  }
+  if (exitCode === 3221225794 || exitCode === -1073741502) {
+    return (
+      "[FFmpeg] Windows failed while initializing ffmpeg.exe. " +
+      "The binary may be corrupted, blocked, or missing runtime DLLs. Reinstall a 64-bit Windows FFmpeg build."
+    );
+  }
+  return undefined;
+}
+
 /**
  * Build a user-facing error message for a failed ffmpeg invocation.
  *
@@ -48,6 +67,10 @@ export function formatFfmpegError(
   if (exitCode === null) {
     return tail ? `[FFmpeg] ${tail}` : "[FFmpeg] process error";
   }
+  const windowsMessage = formatWindowsFfmpegExit(exitCode);
+  if (windowsMessage) {
+    return tail ? `${windowsMessage}\nffmpeg stderr (tail):\n${tail}` : windowsMessage;
+  }
   return tail
     ? `FFmpeg exited with code ${exitCode}\nffmpeg stderr (tail):\n${tail}`
     : `FFmpeg exited with code ${exitCode}`;
@@ -60,7 +83,7 @@ export async function runFfmpeg(args: string[], opts?: RunFfmpegOptions): Promis
   const onStderr = opts?.onStderr;
 
   return new Promise<RunFfmpegResult>((resolve) => {
-    const ffmpeg = spawn("ffmpeg", args);
+    const ffmpeg = spawn(getFfmpegBinary(), args);
     trackChildProcess(ffmpeg);
     let stderr = "";