@drakulavich/parakeet-cli 0.7.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/parakeet-cli",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Fast local speech-to-text CLI. CoreML on Apple Silicon, ONNX on CPU. 25 languages.",
   "type": "module",
   "bin": {

package/src/__tests__/benchmark-report.test.ts

@@ -0,0 +1,67 @@
+import { describe, test, expect } from "bun:test";
+import {
+  createBenchmarkSummary,
+  renderBenchmarkReport,
+  type BenchmarkSystemInfo,
+} from "../benchmark-report";
+
+const system: BenchmarkSystemInfo = {
+  os: "Darwin",
+  arch: "arm64",
+  chip: "Apple M3 Pro",
+  ram: "18 GB",
+  backend: "CoreML",
+};
+
+describe("benchmark-report", () => {
+  test("createBenchmarkSummary computes totals and speedup", () => {
+    expect(
+      createBenchmarkSummary(
+        [
+          { time: 2.34, text: "a" },
+          { time: 1.11, text: "b" },
+        ],
+        [
+          { time: 1.0, text: "a" },
+          { time: 0.5, text: "b" },
+        ],
+      ),
+    ).toEqual({
+      whisper_total: 3.5,
+      parakeet_total: 1.5,
+      speedup: 2.3,
+    });
+  });
+
+  test("createBenchmarkSummary rejects mismatched result counts", () => {
+    expect(() =>
+      createBenchmarkSummary(
+        [{ time: 1, text: "a" }],
+        [
+          { time: 1, text: "a" },
+          { time: 2, text: "b" },
+        ],
+      ),
+    ).toThrow("Benchmark result count mismatch");
+  });
+
+  test("renderBenchmarkReport produces markdown with totals", () => {
+    const report = renderBenchmarkReport({
+      date: "2026-04-08",
+      version: "0.7.0",
+      system,
+      whisperResults: [{ time: 3.2, text: "hello" }],
+      parakeetResults: [{ time: 1.6, text: "hello" }],
+    });
+
+    expect(report.summary).toEqual({
+      whisper_total: 3.2,
+      parakeet_total: 1.6,
+      speedup: 2,
+    });
+    expect(report.markdown).toContain("**Date:** 2026-04-08");
+    expect(report.markdown).toContain("**Runner:** Darwin arm64 (Apple M3 Pro, 18 GB RAM)");
+    expect(report.markdown).toContain("| **Total** | **3.2s** | **1.6s** | | |");
+    expect(report.markdown).toContain("**Parakeet is ~2x faster.**");
+  });
+});

package/src/__tests__/coreml-install.test.ts

@@ -0,0 +1,281 @@
+import { describe, test, expect } from "bun:test";
+import {
+  classifyCoreMLInstallProbe,
+  createCoreMLBinaryRunner,
+  ensureCoreMLModels,
+  getCoreMLDownloadURL,
+  getCoreMLInstallState,
+  getCoreMLInstallStatus,
+  getCoreMLSupportDir,
+  parseCoreMLBinaryCapabilities,
+  planCoreMLInstall,
+  type CoreMLBinaryCommandResult,
+  type CoreMLBinaryRunner,
+} from "../coreml-install";
+import { join } from "path";
+import { homedir } from "os";
+
+describe("coreml-install", () => {
+  test("getCoreMLSupportDir returns correct cache path", () => {
+    expect(getCoreMLSupportDir()).toBe(
+      join(homedir(), ".cache", "parakeet", "coreml"),
+    );
+  });
+
+  test("getCoreMLDownloadURL includes version and correct filename", () => {
+    const url = getCoreMLDownloadURL("0.5.0");
+    expect(url).toBe(
+      "https://github.com/drakulavich/parakeet-cli/releases/download/v0.5.0/parakeet-coreml-darwin-arm64",
+    );
+  });
+
+  test("getCoreMLInstallState returns missing when binary is absent", () => {
+    const state = getCoreMLInstallState({
+      binPath: "/tmp/parakeet-coreml",
+      exists: () => false,
+    });
+
+    expect(state).toBe("missing");
+  });
+
+  test("getCoreMLInstallState returns binary-only when readiness check fails", () => {
+    const state = getCoreMLInstallState({
+      binPath: "/tmp/parakeet-coreml",
+      exists: () => true,
+      verifyReady: () => "binary-only",
+    });
+
+    expect(state).toBe("binary-only");
+  });
+
+  test("getCoreMLInstallState returns ready when readiness check passes", () => {
+    const state = getCoreMLInstallState({
+      binPath: "/tmp/parakeet-coreml",
+      exists: () => true,
+      verifyReady: () => "ready",
+    });
+
+    expect(state).toBe("ready");
+  });
+
+  test("getCoreMLInstallState returns stale-binary when cached binary is too old", () => {
+    const state = getCoreMLInstallState({
+      binPath: "/tmp/parakeet-coreml",
+      exists: () => true,
+      verifyReady: () => "stale-binary",
+    });
+
+    expect(state).toBe("stale-binary");
+  });
+
+  test("getCoreMLInstallState defaults to binary-only when no readiness checker is provided", () => {
+    const state = getCoreMLInstallState({
+      binPath: "/tmp/parakeet-coreml",
+      exists: () => true,
+    });
+
+    expect(state).toBe("binary-only");
+  });
+
+  test("planCoreMLInstall skips work when install is ready", () => {
+    expect(planCoreMLInstall("ready")).toEqual({
+      downloadBinary: false,
+      downloadModels: false,
+    });
+  });
+
+  test("planCoreMLInstall downloads only models when binary already exists", () => {
+    expect(planCoreMLInstall("binary-only")).toEqual({
+      downloadBinary: false,
+      downloadModels: true,
+    });
+  });
+
+  test("planCoreMLInstall forces both downloads with no-cache", () => {
+    expect(planCoreMLInstall("ready", true)).toEqual({
+      downloadBinary: true,
+      downloadModels: true,
+    });
+  });
+
+  test("planCoreMLInstall refreshes stale cached binaries", () => {
+    expect(planCoreMLInstall("stale-binary")).toEqual({
+      downloadBinary: true,
+      downloadModels: true,
+    });
+  });
+
+  test("parseCoreMLBinaryCapabilities accepts the current protocol payload", () => {
+    expect(
+      parseCoreMLBinaryCapabilities(
+        JSON.stringify({
+          protocolVersion: 1,
+          installState: "ready",
+          supportedCommands: {
+            checkInstall: true,
+            downloadOnly: true,
+          },
+        }),
+      ),
+    ).toEqual({
+      protocolVersion: 1,
+      installState: "ready",
+      supportedCommands: {
+        checkInstall: true,
+        downloadOnly: true,
+      },
+    });
+  });
+
+  test("parseCoreMLBinaryCapabilities rejects malformed payloads", () => {
+    expect(
+      parseCoreMLBinaryCapabilities("{invalid"),
+    ).toBeNull();
+    expect(
+      parseCoreMLBinaryCapabilities(
+        JSON.stringify({
+          protocolVersion: 2,
+          installState: "ready",
+          supportedCommands: {
+            checkInstall: true,
+            downloadOnly: true,
+          },
+        }),
+      ),
+    ).toBeNull();
+  });
+
+  test("classifyCoreMLInstallProbe classifies capabilities responses", () => {
+    expect(
+      classifyCoreMLInstallProbe(1, ""),
+    ).toBe("stale-binary");
+    expect(
+      classifyCoreMLInstallProbe(
+        0,
+        JSON.stringify({
+          protocolVersion: 1,
+          installState: "models-missing",
+          supportedCommands: {
+            checkInstall: true,
+            downloadOnly: true,
+          },
+        }),
+      ),
+    ).toBe("binary-only");
+    expect(
+      classifyCoreMLInstallProbe(
+        0,
+        JSON.stringify({
+          protocolVersion: 1,
+          installState: "ready",
+          supportedCommands: {
+            checkInstall: true,
+            downloadOnly: true,
+          },
+        }),
+      ),
+    ).toBe("ready");
+    expect(
+      classifyCoreMLInstallProbe(0, "{\"protocolVersion\":999}"),
+    ).toBe("stale-binary");
+  });
+
+  test("createCoreMLBinaryRunner runs the expected commands", () => {
+    const calls: string[][] = [];
+    const runner = createCoreMLBinaryRunner((cmd) => {
+      calls.push(Array.isArray(cmd) ? cmd : cmd.cmd);
+      return {
+        exitCode: 0,
+        stdout: Buffer.from("{}"),
+        stderr: Buffer.from(""),
+      } as ReturnType<typeof Bun.spawnSync>;
+    });
+
+    runner.probeCapabilities("/tmp/parakeet-coreml");
+    runner.downloadModels("/tmp/parakeet-coreml");
+
+    expect(calls).toEqual([
+      ["/tmp/parakeet-coreml", "--capabilities-json"],
+      ["/tmp/parakeet-coreml", "--download-only"],
+    ]);
+  });
+
+  test("getCoreMLInstallStatus delegates to the runner probe", () => {
+    const runner: CoreMLBinaryRunner = {
+      probeCapabilities() {
+        return {
+          exitCode: 0,
+          stdout: JSON.stringify({
+            protocolVersion: 1,
+            installState: "models-missing",
+            supportedCommands: {
+              checkInstall: true,
+              downloadOnly: true,
+            },
+          }),
+          stderr: "",
+        };
+      },
+      downloadModels() {
+        throw new Error("not used");
+      },
+    };
+
+    expect(getCoreMLInstallStatus("/tmp/parakeet-coreml", runner)).toBe("binary-only");
+  });
+
+  test("ensureCoreMLModels streams command output through the writer", async () => {
+    const writes = {
+      stdout: [] as string[],
+      stderr: [] as string[],
+    };
+    const runner: CoreMLBinaryRunner = {
+      probeCapabilities() {
+        throw new Error("not used");
+      },
+      downloadModels() {
+        return {
+          exitCode: 0,
+          stdout: "downloaded\n",
+          stderr: "progress\n",
+        };
+      },
+    };
+
+    await ensureCoreMLModels("/tmp/parakeet-coreml", runner, {
+      stdout(message) {
+        writes.stdout.push(message);
+      },
+      stderr(message) {
+        writes.stderr.push(message);
+      },
+    });
+
+    expect(writes).toEqual({
+      stdout: ["downloaded\n"],
+      stderr: ["progress\n"],
+    });
+  });
+
+  test("ensureCoreMLModels throws a contextual error when download fails", async () => {
+    const runner: CoreMLBinaryRunner = {
+      probeCapabilities() {
+        throw new Error("not used");
+      },
+      downloadModels() {
+        return {
+          exitCode: 2,
+          stdout: "",
+          stderr: "download failed",
+        };
+      },
+    };
+
+    await expect(
+      ensureCoreMLModels("/tmp/parakeet-coreml", runner, {
+        stdout() {},
+        stderr() {},
+      }),
+    ).rejects.toThrow("Failed to download CoreML models: download failed");
+  });
+});

package/src/__tests__/coreml.test.ts

@@ -1,28 +1,24 @@
 import { describe, test, expect } from "bun:test";
-import { getCoreMLBinPath, isMacArm64, isCoreMLInstalled } from "../coreml";
-import { join } from "path";
-import { homedir } from "os";
+import {
+  shouldRetryCoreMLWithWav,
+} from "../coreml";
 
 describe("coreml", () => {
-  test("getCoreMLBinPath returns correct cache path", () => {
-    const binPath = getCoreMLBinPath();
-    expect(binPath).toBe(
-      join(homedir(), ".cache", "parakeet", "coreml", "bin", "parakeet-coreml"),
-    );
+  test("retries non-wav files on CoreAudio decode errors", () => {
+    expect(
+      shouldRetryCoreMLWithWav(
+        "fixtures/hello-english.oga",
+        new Error("Error: The operation couldn’t be completed. (com.apple.coreaudio.avfaudio error 1718449215.)"),
+      ),
+    ).toBe(true);
   });
 
-  test("isMacArm64 returns a boolean", () => {
-    const result = isMacArm64();
-    expect(typeof result).toBe("boolean");
-    if (process.platform === "darwin" && process.arch === "arm64") {
-      expect(result).toBe(true);
-    } else {
-      expect(result).toBe(false);
-    }
-  });
-
-  test("isCoreMLInstalled returns a boolean", () => {
-    const result = isCoreMLInstalled();
-    expect(typeof result).toBe("boolean");
+  test("does not retry wav files on CoreAudio decode errors", () => {
+    expect(
+      shouldRetryCoreMLWithWav(
+        "fixtures/silence.wav",
+        new Error("Error: The operation couldn’t be completed. (com.apple.coreaudio.avfaudio error 1718449215.)"),
+      ),
+    ).toBe(false);
   });
 });

package/src/__tests__/lib.test.ts

@@ -2,10 +2,6 @@ import { describe, expect, it } from "bun:test";
 import { transcribe } from "../lib";
 
 describe("lib API", () => {
-  it("exports transcribe function", () => {
-    expect(typeof transcribe).toBe("function");
-  });
-
   it("rejects missing file", async () => {
     await expect(transcribe("/nonexistent/audio.wav")).rejects.toThrow("File not found");
   });

package/src/audio.ts

@@ -6,40 +6,64 @@ import { randomUUID } from "crypto";
 let ffmpegChecked = false;
 
 export async function convertToFloat32PCM(inputPath: string): Promise<Float32Array> {
+  const tmpPath = await convertAudioWithFfmpeg(inputPath, "f32le", [
+    "-ar", "16000",
+    "-ac", "1",
+    "-f", "f32le",
+    "-acodec", "pcm_f32le",
+  ]);
+
+  try {
+    const raw = await Bun.file(tmpPath).arrayBuffer();
+    return new Float32Array(raw);
+  } finally {
+    // Best-effort cleanup; file may already be gone
+    try { unlinkSync(tmpPath); } catch {}
+  }
+}
+
+export async function convertToWav16kMono(inputPath: string): Promise<string> {
+  return convertAudioWithFfmpeg(inputPath, "wav", [
+    "-ar", "16000",
+    "-ac", "1",
+    "-f", "wav",
+    "-acodec", "pcm_s16le",
+  ]);
+}
+
+async function convertAudioWithFfmpeg(
+  inputPath: string,
+  extension: string,
+  ffmpegArgs: string[],
+): Promise<string> {
   if (!existsSync(inputPath)) {
     throw new Error(`file not found: ${inputPath}`);
   }
 
-  await assertFfmpegExists();
-
-  const tmpPath = join(tmpdir(), `parakeet-${randomUUID()}.f32le`);
+  assertFfmpegExists();
 
-  try {
-    const proc = Bun.spawn(
-      ["ffmpeg", "-i", inputPath, "-ar", "16000", "-ac", "1", "-f", "f32le", "-acodec", "pcm_f32le", tmpPath, "-y"],
-      { stdout: "pipe", stderr: "pipe" }
-    );
+  const tmpPath = join(tmpdir(), `parakeet-${randomUUID()}.${extension}`);
 
-    const exitCode = await proc.exited;
+  const proc = Bun.spawn(
+    ["ffmpeg", "-i", inputPath, ...ffmpegArgs, tmpPath, "-y"],
+    { stdout: "pipe", stderr: "pipe" }
+  );
 
-    if (exitCode !== 0) {
-      const stderr = await new Response(proc.stderr).text();
-      throw new Error(`failed to convert audio: ${stderr.trim().split("\n").pop()}`);
-    }
+  const [exitCode, stderr] = await Promise.all([
+    proc.exited,
+    new Response(proc.stderr).text(),
+  ]);
 
-    const raw = await Bun.file(tmpPath).arrayBuffer();
-    return new Float32Array(raw);
-  } finally {
-    // Best-effort cleanup; file may already be gone
-    try { unlinkSync(tmpPath); } catch {}
+  if (exitCode !== 0) {
+    throw new Error(`failed to convert audio: ${stderr.trim().split("\n").pop()}`);
   }
+
+  return tmpPath;
 }
 
-async function assertFfmpegExists(): Promise<void> {
+function assertFfmpegExists(): void {
   if (ffmpegChecked) return;
-  const proc = Bun.spawn(["which", "ffmpeg"], { stdout: "pipe", stderr: "pipe" });
-  const exitCode = await proc.exited;
-  if (exitCode !== 0) {
+  if (!Bun.which("ffmpeg")) {
     throw new Error("ffmpeg not found in PATH");
   }
   ffmpegChecked = true;

package/src/benchmark-report.ts

@@ -0,0 +1,92 @@
+export interface BenchmarkSystemInfo {
+  os: string;
+  arch: string;
+  chip: string;
+  ram: string;
+  backend: string;
+}
+
+export interface BenchmarkResult {
+  time: number;
+  text: string;
+}
+
+export interface BenchmarkSummary {
+  whisper_total: number;
+  parakeet_total: number;
+  speedup: number;
+}
+
+export interface BenchmarkReport {
+  markdown: string;
+  summary: BenchmarkSummary;
+}
+
+function roundToTenths(value: number): number {
+  return Math.round(value * 10) / 10;
+}
+
+export function createBenchmarkSummary(
+  whisperResults: BenchmarkResult[],
+  parakeetResults: BenchmarkResult[],
+): BenchmarkSummary {
+  if (whisperResults.length !== parakeetResults.length) {
+    throw new Error(
+      `Benchmark result count mismatch: faster-whisper=${whisperResults.length}, parakeet=${parakeetResults.length}`,
+    );
+  }
+
+  const whisperTotal = roundToTenths(
+    whisperResults.reduce((total, result) => total + result.time, 0),
+  );
+  const parakeetTotal = roundToTenths(
+    parakeetResults.reduce((total, result) => total + result.time, 0),
+  );
+
+  return {
+    whisper_total: whisperTotal,
+    parakeet_total: parakeetTotal,
+    speedup: parakeetTotal > 0 ? roundToTenths(whisperTotal / parakeetTotal) : 0,
+  };
+}
+
+export function renderBenchmarkReport(args: {
+  date: string;
+  version: string;
+  system: BenchmarkSystemInfo;
+  whisperResults: BenchmarkResult[];
+  parakeetResults: BenchmarkResult[];
+}): BenchmarkReport {
+  const { date, version, system, whisperResults, parakeetResults } = args;
+  const summary = createBenchmarkSummary(whisperResults, parakeetResults);
+
+  const lines: string[] = [
+    "",
+    `**Date:** ${date}`,
+    `**Version:** v${version}`,
+    `**Runner:** ${system.os} ${system.arch} (${system.chip}, ${system.ram} RAM)`,
+    `**Backend:** ${system.backend}`,
+    "",
+    `| # | faster-whisper | Parakeet (${system.backend}) | faster-whisper Transcript | Parakeet Transcript |`,
+    "|---|---------|----------|--------------------|---------------------|",
+  ];
+
+  for (let i = 0; i < whisperResults.length; i++) {
+    const whisper = whisperResults[i];
+    const parakeet = parakeetResults[i];
+    lines.push(
+      `| ${i + 1} | ${whisper.time}s | ${parakeet.time}s | ${whisper.text} | ${parakeet.text} |`,
+    );
+  }
+
+  lines.push(
+    `| **Total** | **${summary.whisper_total}s** | **${summary.parakeet_total}s** | | |`,
+  );
+  lines.push("");
+  lines.push(`**Parakeet is ~${summary.speedup}x faster.**`);
+
+  return {
+    markdown: lines.join("\n"),
+    summary,
+  };
+}

package/src/cli.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
 
 import { transcribe } from "./lib";
-import { downloadModel, downloadCoreML } from "./models";
+import { downloadModel } from "./onnx-install";
+import { downloadCoreML } from "./coreml-install";
 import { isMacArm64 } from "./coreml";
 
 async function main(): Promise<void> {

package/src/coreml-install.ts

@@ -0,0 +1,247 @@
+import { join, dirname } from "path";
+import { homedir } from "os";
+import { existsSync, mkdirSync, chmodSync } from "fs";
+import { getCoreMLBinPath } from "./coreml";
+
+const COREML_BINARY_NAME = "parakeet-coreml-darwin-arm64";
+const GITHUB_REPO = "drakulavich/parakeet-cli";
+
+export type CoreMLInstallState = "missing" | "binary-only" | "ready" | "stale-binary";
+export type CoreMLBinaryInstallState = "ready" | "models-missing";
+
+export interface CoreMLBinaryCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface CoreMLBinaryRunner {
+  probeCapabilities(binPath: string): CoreMLBinaryCommandResult;
+  downloadModels(binPath: string): CoreMLBinaryCommandResult;
+}
+
+export interface CoreMLOutputWriter {
+  stdout(message: string): void;
+  stderr(message: string): void;
+}
+
+export interface CoreMLBinaryCapabilities {
+  protocolVersion: number;
+  installState: CoreMLBinaryInstallState;
+  supportedCommands: {
+    checkInstall: boolean;
+    downloadOnly: boolean;
+  };
+}
+
+const defaultOutputWriter: CoreMLOutputWriter = {
+  stdout(message) {
+    process.stdout.write(message);
+  },
+  stderr(message) {
+    process.stderr.write(message);
+  },
+};
+
+export function createCoreMLBinaryRunner(
+  spawnSync: typeof Bun.spawnSync = Bun.spawnSync,
+): CoreMLBinaryRunner {
+  function runCommand(binPath: string, flag: string): CoreMLBinaryCommandResult {
+    const proc = spawnSync([binPath, flag], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    return {
+      exitCode: proc.exitCode,
+      stdout: proc.stdout.toString(),
+      stderr: proc.stderr.toString(),
+    };
+  }
+
+  return {
+    probeCapabilities(binPath) {
+      return runCommand(binPath, "--capabilities-json");
+    },
+    downloadModels(binPath) {
+      return runCommand(binPath, "--download-only");
+    },
+  };
+}
+
+const defaultCoreMLBinaryRunner = createCoreMLBinaryRunner();
+
+export function getCoreMLSupportDir(): string {
+  return join(homedir(), ".cache", "parakeet", "coreml");
+}
+
+export function getCoreMLDownloadURL(version: string): string {
+  return `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${COREML_BINARY_NAME}`;
+}
+
+export function getCoreMLLatestDownloadURL(): string {
+  return `https://github.com/${GITHUB_REPO}/releases/latest/download/${COREML_BINARY_NAME}`;
+}
+
+export function getCoreMLInstallState(opts?: {
+  binPath?: string;
+  exists?: (path: string) => boolean;
+  verifyReady?: (binPath: string) => CoreMLInstallState;
+}): CoreMLInstallState {
+  const binPath = opts?.binPath ?? getCoreMLBinPath();
+  const fileExists = opts?.exists ?? existsSync;
+  const verifyReady = opts?.verifyReady;
+
+  if (!fileExists(binPath)) {
+    return "missing";
+  }
+
+  if (!verifyReady) {
+    return "binary-only";
+  }
+
+  return verifyReady(binPath);
+}
+
+export function planCoreMLInstall(
+  state: CoreMLInstallState,
+  noCache = false,
+): { downloadBinary: boolean; downloadModels: boolean } {
+  if (noCache) {
+    return { downloadBinary: true, downloadModels: true };
+  }
+
+  switch (state) {
+    case "missing":
+      return { downloadBinary: true, downloadModels: true };
+    case "binary-only":
+      return { downloadBinary: false, downloadModels: true };
+    case "ready":
+      return { downloadBinary: false, downloadModels: false };
+    case "stale-binary":
+      return { downloadBinary: true, downloadModels: true };
+  }
+}
+
+export function parseCoreMLBinaryCapabilities(stdout: string): CoreMLBinaryCapabilities | null {
+  try {
+    const parsed = JSON.parse(stdout) as Partial<CoreMLBinaryCapabilities>;
+    if (parsed.protocolVersion !== 1) {
+      return null;
+    }
+    if (parsed.installState !== "ready" && parsed.installState !== "models-missing") {
+      return null;
+    }
+    if (!parsed.supportedCommands) {
+      return null;
+    }
+    if (parsed.supportedCommands.checkInstall !== true || parsed.supportedCommands.downloadOnly !== true) {
+      return null;
+    }
+
+    return {
+      protocolVersion: parsed.protocolVersion,
+      installState: parsed.installState,
+      supportedCommands: parsed.supportedCommands,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function classifyCoreMLInstallProbe(exitCode: number, stdout: string): CoreMLInstallState {
+  if (exitCode !== 0) {
+    return "stale-binary";
+  }
+
+  const capabilities = parseCoreMLBinaryCapabilities(stdout);
+  if (!capabilities) {
+    return "stale-binary";
+  }
+
+  return capabilities.installState === "ready" ? "ready" : "binary-only";
+}
+
+async function fetchCoreMLBinary(): Promise<Response> {
+  const latestUrl = getCoreMLLatestDownloadURL();
+  let res = await fetch(latestUrl, { redirect: "follow" });
+
+  if (res.ok) {
+    return res;
+  }
+
+  const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+  const versionUrl = getCoreMLDownloadURL(pkg.version);
+  res = await fetch(versionUrl, { redirect: "follow" });
+
+  if (!res.ok) {
+    throw new Error(`Failed to download CoreML binary (HTTP ${res.status}). No release found with ${COREML_BINARY_NAME}.`);
+  }
+
+  return res;
+}
+
+export function getCoreMLInstallStatus(
+  binPath: string,
+  runner: CoreMLBinaryRunner = defaultCoreMLBinaryRunner,
+): CoreMLInstallState {
+  const probe = runner.probeCapabilities(binPath);
+  return classifyCoreMLInstallProbe(probe.exitCode, probe.stdout);
+}
+
+export async function ensureCoreMLModels(
+  binPath: string,
+  runner: CoreMLBinaryRunner = defaultCoreMLBinaryRunner,
+  output: CoreMLOutputWriter = defaultOutputWriter,
+): Promise<void> {
+  const download = runner.downloadModels(binPath);
+
+  if (download.stderr) {
+    output.stderr(download.stderr);
+  }
+  if (download.stdout) {
+    output.stdout(download.stdout);
+  }
+
+  if (download.exitCode !== 0) {
+    const detail = download.stderr.trim();
+    throw new Error(detail ? `Failed to download CoreML models: ${detail}` : "Failed to download CoreML models");
+  }
+}
+
+export async function downloadCoreML(
+  noCache = false,
+  opts?: {
+    runner?: CoreMLBinaryRunner;
+    output?: CoreMLOutputWriter;
+  },
+): Promise<string> {
+  const binPath = getCoreMLBinPath();
+  const runner = opts?.runner ?? defaultCoreMLBinaryRunner;
+  const output = opts?.output ?? defaultOutputWriter;
+  const state = getCoreMLInstallState({
+    binPath,
+    verifyReady: noCache ? undefined : (path) => getCoreMLInstallStatus(path, runner),
+  });
+  const plan = planCoreMLInstall(state, noCache);
+
+  if (!plan.downloadBinary && !plan.downloadModels) {
+    console.log("CoreML backend already installed.");
+    return binPath;
+  }
+
+  if (plan.downloadBinary) {
+    console.error("Downloading parakeet-coreml binary...");
+    const res = await fetchCoreMLBinary();
+    mkdirSync(dirname(binPath), { recursive: true });
+    await Bun.write(binPath, res);
+    chmodSync(binPath, 0o755);
+  }
+
+  if (plan.downloadModels) {
+    await ensureCoreMLModels(binPath, runner, output);
+  }
+
+  console.log("CoreML backend installed successfully.");
+  return binPath;
+}

package/src/coreml.ts

@@ -1,6 +1,8 @@
 import { join } from "path";
 import { homedir } from "os";
 import { existsSync } from "fs";
+import { unlinkSync } from "fs";
+import { convertToWav16kMono } from "./audio";
 
 export function isMacArm64(): boolean {
   return process.platform === "darwin" && process.arch === "arm64";
@@ -15,6 +17,32 @@ export function isCoreMLInstalled(): boolean {
 }
 
 export async function transcribeCoreML(audioPath: string): Promise<string> {
+  try {
+    return await runCoreML(audioPath);
+  } catch (error) {
+    if (!shouldRetryCoreMLWithWav(audioPath, error)) {
+      throw error;
+    }
+
+    const wavPath = await convertToWav16kMono(audioPath);
+    try {
+      return await runCoreML(wavPath);
+    } finally {
+      try { unlinkSync(wavPath); } catch {}
+    }
+  }
+}
+
+export function shouldRetryCoreMLWithWav(audioPath: string, error: unknown): boolean {
+  if (audioPath.toLowerCase().endsWith(".wav")) {
+    return false;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("com.apple.coreaudio.avfaudio error");
+}
+
+async function runCoreML(audioPath: string): Promise<string> {
   const binPath = getCoreMLBinPath();
   const proc = Bun.spawn([binPath, audioPath], {
     stdout: "pipe",
@@ -28,7 +56,7 @@ export async function transcribeCoreML(audioPath: string): Promise<string> {
   ]);
 
   if (exitCode !== 0) {
-    throw new Error(stderr);
+    throw new Error(stderr.trim() || `parakeet-coreml exited with code ${exitCode}`);
   }
 
   return stdout.trim();

package/src/lib.ts

@@ -1,6 +1,7 @@
 import { existsSync } from "fs";
 import { transcribe as internalTranscribe, type TranscribeOptions } from "./transcribe";
-import { downloadModel, downloadCoreML } from "./models";
+import { downloadModel } from "./onnx-install";
+import { downloadCoreML } from "./coreml-install";
 
 export type { TranscribeOptions };
 export { downloadModel, downloadCoreML };

package/src/models.ts

@@ -1,168 +1,9 @@
-import { join, dirname } from "path";
-import { homedir } from "os";
-import { existsSync, mkdirSync, chmodSync } from "fs";
 import { isCoreMLInstalled } from "./coreml";
+import { isModelCached } from "./onnx-install";
 
-export const HF_REPO = "istupakov/parakeet-tdt-0.6b-v3-onnx";
-
-export const MODEL_FILES = [
-  "encoder-model.onnx",
-  "encoder-model.onnx.data",
-  "decoder_joint-model.onnx",
-  "nemo128.onnx",
-  "vocab.txt",
-];
-
-export function getModelDir(): string {
-  return join(homedir(), ".cache", "parakeet", "v3");
-}
-
-export function isModelCached(dir?: string): boolean {
-  const d = dir ?? getModelDir();
-  return MODEL_FILES.every((f) => existsSync(join(d, f)));
-}
+export * from "./onnx-install";
+export * from "./coreml-install";
 
 export function isModelInstalled(modelDir?: string): boolean {
   return isCoreMLInstalled() || isModelCached(modelDir);
 }
-
-export function installHintError(headline: string): Error {
-  const lines = [
-    headline,
-    "",
-    "╔══════════════════════════════════════════════════════════╗",
-    "║ Please run the following command to get started:         ║",
-    "║                                                          ║",
-    "║     bunx @drakulavich/parakeet-cli install               ║",
-    "╚══════════════════════════════════════════════════════════╝",
-  ];
-  return new Error(lines.join("\n"));
-}
-
-export function requireModel(modelDir?: string): string {
-  const dir = modelDir ?? getModelDir();
-
-  if (!isModelCached(dir)) {
-    throw installHintError(`Error: Model not found at ${dir}`);
-  }
-
-  return dir;
-}
-
-export async function downloadModel(noCache = false, modelDir?: string): Promise<string> {
-  const dir = modelDir ?? getModelDir();
-
-  if (!noCache && isModelCached(dir)) {
-    console.log("Model already downloaded.");
-    return dir;
-  }
-
-  mkdirSync(dir, { recursive: true });
-
-  for (const file of MODEL_FILES) {
-    const url = `https://huggingface.co/${HF_REPO}/resolve/main/${file}`;
-    const dest = join(dir, file);
-
-    if (!noCache && existsSync(dest)) continue;
-
-    console.error(`Downloading ${file}...`);
-
-    let res: Response;
-    try {
-      res = await fetch(url, { redirect: "follow" });
-    } catch (e) {
-      throw new Error(`failed to fetch ${file}: ${e instanceof Error ? e.message : e}`);
-    }
-
-    if (!res.ok) {
-      throw new Error(`failed to download ${file}: HTTP ${res.status}`);
-    }
-
-    if (!res.body) {
-      throw new Error(`empty response body for ${file}`);
-    }
-
-    const writer = Bun.file(dest).writer();
-    let bytes = 0;
-    try {
-      for await (const chunk of res.body) {
-        writer.write(chunk);
-        bytes += chunk.length;
-      }
-    } finally {
-      writer.end();
-    }
-
-    if (bytes === 0) {
-      throw new Error(`downloaded 0 bytes for ${file}`);
-    }
-  }
-
-  console.log("Model downloaded successfully.");
-  return dir;
-}
-
-const COREML_BINARY_NAME = "parakeet-coreml-darwin-arm64";
-const GITHUB_REPO = "drakulavich/parakeet-cli";
-
-export function getCoreMLDownloadURL(version: string): string {
-  return `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${COREML_BINARY_NAME}`;
-}
-
-export function getCoreMLLatestDownloadURL(): string {
-  return `https://github.com/${GITHUB_REPO}/releases/latest/download/${COREML_BINARY_NAME}`;
-}
-
-export async function downloadCoreML(noCache = false): Promise<string> {
-  const { getCoreMLBinPath } = await import("./coreml");
-  const binPath = getCoreMLBinPath();
-
-  if (!noCache && existsSync(binPath)) {
-    // Binary exists — ensure models are also downloaded
-    const checkProc = Bun.spawnSync([binPath, "--download-only"], {
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    if (checkProc.exitCode === 0) {
-      console.log("CoreML backend already installed.");
-      return binPath;
-    }
-    // Models missing — continue to re-download
-  }
-
-  // Try latest release first, fall back to version-specific
-  const latestUrl = getCoreMLLatestDownloadURL();
-  console.error("Downloading parakeet-coreml binary...");
-
-  let res = await fetch(latestUrl, { redirect: "follow" });
-
-  if (!res.ok) {
-    const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
-    const versionUrl = getCoreMLDownloadURL(pkg.version);
-    res = await fetch(versionUrl, { redirect: "follow" });
-  }
-
-  if (!res.ok) {
-    throw new Error(`Failed to download CoreML binary (HTTP ${res.status}). No release found with ${COREML_BINARY_NAME}.`);
-  }
-
-  mkdirSync(dirname(binPath), { recursive: true });
-
-  await Bun.write(binPath, res);
-
-  chmodSync(binPath, 0o755);
-
-  // Download CoreML model files (first transcription would be slow without this)
-  console.error("Downloading CoreML models...");
-  const downloadProc = Bun.spawnSync([binPath, "--download-only"], {
-    stdout: "inherit",
-    stderr: "inherit",
-  });
-
-  if (downloadProc.exitCode !== 0) {
-    throw new Error("Failed to download CoreML models");
-  }
-
-  console.log("CoreML backend installed successfully.");
-  return binPath;
-}

package/src/onnx-install.ts

@@ -0,0 +1,98 @@
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, mkdirSync } from "fs";
+
+export const HF_REPO = "istupakov/parakeet-tdt-0.6b-v3-onnx";
+
+export const MODEL_FILES = [
+  "encoder-model.onnx",
+  "encoder-model.onnx.data",
+  "decoder_joint-model.onnx",
+  "nemo128.onnx",
+  "vocab.txt",
+];
+
+export function getModelDir(): string {
+  return join(homedir(), ".cache", "parakeet", "v3");
+}
+
+export function isModelCached(dir?: string): boolean {
+  const resolvedDir = dir ?? getModelDir();
+  return MODEL_FILES.every((file) => existsSync(join(resolvedDir, file)));
+}
+
+export function installHintError(headline: string): Error {
+  const lines = [
+    headline,
+    "",
+    "╔══════════════════════════════════════════════════════════╗",
+    "║ Please run the following command to get started:         ║",
+    "║                                                          ║",
+    "║     bunx @drakulavich/parakeet-cli install               ║",
+    "╚══════════════════════════════════════════════════════════╝",
+  ];
+  return new Error(lines.join("\n"));
+}
+
+export function requireModel(modelDir?: string): string {
+  const dir = modelDir ?? getModelDir();
+
+  if (!isModelCached(dir)) {
+    throw installHintError(`Error: Model not found at ${dir}`);
+  }
+
+  return dir;
+}
+
+export async function downloadModel(noCache = false, modelDir?: string): Promise<string> {
+  const dir = modelDir ?? getModelDir();
+
+  if (!noCache && isModelCached(dir)) {
+    console.log("Model already downloaded.");
+    return dir;
+  }
+
+  mkdirSync(dir, { recursive: true });
+
+  for (const file of MODEL_FILES) {
+    const url = `https://huggingface.co/${HF_REPO}/resolve/main/${file}`;
+    const dest = join(dir, file);
+
+    if (!noCache && existsSync(dest)) continue;
+
+    console.error(`Downloading ${file}...`);
+
+    let res: Response;
+    try {
+      res = await fetch(url, { redirect: "follow" });
+    } catch (e) {
+      throw new Error(`failed to fetch ${file}: ${e instanceof Error ? e.message : e}`);
+    }
+
+    if (!res.ok) {
+      throw new Error(`failed to download ${file}: HTTP ${res.status}`);
+    }
+
+    if (!res.body) {
+      throw new Error(`empty response body for ${file}`);
+    }
+
+    const writer = Bun.file(dest).writer();
+    let bytes = 0;
+    try {
+      for await (const chunk of res.body) {
+        writer.write(chunk);
+        bytes += chunk.length;
+      }
+    } finally {
+      writer.end();
+    }
+
+    if (bytes === 0) {
+      throw new Error(`downloaded 0 bytes for ${file}`);
+    }
+  }
+
+  console.log("Model downloaded successfully.");
+  return dir;
+}

package/src/transcribe.ts

@@ -1,4 +1,4 @@
-import { requireModel, isModelCached, installHintError } from "./models";
+import { requireModel, isModelCached, installHintError } from "./onnx-install";
 import { isCoreMLInstalled, transcribeCoreML } from "./coreml";
 import { convertToFloat32PCM } from "./audio";
 import { initPreprocessor, preprocess } from "./preprocess";

package/src/__tests__/models.test.ts

@@ -1,30 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { getModelDir, MODEL_FILES, HF_REPO, getCoreMLDownloadURL } from "../models";
-import { join } from "path";
-import { homedir } from "os";
-
-describe("models", () => {
-  test("getModelDir returns correct cache path", () => {
-    const dir = getModelDir();
-    expect(dir).toBe(join(homedir(), ".cache", "parakeet", "v3"));
-  });
-
-  test("MODEL_FILES lists required files", () => {
-    expect(MODEL_FILES).toContain("encoder-model.onnx");
-    expect(MODEL_FILES).toContain("encoder-model.onnx.data");
-    expect(MODEL_FILES).toContain("decoder_joint-model.onnx");
-    expect(MODEL_FILES).toContain("nemo128.onnx");
-    expect(MODEL_FILES).toContain("vocab.txt");
-  });
-
-  test("HF_REPO points to v3 ONNX repo", () => {
-    expect(HF_REPO).toBe("istupakov/parakeet-tdt-0.6b-v3-onnx");
-  });
-
-  test("getCoreMLDownloadURL includes version and correct filename", () => {
-    const url = getCoreMLDownloadURL("0.5.0");
-    expect(url).toBe(
-      "https://github.com/drakulavich/parakeet-cli/releases/download/v0.5.0/parakeet-coreml-darwin-arm64"
-    );
-  });
-});

package/src/__tests__/transcribe.test.ts

@@ -1,11 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { transcribe } from "../transcribe";
-
-describe("transcribe", () => {
-  test("returns empty string for very short audio", async () => {
-    // Audio < 0.1s (1600 samples) should return empty
-    // We can't easily test this without a fixture, so this is a smoke test
-    // that the module exports correctly
-    expect(typeof transcribe).toBe("function");
-  });
-});