Skip to content

Commit 9efbbdf

Browse files
fix(cli): transcribe names why whisper is missing and the one line that fixes it (#7366)
* fix(cli): transcribe names why whisper is missing and the one line that fixes it * fix(cli): a Windows box gets a runnable install line and finds the whisper it just built
1 parent a3b8f52 commit 9efbbdf

2 files changed

Lines changed: 71 additions & 12 deletions

File tree

‎packages/cli/src/whisper/manager.install.test.ts‎

Lines changed: 49 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
1+
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
22
import { tmpdir } from "node:os";
3-
import { join } from "node:path";
3+
import { dirname, join } from "node:path";
44
import { afterEach, expect, it, vi } from "vitest";
55
import { ensureWhisper, findWhisper, WhisperUnavailableError } from "./manager.js";
66
const calls = vi.hoisted(() => ({ exec: vi.fn() }));
@@ -63,3 +63,50 @@ it("clones whisper.cpp inside its build dir, with no cache path on the command l
6363
rmSync(cache, { recursive: true, force: true });
6464
}
6565
});
66+
67+
it("names the missing build tool when whisper.cpp cannot be built", async () => {
68+
vi.stubEnv("HYPERFRAMES_CACHE_DIR", mkdtempSync(join(tmpdir(), "hf-whisper-cache-")));
69+
vi.resetModules();
70+
const { ensureWhisper: ensure } = await import("./manager.js");
71+
calls.exec.mockImplementation((command: string, args: string[]) => {
72+
if ((command === "which" || command === "where") && args[0] !== "git")
73+
throw new Error("not available");
74+
return `/bin/${args[0]}\n`;
75+
});
76+
await expect(ensure()).rejects.toThrow(/cannot build whisper\.cpp: cmake not found on PATH/);
77+
});
78+
79+
it("gives a Linux user one runnable line to get a working engine", async () => {
80+
vi.resetModules();
81+
vi.doMock("node:os", async (original) => ({
82+
...(await original<typeof import("node:os")>()),
83+
platform: () => "linux",
84+
}));
85+
const { getInstallInstructions } = await import("./manager.js");
86+
expect(getInstallInstructions()).toContain("sudo apt-get install -y git cmake build-essential");
87+
vi.doUnmock("node:os");
88+
});
89+
90+
it("gives a Windows user one runnable winget line, and finds a Release-built whisper-cli.exe", async () => {
91+
const cache = mkdtempSync(join(tmpdir(), "hf-whisper-cache-"));
92+
vi.stubEnv("HYPERFRAMES_CACHE_DIR", cache);
93+
vi.resetModules();
94+
vi.doMock("node:os", async (original) => ({
95+
...(await original<typeof import("node:os")>()),
96+
platform: () => "win32",
97+
}));
98+
try {
99+
const { getInstallInstructions, findWhisper } = await import("./manager.js");
100+
expect(getInstallInstructions()).toContain("winget install -e --id Kitware.CMake");
101+
calls.exec.mockImplementation(() => {
102+
throw new Error("not available");
103+
});
104+
const exe = join(cache, "whisper", "whisper.cpp", "build", "bin", "Release", "whisper-cli.exe");
105+
mkdirSync(dirname(exe), { recursive: true });
106+
writeFileSync(exe, "binary");
107+
expect(findWhisper()?.executablePath).toBe(exe);
108+
} finally {
109+
vi.doUnmock("node:os");
110+
rmSync(cache, { recursive: true, force: true });
111+
}
112+
});

‎packages/cli/src/whisper/manager.ts‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -149,9 +149,12 @@ const BUILD_DIR = hyperframesCacheDir("whisper", "whisper.cpp");
149149
const WHISPER_REPO = "https://github.com/ggml-org/whisper.cpp.git";
150150

151151
function findBuiltBinary(): WhisperResult | undefined {
152+
// Windows (Visual Studio generator) writes bin/Release/whisper-cli.exe, not bin/whisper-cli.
153+
const exe = platform() === "win32" ? ".exe" : "";
152154
for (const p of [
153-
join(BUILD_DIR, "build", "bin", "whisper-cli"),
154-
join(BUILD_DIR, "build", "whisper-cli"),
155+
join(BUILD_DIR, "build", "bin", "Release", `whisper-cli${exe}`),
156+
join(BUILD_DIR, "build", "bin", `whisper-cli${exe}`),
157+
join(BUILD_DIR, "build", `whisper-cli${exe}`),
155158
]) {
156159
if (existsSync(p)) return { executablePath: p, source: "build" };
157160
}
@@ -233,10 +236,10 @@ export function getInstallInstructions(): string {
233236
return "brew install whisper-cpp";
234237
}
235238
if (platform() === "linux") {
236-
return "Build from source: https://github.com/ggml-org/whisper.cpp#building (requires cmake and a C compiler)";
239+
return "sudo apt-get install -y git cmake build-essential (Debian/Ubuntu; other distros: git, cmake and a C compiler, see https://github.com/ggml-org/whisper.cpp#building), then re-run";
237240
}
238241
if (platform() === "win32") {
239-
return "Build with cmake: https://github.com/ggml-org/whisper.cpp#building";
242+
return 'winget install -e --id Git.Git && winget install -e --id Kitware.CMake && winget install -e --id Microsoft.VisualStudio.2022.BuildTools --override "--passive --add Microsoft.VisualStudio.Workload.VCTools", then re-run in a new terminal (or set HYPERFRAMES_WHISPER_PATH to the whisper-cli.exe in whisper-bin-x64.zip from https://github.com/ggml-org/whisper.cpp/releases)';
240243
}
241244
return "See https://github.com/ggml-org/whisper.cpp#building";
242245
}
@@ -269,6 +272,10 @@ export async function ensureWhisper(options?: {
269272
);
270273
}
271274

275+
// What each attempt hit, so the final error names the real cause instead of a bare install hint.
276+
const causes: string[] = [];
277+
const why = (err: unknown) => (err instanceof Error ? err.message : String(err)).trim();
278+
272279
// 2. Try brew (macOS, fastest — pre-built bottle)
273280
if (platform() === "darwin" && hasBrew()) {
274281
options?.onProgress?.("Installing whisper-cpp via Homebrew...");
@@ -280,8 +287,8 @@ export async function ensureWhisper(options?: {
280287
});
281288
const installed = findFromSystem();
282289
if (installed) return { ...installed, source: "brew" };
283-
} catch {
284-
// brew failed — fall through
290+
} catch (err) {
291+
causes.push(`brew install whisper-cpp failed: ${why(err)}`);
285292
}
286293
signal?.throwIfAborted();
287294
}
@@ -290,14 +297,19 @@ export async function ensureWhisper(options?: {
290297
if (hasGit() && hasCmake()) {
291298
try {
292299
return await buildFromSource(options?.onProgress, signal);
293-
} catch {
294-
// build failed — fall through
300+
} catch (err) {
301+
causes.push(why(err));
295302
}
296303
signal?.throwIfAborted();
304+
} else {
305+
const missing = [!hasGit() && "git", !hasCmake() && "cmake"].filter(Boolean).join(" and ");
306+
causes.push(`cannot build whisper.cpp: ${missing} not found on PATH`);
297307
}
298308

299-
// 4. Give up — tell the user how
300-
throw new WhisperUnavailableError(`whisper-cpp not found. Install: ${getInstallInstructions()}`);
309+
// 4. Give up — tell the user why and how
310+
throw new WhisperUnavailableError(
311+
`whisper-cpp not found (${causes.join("; ")}). Install: ${getInstallInstructions()}`,
312+
);
301313
}
302314

303315
export async function ensureModel(

0 commit comments

Comments
 (0)