From 0eba8d6a06aafae286f9cbb784a121d1669d84a3 Mon Sep 17 00:00:00 2001
From: miga-heygen <miguel.sierra_miga@heygen.com>
Date: Fri, 2 Oct 2026 11:54:30 +0000
Subject: [PATCH] fix(cli): route FFmpeg exec-failure hint through
 getFFmpegInstallHint() (#3877)

* fix(cli): route FFmpeg exec-failure hint through getFFmpegInstallHint()

checkFFmpeg()'s "cannot start" branch (binary found but fails to run
-version) hardcoded a Windows/DLL-flavored install hint on every
platform instead of delegating to the already platform-aware
getFFmpegInstallHint() used by every other branch in this file.

* test(cli): pin the ffmpeg cannot-start hint through the async probe mock

* fix(cli): keep the runtime-DLL cannot-start hint on Windows

---------

Co-authored-by: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
---
 packages/cli/src/browser/preflight.test.ts | 32 +++++++++++++++++++++-
 packages/cli/src/browser/preflight.ts      |  5 +++-
 2 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/packages/cli/src/browser/preflight.test.ts b/packages/cli/src/browser/preflight.test.ts
index fa55b8c79d..13ef3a2b32 100644
--- a/packages/cli/src/browser/preflight.test.ts
+++ b/packages/cli/src/browser/preflight.test.ts
@@ -162,10 +162,40 @@ describe("runEnvironmentChecks", () => {
     });
     expect(ffmpeg?.detail).toContain(process.execPath);
     expect(ffmpeg?.detail).toContain("3221225781");
-    expect(ffmpeg?.hint).toContain("working 64-bit FFmpeg build");
     expect(result.ffmpegPath).toBeUndefined();
   });
 
+  // Windows DLL advice only on Windows; elsewhere the platform install hint.
+  describe("FFmpeg cannot-start hint is platform-specific", () => {
+    const realPlatform = process.platform;
+
+    afterEach(() => {
+      Object.defineProperty(process, "platform", { value: realPlatform, configurable: true });
+    });
+
+    it.each([
+      { platform: "darwin" as const, expectedHint: "brew install ffmpeg" },
+      { platform: "sunos" as const, expectedHint: "https://ffmpeg.org/download.html" },
+      {
+        platform: "win32" as const,
+        expectedHint: "Install a working 64-bit FFmpeg build with all required runtime DLLs.",
+      },
+    ])("gives the $platform cannot-start hint", async ({ platform, expectedHint }) => {
+      Object.defineProperty(process, "platform", { value: platform, configurable: true });
+      runProcess.mockImplementation((binaryPath: string) => {
+        if (binaryPath !== process.env.HYPERFRAMES_FFMPEG_PATH)
+          return Promise.resolve({ stdout: "ffprobe version 7.1.1\n", stderr: "" });
+        throw Object.assign(new Error("cannot execute binary file"), { status: 126 });
+      });
+
+      const result = await runEnvironmentChecks();
+      const ffmpeg = result.outcomes.find((outcome) => outcome.name === "FFmpeg");
+
+      expect(ffmpeg?.title).toBe("FFmpeg cannot start");
+      expect(ffmpeg?.hint).toBe(expectedHint);
+    });
+  });
+
   it("validates an explicit browser path without needing browser discovery", async () => {
     const result = await runEnvironmentChecks({
       includeBrowser: true,
diff --git a/packages/cli/src/browser/preflight.ts b/packages/cli/src/browser/preflight.ts
index 40afdc2f09..d706192baa 100644
--- a/packages/cli/src/browser/preflight.ts
+++ b/packages/cli/src/browser/preflight.ts
@@ -122,7 +122,10 @@ async function checkFFmpeg(signal?: AbortSignal): Promise<EnvironmentCheckOutcom
         level: "error",
         title: "FFmpeg cannot start",
         detail: version.detail,
-        hint: "Install a working 64-bit FFmpeg build with all required runtime DLLs.",
+        hint:
+          process.platform === "win32"
+            ? "Install a working 64-bit FFmpeg build with all required runtime DLLs."
+            : getFFmpegInstallHint(),
         path,
       };
     }