@hienlh/ppm 0.23.5 → 0.23.7

package/src/services/speech-to-text/whisper-catalog.ts

@@ -0,0 +1,142 @@
+/**
+ * What "install Whisper" downloads: one whisper.cpp build per platform, one
+ * speech model, and the VAD model that goes with every model.
+ *
+ * Pure and parameterised so the whole matrix is unit-testable without touching
+ * `process.*` or the network. Every entry is pinned by tag/revision AND by
+ * SHA-256, because this code downloads an executable onto the user's machine.
+ *
+ * The VAD model is not optional. Whisper invents speech out of silence, and in
+ * Vietnamese it invents the same YouTube outro every time — six seconds of
+ * digital silence transcribed as "Hãy subscribe cho kênh Ghiền Mì Gõ Để không
+ * bỏ lỡ những video hấp dẫn" on both `small` and `large-v3-turbo`, and pink
+ * noise as "Cảm ơn các bạn đã theo dõi và hẹn gặp lại." With Silero VAD in
+ * front, both come back empty (and in 0.3s instead of seconds).
+ */
+
+/** whisper.cpp release that the prebuilt binaries come from. */
+export const WHISPER_BUILD = "b5130";
+/** Whisper version inside that build, for display only. */
+export const WHISPER_VERSION = "1.9.4";
+
+const RELEASE_BASE = `https://github.com/ggml-org/whisper.cpp/releases/download/${WHISPER_BUILD}`;
+
+/** Pinned commits of the Hugging Face repos the models are fetched from. */
+const MODEL_REPO_REV = "5359861c739e955e79d9a303bcbc70fb988958b1";
+const VAD_REPO_REV = "9ffd54a1e1ee413ddf265af9913beaf518d1639b";
+
+export interface WhisperAsset {
+  /** Archive file name as published in the release. */
+  file: string;
+  url: string;
+  sha256: string;
+  ext: "tar.gz" | "zip";
+}
+
+/**
+ * Prebuilt whisper.cpp per platform.
+ *
+ * macOS is deliberately absent: the release ships an xcframework (a library for
+ * Swift apps), never a `whisper-cli`, so there is nothing to download and
+ * unpack. A Mac uses Homebrew's `whisper.cpp` formula instead — see
+ * `MACOS_INSTALL_HINT` — and PPM then finds `whisper-cli` on PATH.
+ */
+const ASSETS: Record<string, WhisperAsset> = {
+  "linux-x64": {
+    file: "whisper-bin-ubuntu-x64.tar.gz",
+    url: `${RELEASE_BASE}/whisper-bin-ubuntu-x64.tar.gz`,
+    sha256: "53e7fd8b5764edad916b8848dd0af6abb1ff1d3b86c899e79c78652412536c32",
+    ext: "tar.gz",
+  },
+  "linux-arm64": {
+    file: "whisper-bin-ubuntu-arm64.tar.gz",
+    url: `${RELEASE_BASE}/whisper-bin-ubuntu-arm64.tar.gz`,
+    sha256: "93532a0e3777f26f041ffa358ee77dd88b1a33a86847c1990745327ff335a5d6",
+    ext: "tar.gz",
+  },
+  "win32-x64": {
+    file: "whisper-bin-x64.zip",
+    url: `${RELEASE_BASE}/whisper-bin-x64.zip`,
+    sha256: "f9ec6c52a2e949b62ab51fa21d0d497958f9e41c3010c157c4e42932d5316f3c",
+    ext: "zip",
+  },
+  "win32-arm64": {
+    file: "whisper-bin-win-cpu-arm64.zip",
+    url: `${RELEASE_BASE}/whisper-bin-win-cpu-arm64.zip`,
+    sha256: "799543b926ab5b6c2d60cab269a2092e0ae8d27820e9e15429e59de3699546fc",
+    ext: "zip",
+  },
+};
+
+export const MACOS_INSTALL_HINT = "brew install whisper.cpp";
+
+/** The published build for a platform/arch pair, or null when there is none. */
+export function whisperAssetFor(platform: NodeJS.Platform, arch: string): WhisperAsset | null {
+  return ASSETS[`${platform}-${arch}`] ?? null;
+}
+
+export interface WhisperModel {
+  id: string;
+  /** File name in the Hugging Face repo, and on disk. */
+  file: string;
+  label: string;
+  /** One line under the label in Settings. */
+  note: string;
+  bytes: number;
+  sha256: string;
+}
+
+/**
+ * Three rungs, measured on a 10s Vietnamese clip (i9-12900K, 16 threads):
+ * `base` 0.9s but "sửa giúp" came back "sửa dụp"; `small` 2.2s and readable;
+ * `large-v3-turbo` 5.5s and the only one that kept English identifiers
+ * ("handle ... toggle ... message input") intact. Quantized weights, since a
+ * q5 file is a third of the size for no accuracy difference anyone dictating a
+ * chat message would notice.
+ */
+export const WHISPER_MODELS: WhisperModel[] = [
+  {
+    id: "base-q5_1",
+    file: "ggml-base-q5_1.bin",
+    label: "Base",
+    note: "Fastest, weakest — usable for English, rough in Vietnamese",
+    bytes: 59_707_625,
+    sha256: "422f1ae452ade6f30a004d7e5c6a43195e4433bc370bf23fac9cc591f01a8898",
+  },
+  {
+    id: "small-q5_1",
+    file: "ggml-small-q5_1.bin",
+    label: "Small",
+    note: "Middle ground — readable Vietnamese, garbles English words",
+    bytes: 190_085_487,
+    sha256: "ae85e4a935d7a567bd102fe55afc16bb595bdb618e11b2fc7591bc08120411bb",
+  },
+  {
+    id: "large-v3-turbo-q5_0",
+    file: "ggml-large-v3-turbo-q5_0.bin",
+    label: "Large v3 Turbo",
+    note: "Best Vietnamese, keeps English terms — a few seconds per sentence",
+    bytes: 574_041_195,
+    sha256: "394221709cd5ad1f40c46e6031ca61bce88931e6e088c188294c6d5a55ffa7e2",
+  },
+];
+
+export const DEFAULT_MODEL_ID = "large-v3-turbo-q5_0";
+
+export const VAD_MODEL = {
+  file: "ggml-silero-v5.1.2.bin",
+  bytes: 885_098,
+  sha256: "29940d98d42b91fbd05ce489f3ecf7c72f0a42f027e4875919a28fb4c04ea2cf",
+};
+
+export function modelById(id: string): WhisperModel | null {
+  return WHISPER_MODELS.find((m) => m.id === id) ?? null;
+}
+
+export function modelUrl(model: WhisperModel): string {
+  return `https://huggingface.co/ggerganov/whisper.cpp/resolve/${MODEL_REPO_REV}/${model.file}`;
+}
+
+export function vadModelUrl(): string {
+  return `https://huggingface.co/ggml-org/whisper-vad/resolve/${VAD_REPO_REV}/${VAD_MODEL.file}`;
+}

package/src/services/speech-to-text/whisper-download.ts

@@ -0,0 +1,113 @@
+/**
+ * Streaming download with a SHA-256 gate.
+ *
+ * A model is 574 MB, so it is hashed while it streams rather than read back
+ * afterwards, and it lands on a `.part` file that is only renamed once the hash
+ * matches: an interrupted or tampered download can never be mistaken for an
+ * installed one, and a retry starts clean.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, renameSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type FetchFn = typeof fetch;
+
+export interface DownloadOptions {
+  url: string;
+  dest: string;
+  /** Lowercase hex. The download is discarded when the bytes hash to anything else. */
+  sha256: string;
+  /** Called as bytes arrive; `total` is 0 when the server sends no Content-Length. */
+  onProgress?: (received: number, total: number) => void;
+  fetchFn?: FetchFn;
+  signal?: AbortSignal;
+}
+
+/**
+ * How long the transfer may produce no bytes at all before it is abandoned.
+ *
+ * Idle rather than wall-clock: the largest model here is 574 MB, and any total-time
+ * bound that a slow line can exceed would abort a download that was working. What is
+ * never legitimate is silence — a half-open socket after a dropped wifi link or a
+ * tunnel that went away never errors and never yields, so without this the `for await`
+ * below simply never returns and the install never settles.
+ */
+const STALL_TIMEOUT_MS = 60_000;
+
+export async function downloadVerified(opts: DownloadOptions): Promise<void> {
+  const { url, dest, sha256, onProgress, signal } = opts;
+  const fetchFn = opts.fetchFn ?? fetch;
+  const part = `${dest}.part`;
+
+  mkdirSync(dirname(dest), { recursive: true });
+  rmSync(part, { force: true });
+
+  // The caller's signal and the stall timer both have to reach the body stream, and
+  // `fetch` takes one signal — so an internal controller carries both.
+  const stall = new AbortController();
+  const forwardAbort = () => stall.abort(signal?.reason);
+  signal?.addEventListener("abort", forwardAbort, { once: true });
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const armStallTimer = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(
+      () => stall.abort(new Error(`download stalled: no bytes for ${STALL_TIMEOUT_MS}ms (${url})`)),
+      STALL_TIMEOUT_MS,
+    );
+    timer.unref?.();
+  };
+  const disarm = (): void => {
+    if (timer) clearTimeout(timer);
+    timer = null;
+    signal?.removeEventListener("abort", forwardAbort);
+  };
+
+  let res: Response;
+  armStallTimer();
+  try {
+    res = await fetchFn(url, { redirect: "follow", signal: stall.signal });
+  } catch (e) {
+    disarm();
+    throw stall.signal.aborted && stall.signal.reason instanceof Error ? stall.signal.reason : e;
+  }
+  if (!res.ok) { disarm(); throw new Error(`download failed: HTTP ${res.status} (${url})`); }
+  if (!res.body) { disarm(); throw new Error(`download failed: empty body (${url})`); }
+
+  const total = Number(res.headers.get("content-length") ?? 0) || 0;
+  const hash = createHash("sha256");
+  const sink = Bun.file(part).writer();
+  let received = 0;
+
+  try {
+    for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
+      armStallTimer();
+      hash.update(chunk);
+      sink.write(chunk);
+      received += chunk.byteLength;
+      onProgress?.(received, total);
+    }
+    await sink.end();
+    disarm();
+  } catch (e) {
+    disarm();
+    try {
+      await sink.end();
+    } catch {
+      // Sink already torn down by the failure itself.
+    }
+    rmSync(part, { force: true });
+    // An abort raised by the stall timer carries the reason worth reporting; the
+    // stream's own `AbortError` says only that somebody cancelled.
+    throw stall.signal.aborted && stall.signal.reason instanceof Error ? stall.signal.reason : e;
+  }
+
+  const actual = hash.digest("hex");
+  if (actual !== sha256.toLowerCase()) {
+    rmSync(part, { force: true });
+    throw new Error(`checksum mismatch for ${url}: expected ${sha256}, got ${actual}`);
+  }
+
+  // Windows refuses a rename onto an existing file, so clear the target first.
+  rmSync(dest, { force: true });
+  renameSync(part, dest);
+}

package/src/services/speech-to-text/whisper-hallucinations.ts

@@ -0,0 +1,51 @@
+/**
+ * Sentences Whisper invents when it is handed audio with no speech in it.
+ *
+ * The model was trained on YouTube subtitles, so the likeliest continuation of
+ * "a Vietnamese clip with nothing being said" is that channel's sign-off — and
+ * it is not a rare edge case: with `--vad` off, *every* non-speech clip
+ * measured on large-v3-turbo (digital silence, white noise at four levels,
+ * 50 Hz hum, a 440 Hz tone, brown noise, keyboard clicks, a cough, a breath)
+ * came back as the same one sentence, byte for byte:
+ *
+ *     silence/noise/hum/tone/typing/cough  →  "Hãy subscribe cho kênh Ghiền Mì
+ *                                              Gõ Để không bỏ lỡ những video hấp dẫn"
+ *     room tone                            →  "Cảm ơn các bạn đã theo dõi và hẹn gặp lại."
+ *
+ * The VAD model is what normally stops this (those same clips come back empty
+ * with it on), so this list is the second line of defence for the audio VAD
+ * does let through — a fan, a distant TV, a word spoken too far from the mic.
+ * It is deliberately short and measured rather than guessed: add a sentence
+ * here only after seeing this model produce it from a clip with no speech.
+ */
+
+/** Same shape as the list: lowercased, punctuation dropped, spaces collapsed. */
+function normalize(line: string): string {
+  return line
+    .toLowerCase()
+    .replace(/[.,!?;:"'`*\-_()[\]…]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const INVENTED = [
+  "Hãy subscribe cho kênh Ghiền Mì Gõ Để không bỏ lỡ những video hấp dẫn",
+  "Cảm ơn các bạn đã theo dõi và hẹn gặp lại.",
+].map(normalize);
+
+/**
+ * The channel name is the fingerprint: the sign-off comes back with small
+ * wording changes, and nobody dictating into a chat box says it at all.
+ */
+const FINGERPRINT = normalize("Ghiền Mì Gõ");
+
+/**
+ * True for a whole segment the model made up. Whole lines only — `-nt` prints
+ * one line per segment, so dropping a line drops exactly the invented
+ * sentence and leaves the real ones either side of it alone.
+ */
+export function isInventedLine(line: string): boolean {
+  const normalized = normalize(line);
+  if (normalized.length === 0) return false;
+  return INVENTED.includes(normalized) || normalized.includes(FINGERPRINT);
+}

package/src/services/speech-to-text/whisper-install.service.ts

@@ -0,0 +1,247 @@
+/**
+ * Installing Whisper on the host: download the prebuilt whisper.cpp for this
+ * platform, the chosen speech model, and the VAD model, then prove the binary
+ * actually runs here.
+ *
+ * That last step is not ceremony. The published Linux build needs glibc 2.34
+ * and libstdc++ from GCC 11, so on an older host (Ubuntu 20.04 ships glibc
+ * 2.31) every file downloads fine and the binary only fails when someone first
+ * speaks into the chat box. Running `--help` once at install time turns that
+ * into an install error naming the cause.
+ *
+ * One model is kept on disk at a time: they are 60–574 MB, and "which one is
+ * active" then has no state to drift — it is whichever file is there.
+ */
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  DEFAULT_MODEL_ID,
+  MACOS_INSTALL_HINT,
+  VAD_MODEL,
+  WHISPER_MODELS,
+  WHISPER_VERSION,
+  modelById,
+  modelUrl,
+  vadModelUrl,
+  whisperAssetFor,
+  type WhisperAsset,
+} from "./whisper-catalog.ts";
+import { downloadVerified, type FetchFn } from "./whisper-download.ts";
+import {
+  findWhisperBinary,
+  whisperBinDir,
+  whisperDir,
+  whisperModelDir,
+  whisperTmpDir,
+  type WhisperBinary,
+} from "./whisper-paths.ts";
+
+export type InstallPhase = "binary" | "model" | "vad" | "verify";
+
+export interface InstallJobState {
+  modelId: string;
+  phase: InstallPhase;
+  receivedBytes: number;
+  totalBytes: number;
+  done: boolean;
+  error: string | null;
+}
+
+export interface WhisperStatusModel {
+  id: string;
+  label: string;
+  note: string;
+  bytes: number;
+}
+
+export interface WhisperStatus {
+  /** False only when this platform has no prebuilt build AND no binary on the host. */
+  installable: boolean;
+  /** Manual command for a platform PPM cannot install for (macOS). */
+  installHint: string | null;
+  binary: WhisperBinary | null;
+  version: string;
+  /** Model currently on disk, if any. */
+  model: WhisperStatusModel | null;
+  /** Binary + model + VAD model all present — the mic can use it. */
+  ready: boolean;
+  models: WhisperStatusModel[];
+  install: InstallJobState | null;
+}
+
+let currentJob: InstallJobState | null = null;
+
+const publicModel = (m: (typeof WHISPER_MODELS)[number]): WhisperStatusModel => ({
+  id: m.id,
+  label: m.label,
+  note: m.note,
+  bytes: m.bytes,
+});
+
+/** The installed model, found by which catalog file exists on disk. */
+export function installedModel(): (typeof WHISPER_MODELS)[number] | null {
+  return WHISPER_MODELS.find((m) => existsSync(resolve(whisperModelDir(), m.file))) ?? null;
+}
+
+export function vadModelPath(): string {
+  return resolve(whisperModelDir(), VAD_MODEL.file);
+}
+
+export function getWhisperStatus(
+  platform: NodeJS.Platform = process.platform,
+  arch: string = process.arch,
+): WhisperStatus {
+  const binary = findWhisperBinary(platform);
+  const model = installedModel();
+  const hasAsset = whisperAssetFor(platform, arch) !== null;
+
+  return {
+    installable: hasAsset || binary !== null,
+    installHint: !hasAsset && platform === "darwin" ? MACOS_INSTALL_HINT : null,
+    binary,
+    version: WHISPER_VERSION,
+    model: model ? publicModel(model) : null,
+    ready: binary !== null && model !== null && existsSync(vadModelPath()),
+    models: WHISPER_MODELS.map(publicModel),
+    install: currentJob,
+  };
+}
+
+async function extractArchive(archive: string, asset: WhisperAsset, destDir: string, platform: NodeJS.Platform) {
+  const cmd =
+    asset.ext === "tar.gz"
+      ? ["tar", "-xzf", archive, "-C", destDir]
+      : platform === "win32"
+        ? // Windows 10+ ships bsdtar as tar.exe, which reads zip.
+          ["tar", "-xf", archive, "-C", destDir]
+        : ["unzip", "-o", "-q", archive, "-d", destDir];
+
+  const proc = Bun.spawn({ cmd, stdout: "ignore", stderr: "pipe" });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(`extract failed (${cmd[0]} exit ${code}): ${stderr.slice(0, 200)}`);
+  }
+}
+
+/** Run the binary once so a host that cannot execute it fails here, not mid-sentence. */
+async function verifyBinaryRuns(path: string): Promise<void> {
+  let proc;
+  try {
+    proc = Bun.spawn({ cmd: [path, "--help"], stdout: "ignore", stderr: "pipe", windowsHide: true });
+  } catch (e: any) {
+    throw new Error(`whisper-cli could not be started: ${e?.message ?? e}`);
+  }
+  const [code, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+  if (code !== 0) {
+    const detail = stderr.trim().split("\n")[0] ?? `exit ${code}`;
+    throw new Error(`whisper-cli does not run on this host: ${detail}`);
+  }
+}
+
+/** Keep only the model just installed — the others are hundreds of MB of nothing. */
+function pruneOtherModels(keepFile: string) {
+  for (const m of WHISPER_MODELS) {
+    if (m.file !== keepFile) rmSync(resolve(whisperModelDir(), m.file), { force: true });
+  }
+}
+
+async function runInstall(modelId: string, platform: NodeJS.Platform, arch: string, fetchFn?: FetchFn) {
+  const model = modelById(modelId);
+  if (!model) throw new Error(`unknown model: ${modelId}`);
+  const job = currentJob!;
+  const progress = (received: number, total: number) => {
+    job.receivedBytes = received;
+    job.totalBytes = total || 0;
+  };
+
+  mkdirSync(whisperModelDir(), { recursive: true });
+
+  // A host that already has whisper-cli (Homebrew, distro package) needs models only.
+  if (!findWhisperBinary(platform)) {
+    const asset = whisperAssetFor(platform, arch);
+    if (!asset) throw new Error(`no whisper.cpp build for ${platform}/${arch} — install it manually`);
+    job.phase = "binary";
+    mkdirSync(whisperBinDir(), { recursive: true });
+    mkdirSync(whisperTmpDir(), { recursive: true });
+    const archive = resolve(whisperTmpDir(), asset.file);
+    await downloadVerified({ url: asset.url, dest: archive, sha256: asset.sha256, onProgress: progress, fetchFn });
+    await extractArchive(archive, asset, whisperBinDir(), platform);
+    rmSync(archive, { force: true });
+  }
+
+  job.phase = "model";
+  progress(0, model.bytes);
+  await downloadVerified({
+    url: modelUrl(model),
+    dest: resolve(whisperModelDir(), model.file),
+    sha256: model.sha256,
+    onProgress: progress,
+    fetchFn,
+  });
+
+  job.phase = "vad";
+  progress(0, VAD_MODEL.bytes);
+  await downloadVerified({
+    url: vadModelUrl(),
+    dest: vadModelPath(),
+    sha256: VAD_MODEL.sha256,
+    onProgress: progress,
+    fetchFn,
+  });
+
+  job.phase = "verify";
+  const binary = findWhisperBinary(platform);
+  if (!binary) throw new Error("whisper-cli missing after install");
+  await verifyBinaryRuns(binary.path);
+
+  pruneOtherModels(model.file);
+}
+
+/**
+ * Start an install in the background and return immediately — the UI polls
+ * `getWhisperStatus()`. One at a time: a second call while a job runs throws.
+ */
+export function startWhisperInstall(
+  modelId: string = DEFAULT_MODEL_ID,
+  opts: { platform?: NodeJS.Platform; arch?: string; fetchFn?: FetchFn } = {},
+): InstallJobState {
+  if (currentJob && !currentJob.done) throw new Error("An install is already running");
+  const platform = opts.platform ?? process.platform;
+  const arch = opts.arch ?? process.arch;
+  if (!modelById(modelId)) throw new Error(`unknown model: ${modelId}`);
+
+  const job: InstallJobState = {
+    modelId,
+    phase: "binary",
+    receivedBytes: 0,
+    totalBytes: 0,
+    done: false,
+    error: null,
+  };
+  currentJob = job;
+
+  runInstall(modelId, platform, arch, opts.fetchFn)
+    .then(() => {
+      job.done = true;
+    })
+    .catch((e: any) => {
+      job.error = e?.message ?? String(e);
+      job.done = true;
+      console.error("[whisper] install failed:", job.error);
+    });
+
+  return job;
+}
+
+/** Remove everything PPM downloaded. A system-installed whisper-cli is left alone. */
+export function uninstallWhisper(): void {
+  if (currentJob && !currentJob.done) throw new Error("An install is running");
+  rmSync(whisperDir(), { recursive: true, force: true });
+  currentJob = null;
+}
+
+/** Test seam: forget any finished job so a suite starts from a clean status. */
+export function _resetWhisperInstallState(): void {
+  currentJob = null;
+}

package/src/services/speech-to-text/whisper-paths.ts

@@ -0,0 +1,62 @@
+/**
+ * Where the Whisper install lives, and how the binary is found.
+ *
+ * Everything PPM downloads sits under `<ppm dir>/whisper/` so uninstall is one
+ * `rm -rf` and an isolated `PPM_HOME` (tests) never touches a real install.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { getPpmDir } from "../ppm-dir.ts";
+
+export const whisperDir = () => resolve(getPpmDir(), "whisper");
+export const whisperBinDir = () => resolve(whisperDir(), "bin");
+export const whisperModelDir = () => resolve(whisperDir(), "models");
+export const whisperTmpDir = () => resolve(whisperDir(), "tmp");
+
+export const cliName = (platform: NodeJS.Platform = process.platform) =>
+  platform === "win32" ? "whisper-cli.exe" : "whisper-cli";
+
+/**
+ * The extracted archive keeps its own top-level directory — `whisper-bin-ubuntu-x64/`
+ * on Linux, `Release/` on Windows — and those names carry the build tag, so the
+ * binary is located by looking one level down rather than assumed.
+ */
+export function findBundledBinary(platform: NodeJS.Platform = process.platform): string | null {
+  const root = whisperBinDir();
+  if (!existsSync(root)) return null;
+  const name = cliName(platform);
+  if (existsSync(resolve(root, name))) return resolve(root, name);
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const candidate = resolve(root, entry.name, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Homebrew's `whisper.cpp` is how a Mac gets a `whisper-cli` (the release has no
+ * macOS CLI to download), and a PPM started by launchd/systemd inherits a PATH
+ * that usually has neither Homebrew prefix in it — so both are checked directly
+ * rather than trusting `PATH` alone.
+ */
+const SYSTEM_PATHS = ["/opt/homebrew/bin/whisper-cli", "/usr/local/bin/whisper-cli", "/usr/bin/whisper-cli"];
+
+export function findSystemBinary(): string | null {
+  const onPath = Bun.which("whisper-cli");
+  if (onPath) return onPath;
+  return SYSTEM_PATHS.find((p) => existsSync(p)) ?? null;
+}
+
+export interface WhisperBinary {
+  path: string;
+  /** `bundled` = installed by PPM and removable from Settings; `system` = the host's own. */
+  source: "bundled" | "system";
+}
+
+export function findWhisperBinary(platform: NodeJS.Platform = process.platform): WhisperBinary | null {
+  const bundled = findBundledBinary(platform);
+  if (bundled) return { path: bundled, source: "bundled" };
+  const system = findSystemBinary();
+  return system ? { path: system, source: "system" } : null;
+}