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

@@ -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,

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