@hyperframes/engine 0.6.93 → 0.6.95

package/src/services/systemMemory.test.ts

@@ -1,5 +1,95 @@
-import { describe, it, expect } from "vitest";
-import { isLowMemorySystem, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
+import { afterEach, beforeEach, describe, it, expect, vi } from "vitest";
+import {
+  _resetCgroupLimitCacheForTests,
+  isLowMemorySystem,
+  LOW_MEMORY_TOTAL_MB_THRESHOLD,
+  parseCgroupLimitMb,
+} from "./systemMemory.js";
+
+const BYTES_PER_MIB = 1024 * 1024;
+const CGROUP_V2_MEMORY_MAX_PATH = "/sys/fs/cgroup/memory.max";
+const CGROUP_V1_MEMORY_LIMIT_PATH = "/sys/fs/cgroup/memory/memory.limit_in_bytes";
+
+type SystemMemoryModule = typeof import("./systemMemory.js");
+
+type MockSystemMemoryOptions = {
+  files?: Record<string, string>;
+  hostTotalMb?: number;
+  platform?: NodeJS.Platform;
+  readErrors?: Record<string, NodeJS.ErrnoException>;
+  onRead?: (path: string) => void;
+  throwOnFileRead?: boolean;
+};
+
+function stubPlatform(platform: NodeJS.Platform): () => void {
+  const descriptor = Object.getOwnPropertyDescriptor(process, "platform");
+  Object.defineProperty(process, "platform", { value: platform });
+
+  return () => {
+    if (descriptor) {
+      Object.defineProperty(process, "platform", descriptor);
+    }
+  };
+}
+
+async function withSystemMemoryMocks(
+  options: MockSystemMemoryOptions,
+  run: (systemMemory: SystemMemoryModule) => void | Promise<void>,
+): Promise<void> {
+  const {
+    files = {},
+    hostTotalMb = 32768,
+    platform = "linux",
+    readErrors = {},
+    onRead,
+    throwOnFileRead = false,
+  } = options;
+  const restorePlatform = stubPlatform(platform);
+
+  vi.resetModules();
+  vi.doMock("os", () => ({
+    totalmem: () => hostTotalMb * BYTES_PER_MIB,
+  }));
+  vi.doMock("fs", () => ({
+    readFileSync: (path: string) => {
+      onRead?.(path);
+
+      if (throwOnFileRead) {
+        throw new Error(`/sys read should not happen: ${path}`);
+      }
+
+      if (path in readErrors) {
+        throw readErrors[path];
+      }
+
+      if (path in files) {
+        return files[path];
+      }
+
+      throw Object.assign(new Error("missing cgroup file"), { code: "ENOENT" });
+    },
+  }));
+
+  try {
+    const systemMemory = await import("./systemMemory.js");
+    systemMemory._resetCgroupLimitCacheForTests();
+    await run(systemMemory);
+  } finally {
+    vi.doUnmock("fs");
+    vi.doUnmock("os");
+    vi.resetModules();
+    restorePlatform();
+  }
+}
+
+beforeEach(() => {
+  _resetCgroupLimitCacheForTests();
+});
+
+afterEach(() => {
+  _resetCgroupLimitCacheForTests();
+  vi.restoreAllMocks();
+});
 
 describe("isLowMemorySystem", () => {
   it("treats sub-threshold RAM as low-memory", () => {
@@ -20,4 +110,215 @@ describe("isLowMemorySystem", () => {
     expect(isLowMemorySystem(16384)).toBe(false);
     expect(isLowMemorySystem(65536)).toBe(false);
   });
+
+  it("treats a 4 GiB cgroup v2 limit on a 32 GiB host as low-memory", async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V2_MEMORY_MAX_PATH]: `${4096 * BYTES_PER_MIB}`,
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(4096);
+        expect(isLowMemorySystem()).toBe(true);
+      },
+    );
+  });
+});
+
+describe("parseCgroupLimitMb", () => {
+  it("parses cgroup v2 numeric limits", () => {
+    expect(parseCgroupLimitMb(`${4096 * BYTES_PER_MIB}`, null)).toBe(4096);
+  });
+
+  it('ignores cgroup v2 "max" limits', () => {
+    expect(parseCgroupLimitMb("max", null)).toBeNull();
+  });
+
+  it("parses cgroup v1 numeric limits and ignores no-limit sentinels", () => {
+    expect(parseCgroupLimitMb(null, `${6144 * BYTES_PER_MIB}`)).toBe(6144);
+    expect(parseCgroupLimitMb(null, "9223372036854771712")).toBeNull();
+  });
+
+  it("ignores absent and malformed limits", () => {
+    expect(parseCgroupLimitMb(null, null)).toBeNull();
+
+    for (const content of ["", "garbage", "-1", "0"]) {
+      expect(parseCgroupLimitMb(content, null)).toBeNull();
+      expect(parseCgroupLimitMb(null, content)).toBeNull();
+    }
+  });
+
+  it("uses cgroup v2 when both v2 and v1 contents are present", () => {
+    expect(parseCgroupLimitMb(`${4096 * BYTES_PER_MIB}`, `${2048 * BYTES_PER_MIB}`)).toBe(4096);
+  });
+});
+
+describe("getSystemTotalMb", () => {
+  it("caches cgroup probes until the test reset hook clears the cache", async () => {
+    const readCalls: string[] = [];
+    const files = {
+      [CGROUP_V2_MEMORY_MAX_PATH]: `${4096 * BYTES_PER_MIB}`,
+    };
+
+    await withSystemMemoryMocks(
+      {
+        files,
+        onRead: (path) => readCalls.push(path),
+      },
+      ({ _resetCgroupLimitCacheForTests, getSystemTotalMb }) => {
+        expect(getSystemTotalMb()).toBe(4096);
+        expect(getSystemTotalMb()).toBe(4096);
+        expect(readCalls).toEqual([CGROUP_V2_MEMORY_MAX_PATH]);
+
+        files[CGROUP_V2_MEMORY_MAX_PATH] = `${2048 * BYTES_PER_MIB}`;
+        _resetCgroupLimitCacheForTests();
+
+        expect(getSystemTotalMb()).toBe(2048);
+        expect(readCalls).toEqual([CGROUP_V2_MEMORY_MAX_PATH, CGROUP_V2_MEMORY_MAX_PATH]);
+      },
+    );
+  });
+
+  it('uses the host total when cgroup v2 reports "max"', async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V2_MEMORY_MAX_PATH]: "max",
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+      },
+    );
+  });
+
+  it("honors cgroup v1 numeric limits when cgroup v2 is absent", async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V1_MEMORY_LIMIT_PATH]: `${6144 * BYTES_PER_MIB}`,
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(6144);
+        expect(isLowMemorySystem()).toBe(true);
+      },
+    );
+  });
+
+  it("uses the host total when cgroup v1 reports a no-limit sentinel", async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V1_MEMORY_LIMIT_PATH]: "9223372036854771712",
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+      },
+    );
+  });
+
+  it("uses the host total when cgroup files are absent", async () => {
+    await withSystemMemoryMocks({}, ({ getSystemTotalMb, isLowMemorySystem }) => {
+      expect(getSystemTotalMb()).toBe(32768);
+      expect(isLowMemorySystem()).toBe(false);
+    });
+  });
+
+  it("warns once and uses the host total when a cgroup file is unreadable", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await withSystemMemoryMocks(
+      {
+        readErrors: {
+          [CGROUP_V2_MEMORY_MAX_PATH]: Object.assign(new Error("permission denied"), {
+            code: "EACCES",
+          }),
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+        expect(warn).toHaveBeenCalledTimes(1);
+        expect(warn.mock.calls[0]?.[0]).toContain(
+          "[SystemMemory] Unable to read cgroup memory limit",
+        );
+        expect(warn.mock.calls[0]?.[0]).toContain("EACCES");
+      },
+    );
+  });
+
+  it("stays silent when cgroup files are absent", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    await withSystemMemoryMocks({}, ({ getSystemTotalMb }) => {
+      expect(getSystemTotalMb()).toBe(32768);
+      expect(getSystemTotalMb()).toBe(32768);
+      expect(warn).not.toHaveBeenCalled();
+    });
+  });
+
+  it.each(["", "garbage", "-1", "0"])(
+    "uses the host total for malformed cgroup v2 content %j",
+    async (content) => {
+      await withSystemMemoryMocks(
+        {
+          files: {
+            [CGROUP_V2_MEMORY_MAX_PATH]: content,
+          },
+        },
+        ({ getSystemTotalMb, isLowMemorySystem }) => {
+          expect(getSystemTotalMb()).toBe(32768);
+          expect(isLowMemorySystem()).toBe(false);
+        },
+      );
+    },
+  );
+
+  it.each(["", "garbage", "-1", "0"])(
+    "uses the host total for malformed cgroup v1 content %j",
+    async (content) => {
+      await withSystemMemoryMocks(
+        {
+          files: {
+            [CGROUP_V1_MEMORY_LIMIT_PATH]: content,
+          },
+        },
+        ({ getSystemTotalMb, isLowMemorySystem }) => {
+          expect(getSystemTotalMb()).toBe(32768);
+          expect(isLowMemorySystem()).toBe(false);
+        },
+      );
+    },
+  );
+
+  it("uses the host total when a cgroup limit is larger than host RAM", async () => {
+    await withSystemMemoryMocks(
+      {
+        files: {
+          [CGROUP_V2_MEMORY_MAX_PATH]: `${65536 * BYTES_PER_MIB}`,
+        },
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+      },
+    );
+  });
+
+  it("does not read cgroup files on non-Linux platforms", async () => {
+    await withSystemMemoryMocks(
+      {
+        platform: "darwin",
+        throwOnFileRead: true,
+      },
+      ({ getSystemTotalMb, isLowMemorySystem }) => {
+        expect(getSystemTotalMb()).toBe(32768);
+        expect(isLowMemorySystem()).toBe(false);
+      },
+    );
+  });
 });

package/src/services/systemMemory.ts

@@ -8,11 +8,140 @@
  * it lives here once instead of being re-derived inline.
  */
 
+import { readFileSync } from "fs";
 import { totalmem } from "os";
 
+const BYTES_PER_MIB = 1024 * 1024;
+const BYTES_PER_MIB_BIGINT = BigInt(BYTES_PER_MIB);
+// These are the paths as seen from INSIDE a container, where the runtime
+// mounts the container's own cgroup at the namespace root — the case this
+// probe exists for. They are deliberately not resolved via /proc/self/cgroup:
+// on a bare host under systemd the process's real limit may live in a nested
+// slice (e.g. /sys/fs/cgroup/user.slice/.../memory.max) that these root paths
+// don't see, and that's acceptable — bare hosts are covered by total-RAM
+// detection, and chasing nested slices adds fragility for no container gain.
+const CGROUP_V2_MEMORY_MAX_PATH = "/sys/fs/cgroup/memory.max";
+const CGROUP_V1_MEMORY_LIMIT_PATH = "/sys/fs/cgroup/memory/memory.limit_in_bytes";
+// Kernel no-limit sentinel is page-rounded 2^63-1 (~9223372036854771712); >= 2^60 is implausible as a real limit.
+const CGROUP_V1_NO_LIMIT_CUTOFF_BYTES = 2n ** 60n;
+
+let _cachedCgroupLimitMb: number | null | undefined;
+let _warnedCgroupReadFailure = false;
+
+/** Parse cgroup v2/v1 memory limits from sysfs file contents into MiB. */
+export function parseCgroupLimitMb(
+  v2Content: string | null,
+  v1Content: string | null,
+): number | null {
+  if (v2Content !== null) {
+    return parseCgroupV2LimitMb(v2Content);
+  }
+
+  return parseCgroupV1LimitMb(v1Content);
+}
+
+function parseCgroupV2LimitMb(content: string): number | null {
+  const trimmed = content.trim();
+  if (trimmed === "max") {
+    return null;
+  }
+
+  return parsePositiveByteLimitMb(trimmed);
+}
+
+function parseCgroupV1LimitMb(content: string | null): number | null {
+  if (content === null) {
+    return null;
+  }
+
+  return parsePositiveByteLimitMb(content.trim(), CGROUP_V1_NO_LIMIT_CUTOFF_BYTES);
+}
+
+function parsePositiveByteLimitMb(content: string, noLimitCutoffBytes?: bigint): number | null {
+  if (!/^\d+$/.test(content)) {
+    return null;
+  }
+
+  const bytes = BigInt(content);
+  if (bytes <= 0n) {
+    return null;
+  }
+
+  if (noLimitCutoffBytes !== undefined && bytes >= noLimitCutoffBytes) {
+    return null;
+  }
+
+  return Number(bytes / BYTES_PER_MIB_BIGINT);
+}
+
+/** Test-only: reset the cached cgroup memory probe. */
+export function _resetCgroupLimitCacheForTests(): void {
+  _cachedCgroupLimitMb = undefined;
+  _warnedCgroupReadFailure = false;
+}
+
+function getCgroupLimitMb(): number | null {
+  if (_cachedCgroupLimitMb !== undefined) return _cachedCgroupLimitMb;
+
+  if (process.platform !== "linux") {
+    _cachedCgroupLimitMb = null;
+    return null;
+  }
+
+  const v2Content = readCgroupFile(CGROUP_V2_MEMORY_MAX_PATH);
+  const v1Content = v2Content === null ? readCgroupFile(CGROUP_V1_MEMORY_LIMIT_PATH) : null;
+
+  _cachedCgroupLimitMb = parseCgroupLimitMb(v2Content, v1Content);
+  if (_cachedCgroupLimitMb !== null) {
+    console.info(
+      `[SystemMemory] cgroup memory limit detected: ${_cachedCgroupLimitMb} MiB — ` +
+        `it governs memory-adaptive render behaviour instead of host RAM.`,
+    );
+  }
+  return _cachedCgroupLimitMb;
+}
+
+function readCgroupFile(path: string): string | null {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    const code = getErrorCode(error);
+    if (code !== "ENOENT" && code !== "ENOTDIR") {
+      warnCgroupReadFailure(path, error);
+    }
+    return null;
+  }
+}
+
+function getErrorCode(error: unknown): string | undefined {
+  if (typeof error !== "object" || error === null || !("code" in error)) {
+    return undefined;
+  }
+
+  return typeof error.code === "string" ? error.code : undefined;
+}
+
+function formatCgroupReadError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = getErrorCode(error);
+  return code ? `${code}: ${message}` : message;
+}
+
+function warnCgroupReadFailure(path: string, error: unknown): void {
+  if (_warnedCgroupReadFailure) return;
+  _warnedCgroupReadFailure = true;
+  console.warn(
+    `[SystemMemory] Unable to read cgroup memory limit at ${path} ` +
+      `(${formatCgroupReadError(error)}); falling back to host RAM.`,
+  );
+}
+
 /** Total physical RAM in MiB. */
 export function getSystemTotalMb(): number {
-  return Math.floor(totalmem() / (1024 * 1024));
+  const hostTotalMb = Math.floor(totalmem() / BYTES_PER_MIB);
+  const cgroupLimitMb = getCgroupLimitMb();
+
+  return cgroupLimitMb === null ? hostTotalMb : Math.min(hostTotalMb, cgroupLimitMb);
 }
 
 /**
@@ -38,14 +167,13 @@ export const LOW_MEMORY_TOTAL_MB_THRESHOLD = 8192;
  * survive". Accepts an explicit `totalMb` so callers (and tests) can pass
  * a known value instead of re-probing.
  *
- * Caveat: `os.totalmem()` reports the *host's* physical RAM, not a
- * cgroup/container memory limit. A 4 GB container on a 32 GB host will not
- * auto-flag as low-memory, and an 8 GB container on a 64 GB host won't
- * either. Containerised and serverless callers (Docker `--docker` renders,
- * Lambda) that want a specific profile should set `PRODUCER_LOW_MEMORY_MODE`
- * explicitly rather than relying on auto-detection. Hosts whose *total* RAM
- * is genuinely <= the threshold (laptops, small VMs, small Lambda tiers) are
- * detected correctly regardless of container nesting.
+ * Caveat: Linux cgroup v1/v2 memory limits are consulted when readable, so
+ * Docker and serverless runtimes, including Lambda tiers with readable cgroup
+ * ceilings, inherit the tighter container limit instead of the host's physical
+ * RAM. Environments that hide cgroup files should set
+ * `PRODUCER_LOW_MEMORY_MODE` explicitly rather than relying on auto-detection.
+ * Hosts whose *effective* total RAM is genuinely <= the threshold (laptops,
+ * small VMs, small Lambda tiers, small containers) are detected correctly.
  */
 export function isLowMemorySystem(totalMb: number = getSystemTotalMb()): boolean {
   return totalMb <= LOW_MEMORY_TOTAL_MB_THRESHOLD;

package/src/services/videoFrameExtractor.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file unused-class-member code-duplication complexity
 /**
  * Video Frame Extractor Service
  *
@@ -19,6 +20,7 @@ import {
 } from "../utils/hdr.js";
 import { downloadToTemp, isHttpUrl } from "../utils/urlDownloader.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
+import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import {
@@ -259,7 +261,7 @@ export async function extractVideoFramesRange(
   args.push("-y", outputPattern);
 
   return new Promise((resolve, reject) => {
-    const ffmpeg = spawn("ffmpeg", args);
+    const ffmpeg = spawn(getFfmpegBinary(), args);
     trackChildProcess(ffmpeg);
     let stderr = "";
     const onAbort = () => {

package/src/utils/ffmpegBinaries.test.ts

@@ -0,0 +1,43 @@
+// fallow-ignore-file code-duplication
+import { resolve } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  assertConfiguredFfmpegBinariesExist,
+  getFfmpegBinary,
+  getFfprobeBinary,
+} from "./ffmpegBinaries.js";
+
+describe("ffmpeg binary env resolution", () => {
+  const originalFfmpegPath = process.env.HYPERFRAMES_FFMPEG_PATH;
+  const originalFfprobePath = process.env.HYPERFRAMES_FFPROBE_PATH;
+
+  afterEach(() => {
+    if (originalFfmpegPath === undefined) delete process.env.HYPERFRAMES_FFMPEG_PATH;
+    else process.env.HYPERFRAMES_FFMPEG_PATH = originalFfmpegPath;
+    if (originalFfprobePath === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    else process.env.HYPERFRAMES_FFPROBE_PATH = originalFfprobePath;
+  });
+
+  it("uses configured absolute paths when env vars are set", () => {
+    process.env.HYPERFRAMES_FFMPEG_PATH = "/tools/ffmpeg.exe";
+    process.env.HYPERFRAMES_FFPROBE_PATH = "/tools/ffprobe.exe";
+
+    expect(getFfmpegBinary()).toBe(resolve("/tools/ffmpeg.exe"));
+    expect(getFfprobeBinary()).toBe(resolve("/tools/ffprobe.exe"));
+  });
+
+  it("throws a clear error when a configured FFmpeg path is missing", () => {
+    process.env.HYPERFRAMES_FFMPEG_PATH = "/missing/ffmpeg.exe";
+
+    expect(() => assertConfiguredFfmpegBinariesExist()).toThrow(
+      /FFmpeg binary not found at HYPERFRAMES_FFMPEG_PATH/,
+    );
+  });
+
+  it("accepts existing configured paths", () => {
+    process.env.HYPERFRAMES_FFMPEG_PATH = process.execPath;
+    process.env.HYPERFRAMES_FFPROBE_PATH = process.execPath;
+
+    expect(() => assertConfiguredFfmpegBinariesExist()).not.toThrow();
+  });
+});

package/src/utils/ffmpegBinaries.ts

@@ -0,0 +1,63 @@
+// fallow-ignore-file code-duplication
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { resolve } from "path";
+
+export const FFMPEG_PATH_ENV = "HYPERFRAMES_FFMPEG_PATH";
+export const FFPROBE_PATH_ENV = "HYPERFRAMES_FFPROBE_PATH";
+
+const pathCache = new Map<string, string | undefined>();
+
+function findOnPath(name: "ffmpeg" | "ffprobe"): string | undefined {
+  if (pathCache.has(name)) return pathCache.get(name);
+  try {
+    const command = process.platform === "win32" ? "where" : "which";
+    const output = execFileSync(command, [name], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    });
+    const first = output
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .find(Boolean);
+    const resolved = first ? resolve(first) : undefined;
+    pathCache.set(name, resolved);
+    return resolved;
+  } catch {
+    pathCache.set(name, undefined);
+    return undefined;
+  }
+}
+
+function getConfiguredBinary(envName: string, binaryName: "ffmpeg" | "ffprobe"): string {
+  const configured = process.env[envName]?.trim();
+  if (configured) return resolve(configured);
+  return findOnPath(binaryName) ?? binaryName;
+}
+
+export function getFfmpegBinary(): string {
+  return getConfiguredBinary(FFMPEG_PATH_ENV, "ffmpeg");
+}
+
+export function getFfprobeBinary(): string {
+  return getConfiguredBinary(FFPROBE_PATH_ENV, "ffprobe");
+}
+
+export function assertConfiguredFfmpegBinariesExist(): void {
+  const ffmpegPath = process.env[FFMPEG_PATH_ENV]?.trim();
+  if (ffmpegPath && !existsSync(ffmpegPath)) {
+    throw new Error(
+      `[FFmpeg] FFmpeg binary not found at ${FFMPEG_PATH_ENV}="${ffmpegPath}". ` +
+        "Install FFmpeg or unset the override.",
+    );
+  }
+
+  const ffprobePath = process.env[FFPROBE_PATH_ENV]?.trim();
+  if (ffprobePath && !existsSync(ffprobePath)) {
+    throw new Error(
+      `[FFmpeg] FFprobe binary not found at ${FFPROBE_PATH_ENV}="${ffprobePath}". ` +
+        "Install FFmpeg or unset the override.",
+    );
+  }
+}

package/src/utils/ffprobe.test.ts

@@ -1,3 +1,4 @@
+// fallow-ignore-file code-duplication
 import { EventEmitter } from "events";
 import { readFileSync } from "fs";
 import { resolve } from "path";
@@ -164,9 +165,35 @@ function createSpawnSpy(outcomes: SpawnOutcome[]): {
 }
 
 describe("ffprobe missing-binary fallback", () => {
+  const originalFfprobePath = process.env.HYPERFRAMES_FFPROBE_PATH;
+
   afterEach(() => {
     vi.resetModules();
     vi.doUnmock("child_process");
+    if (originalFfprobePath === undefined) delete process.env.HYPERFRAMES_FFPROBE_PATH;
+    else process.env.HYPERFRAMES_FFPROBE_PATH = originalFfprobePath;
+  });
+
+  it("spawns the configured absolute FFprobe path when HYPERFRAMES_FFPROBE_PATH is set", async () => {
+    process.env.HYPERFRAMES_FFPROBE_PATH = "/tools/ffprobe.exe";
+    const { spawn, calls } = createSpawnSpy([
+      {
+        kind: "exit",
+        code: 0,
+        stdout: JSON.stringify({
+          streams: [{ codec_type: "audio", codec_name: "aac", sample_rate: "48000", channels: 2 }],
+          format: { duration: "1.25", bit_rate: "128000" },
+        }),
+      },
+    ]);
+    vi.resetModules();
+    vi.doMock("child_process", () => ({ spawn }));
+
+    const { extractAudioMetadata } = await import("./ffprobe.js");
+    const meta = await extractAudioMetadata("/tmp/uses-configured-ffprobe.wav");
+
+    expect(meta.durationSeconds).toBe(1.25);
+    expect(calls[0]?.command).toBe(resolve("/tools/ffprobe.exe"));
   });
 
   it("extractMediaMetadata falls back to PNG cICP metadata when ffprobe is missing", async () => {

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);
       }