@drakulavich/parakeet-cli 0.7.4 → 0.8.1

package/README.md

@@ -117,4 +117,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 
-MIT
+Made with 💛🩵 Published under MIT License.

package/bin/parakeet.js

@@ -1,2 +1,4 @@
 #!/usr/bin/env bun
-await import("../src/cli.ts");
+import { runCli } from "../src/cli.ts";
+
+await runCli();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/parakeet-cli",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "description": "Fast local speech-to-text CLI. CoreML on Apple Silicon, ONNX on CPU. 25 languages.",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
   ],
   "scripts": {
     "test": "bun test",
-    "test:unit": "bun test src/__tests__/",
+    "test:unit": "bun test tests/unit/",
     "test:integration": "bun test tests/integration/"
   },
   "keywords": [
@@ -53,7 +53,9 @@
     "typescript": "^6.0.2"
   },
   "dependencies": {
+    "citty": "^0.2.2",
     "onnxruntime-node": "^1.24.0",
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "tinyld": "^1.3.4"
   }
 }

package/src/audio.ts

@@ -55,7 +55,10 @@ async function convertAudioWithFfmpeg(
   ]);
 
   if (exitCode !== 0) {
-    throw new Error(`failed to convert audio: ${stderr.trim().split("\n").pop()}`);
+    const lastLine = stderr.trim().split("\n").pop() ?? "unknown error";
+    throw new Error(
+      `Audio conversion failed: ${lastLine}\n  File: ${inputPath}\n  Fix: Ensure the file is a valid audio format. Run "ffmpeg -i ${inputPath}" to diagnose.`,
+    );
   }
 
   return tmpPath;

package/src/cli.ts

@@ -1,60 +1,74 @@
 #!/usr/bin/env bun
 
+import { defineCommand, runMain } from "citty";
+import { detect } from "tinyld";
 import { transcribe } from "./lib";
 import { downloadModel } from "./onnx-install";
 import { downloadCoreML } from "./coreml-install";
 import { isMacArm64 } from "./coreml";
 import { log } from "./log";
+import { showStatus } from "./status";
 
-async function main(): Promise<void> {
-  const args = process.argv.slice(2);
+export function detectLanguage(text: string): string {
+  if (!text) return "";
+  return detect(text);
+}
+
+export function checkLanguageMismatch(expected: string | undefined, detected: string): string | null {
+  if (!expected || !detected || expected === detected) return null;
+  return `warning: expected language "${expected}" but detected "${detected}"`;
+}
+
+export interface InstallOptions {
+  coreml: boolean;
+  onnx: boolean;
+  noCache: boolean;
+}
+
+interface InstallCommandArgs {
+  coreml: boolean;
+  onnx: boolean;
+  "no-cache": boolean;
+}
+
+interface MainCommandArgs {
+  _: string[];
+  json: boolean;
+  lang?: string;
+}
 
-  if (args.includes("--version")) {
-    const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
-    console.log(pkg.version);
-    process.exit(0);
+const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+
+export function resolveInstallBackend(options: InstallOptions, macArm64 = isMacArm64()): "coreml" | "onnx" {
+  const { coreml, onnx } = options;
+
+  if (coreml && onnx) {
+    throw new Error('Choose only one backend: "--coreml" or "--onnx".');
   }
 
-  const positional = args.filter((a) => !a.startsWith("--"));
-
-  if (positional[0] === "install") {
-    const noCache = args.includes("--no-cache");
-    const forceCoreML = args.includes("--coreml");
-    const forceOnnx = args.includes("--onnx");
-
-    try {
-      if (forceCoreML) {
-        if (!isMacArm64()) {
-          log.error("CoreML backend is only available on macOS Apple Silicon.");
-          process.exit(1);
-        }
-        await downloadCoreML(noCache);
-      } else if (forceOnnx) {
-        await downloadModel(noCache);
-      } else if (isMacArm64()) {
-        await downloadCoreML(noCache);
-      } else {
-        await downloadModel(noCache);
-      }
-    } catch (err: unknown) {
-      const message = err instanceof Error ? err.message : String(err);
-      log.error(message);
-      process.exit(1);
+  if (coreml) {
+    if (!macArm64) {
+      throw new Error("CoreML backend is only available on macOS Apple Silicon.");
     }
-    process.exit(0);
+    return "coreml";
   }
 
-  const file = positional[0];
-
-  if (!file) {
-    log.info("Usage: parakeet [--version] <audio_file>");
-    log.info("       parakeet install [--coreml | --onnx] [--no-cache]");
-    process.exit(1);
+  if (onnx) {
+    return "onnx";
   }
 
+  return macArm64 ? "coreml" : "onnx";
+}
+
+async function performInstall(options: InstallOptions) {
+  const { noCache } = options;
   try {
-    const text = await transcribe(file);
-    if (text) process.stdout.write(text + "\n");
+    const backend = resolveInstallBackend(options);
+    if (backend === "coreml") {
+      await downloadCoreML(noCache);
+    } else {
+      await downloadModel(noCache);
+    }
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
     log.error(message);
@@ -62,4 +76,131 @@ async function main(): Promise<void> {
   }
 }
 
-main();
+export const installCommand = defineCommand({
+  meta: {
+    name: "install",
+    description: "Download speech-to-text models",
+  },
+  args: {
+    coreml: {
+      type: "boolean",
+      description: "Force CoreML backend (macOS arm64)",
+      default: false,
+    },
+    onnx: {
+      type: "boolean",
+      description: "Force ONNX backend",
+      default: false,
+    },
+    "no-cache": {
+      type: "boolean",
+      description: "Re-download even if cached",
+      default: false,
+    },
+  },
+  async run({ args }: { args: InstallCommandArgs }) {
+    await performInstall({ coreml: args.coreml, onnx: args.onnx, noCache: args["no-cache"] });
+  },
+});
+
+export const statusCommand = defineCommand({
+  meta: {
+    name: "status",
+    description: "Show backend installation status",
+  },
+  async run() {
+    await showStatus();
+  },
+});
+
+export const mainCommand = defineCommand({
+  meta: {
+    name: "parakeet",
+    version: pkg.version,
+    description:
+      "Fast local speech-to-text. 25 languages. CoreML on Apple Silicon, ONNX on CPU.\n" +
+      "  Run 'parakeet install [--coreml | --onnx] [--no-cache]' to download models.\n" +
+      "  Run 'parakeet status' to inspect installed backends.",
+  },
+  args: {
+    json: {
+      type: "boolean",
+      description: "Output results as JSON",
+      default: false,
+    },
+    lang: {
+      type: "string",
+      description: "Expected language code (ISO 639-1), warn if mismatch",
+    },
+  },
+  async run({ args }: { args: MainCommandArgs }) {
+    const files = args._;
+
+    if (files.length === 0) {
+      log.info("Usage: parakeet <audio_file> [audio_file ...]\n       parakeet install [--coreml | --onnx] [--no-cache]\n       parakeet status");
+      process.exit(1);
+    }
+
+    let hasError = false;
+    const results: TranscribeResult[] = [];
+
+    for (const file of files) {
+      try {
+        const text = await transcribe(file);
+        const lang = detectLanguage(text);
+
+        const mismatchWarning = checkLanguageMismatch(args.lang, lang);
+        if (mismatchWarning) log.warn(`${file}: ${mismatchWarning}`);
+
+        results.push({ file, text, lang });
+      } catch (err: unknown) {
+        hasError = true;
+        const message = err instanceof Error ? err.message : String(err);
+        log.error(`${file}: ${message}`);
+      }
+    }
+
+    if (args.json) {
+      process.stdout.write(formatJsonOutput(results));
+    } else {
+      process.stdout.write(formatTextOutput(results));
+    }
+
+    if (hasError) process.exit(1);
+  },
+});
+
+export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
+  const [firstArg, ...restArgs] = rawArgs;
+
+  if (firstArg === "install") {
+    await runMain(installCommand, { rawArgs: restArgs });
+    return;
+  }
+
+  if (firstArg === "status") {
+    await runMain(statusCommand, { rawArgs: restArgs });
+    return;
+  }
+
+  await runMain(mainCommand, { rawArgs });
+}
+
+export type TranscribeResult = { file: string; text: string; lang: string };
+
+export function formatTextOutput(results: TranscribeResult[]): string {
+  if (results.length === 1) {
+    return results[0].text + "\n";
+  }
+  return results
+    .map((r, i) => (i > 0 ? "\n" : "") + `=== ${r.file} ===\n${r.text}\n`)
+    .join("");
+}
+
+export function formatJsonOutput(results: TranscribeResult[]): string {
+  return JSON.stringify(results, null, 2) + "\n";
+}
+
+if (import.meta.main) {
+  await runCli();
+}

package/src/coreml-install.ts

@@ -3,6 +3,7 @@ import { homedir } from "os";
 import { existsSync, mkdirSync, chmodSync } from "fs";
 import { getCoreMLBinPath } from "./coreml";
 import { log } from "./log";
+import { streamResponseToFile } from "./progress";
 
 const COREML_BINARY_NAME = "parakeet-coreml-darwin-arm64";
 const GITHUB_REPO = "drakulavich/parakeet-cli";
@@ -84,6 +85,18 @@ export function getCoreMLLatestDownloadURL(): string {
   return `https://github.com/${GITHUB_REPO}/releases/latest/download/${COREML_BINARY_NAME}`;
 }
 
+export function isUnreleasedVersion(version: string): boolean {
+  return version === "0.0.0" || version.includes("-");
+}
+
+export function getCoreMLBinaryDownloadCandidates(version: string): string[] {
+  const versionUrl = getCoreMLDownloadURL(version);
+  if (isUnreleasedVersion(version)) {
+    return [getCoreMLLatestDownloadURL(), versionUrl];
+  }
+  return [versionUrl];
+}
+
 export function getCoreMLInstallState(opts?: {
   binPath?: string;
   exists?: (path: string) => boolean;
@@ -164,22 +177,21 @@ export function classifyCoreMLInstallProbe(exitCode: number, stdout: string): Co
 }
 
 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" });
+  const version = typeof pkg.version === "string" ? pkg.version : "unknown";
 
-  if (!res.ok) {
-    throw new Error(`Failed to download CoreML binary (HTTP ${res.status}). No release found with ${COREML_BINARY_NAME}.`);
+  let lastStatus: number | null = null;
+  for (const url of getCoreMLBinaryDownloadCandidates(version)) {
+    const res = await fetch(url, { redirect: "follow" });
+    if (res.ok) {
+      return res;
+    }
+    lastStatus = res.status;
   }
 
-  return res;
+  throw new Error(
+    `Failed to download CoreML binary${lastStatus ? ` (HTTP ${lastStatus})` : ""}\n  Requested package version: ${version}\n  Fix: Check https://github.com/drakulavich/parakeet-cli/releases for available versions\n       Or install the ONNX backend instead: parakeet install --onnx`,
+  );
 }
 
 export function getCoreMLInstallStatus(
@@ -232,10 +244,9 @@ export async function downloadCoreML(
   }
 
   if (plan.downloadBinary) {
-    log.progress("Downloading parakeet-coreml binary...");
     const res = await fetchCoreMLBinary();
     mkdirSync(dirname(binPath), { recursive: true });
-    await Bun.write(binPath, res);
+    await streamResponseToFile(res, binPath, "parakeet-coreml binary");
     chmodSync(binPath, 0o755);
   }
 

package/src/lib.ts

@@ -14,5 +14,5 @@ export async function transcribe(
     throw new Error(`File not found: ${audioPath}`);
   }
 
-  return internalTranscribe(audioPath, options);
+  return internalTranscribe(audioPath, { ...options, silent: true });
 }

package/src/onnx-install.ts

@@ -2,6 +2,7 @@ import { join } from "path";
 import { homedir } from "os";
 import { existsSync, mkdirSync } from "fs";
 import { log } from "./log";
+import { streamResponseToFile } from "./progress";
 
 export const HF_REPO = "istupakov/parakeet-tdt-0.6b-v3-onnx";
 
@@ -61,36 +62,27 @@ export async function downloadModel(noCache = false, modelDir?: string): Promise
 
     if (!noCache && existsSync(dest)) continue;
 
-    log.progress(`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}`);
+      throw new Error(
+        `Failed to fetch ${file}: ${e instanceof Error ? e.message : e}\n  Fix: Check your network connection and try again`,
+      );
     }
 
     if (!res.ok) {
-      throw new Error(`failed to download ${file}: HTTP ${res.status}`);
-    }
-
-    if (!res.body) {
-      throw new Error(`empty response body for ${file}`);
+      throw new Error(
+        `Failed to download ${file}: HTTP ${res.status}\n  Fix: Check your network connection or try again with --no-cache`,
+      );
     }
 
-    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();
-    }
+    const bytes = await streamResponseToFile(res, dest, file);
 
     if (bytes === 0) {
-      throw new Error(`downloaded 0 bytes for ${file}`);
+      throw new Error(
+        `Downloaded 0 bytes for ${file}\n  Fix: Try again — the server may be temporarily unavailable`,
+      );
     }
   }
 

package/src/progress.ts

@@ -0,0 +1,80 @@
+import { log } from "./log";
+
+const BAR_WIDTH = 20;
+
+export function formatBytes(bytes: number): string {
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+export function formatProgressBar(label: string, downloaded: number, total: number): string {
+  const pct = total <= 0 ? 0 : Math.min(100, Math.floor((downloaded / total) * 100));
+  const filled = Math.round((pct / 100) * BAR_WIDTH);
+  const empty = BAR_WIDTH - filled;
+  const bar = "█".repeat(filled) + "░".repeat(empty);
+  return `${label}  [${bar}] ${pct}%  ${formatBytes(downloaded)}/${formatBytes(total)}`;
+}
+
+export async function streamResponseToFile(
+  res: Response,
+  destPath: string,
+  label: string,
+): Promise<number> {
+  if (!res.body) {
+    throw new Error(
+      `Download failed: empty response for ${label}\n  Fix: Try again — the server may be temporarily unavailable`,
+    );
+  }
+
+  const totalBytes = Number(res.headers.get("content-length") || 0);
+  const progress = createProgressBar(label, totalBytes);
+
+  const writer = Bun.file(destPath).writer();
+  let bytes = 0;
+  try {
+    for await (const chunk of res.body) {
+      writer.write(chunk);
+      bytes += chunk.length;
+      progress.update(chunk.length);
+    }
+  } finally {
+    writer.end();
+  }
+
+  progress.finish();
+  return bytes;
+}
+
+export function createProgressBar(label: string, totalBytes: number): {
+  update(downloadedBytes: number): void;
+  finish(): void;
+} {
+  const isTTY = process.stderr.isTTY;
+
+  if (!isTTY || totalBytes <= 0) {
+    const sizeInfo = totalBytes > 0 ? ` (${formatBytes(totalBytes)})` : "";
+    log.progress(`Downloading ${label}${sizeInfo}...`);
+    return {
+      update() {},
+      finish() {
+        log.success(`Downloaded ${label} ✓`);
+      },
+    };
+  }
+
+  let current = 0;
+  let lastPct = -1;
+  return {
+    update(downloadedBytes: number) {
+      current += downloadedBytes;
+      const pct = totalBytes > 0 ? Math.floor((current / totalBytes) * 100) : 0;
+      if (pct === lastPct) return;
+      lastPct = pct;
+      const line = formatProgressBar(label, current, totalBytes);
+      process.stderr.write(`\r${line}`);
+    },
+    finish() {
+      const line = formatProgressBar(label, totalBytes, totalBytes);
+      process.stderr.write(`\r${line}\n`);
+    },
+  };
+}

package/src/status.ts

@@ -0,0 +1,175 @@
+import { isMacArm64, getCoreMLBinPath } from "./coreml";
+import { isModelCached, getModelDir } from "./onnx-install";
+import { getCoreMLInstallState, getCoreMLInstallStatus, getCoreMLSupportDir, type CoreMLInstallState } from "./coreml-install";
+import { log } from "./log";
+import pc from "picocolors";
+
+export type StatusCoreMLState = CoreMLInstallState | "n/a" | "probe-failed";
+export type StatusPlatform = "mac-arm64" | "other";
+
+export function formatStatusLine(
+  label: string,
+  path: string | null,
+  installed: boolean,
+  missingLabel = "not installed",
+): string {
+  const status = installed ? pc.green("✓") : pc.red(`✗ ${missingLabel}`);
+  const pathStr = path ?? "";
+  const padding = " ".repeat(Math.max(1, 50 - label.length - pathStr.length));
+  return `  ${label}:${pathStr ? `   ${pathStr}` : ""}${padding}${status}`;
+}
+
+export interface StatusInfo {
+  onnx: boolean;
+  coreml: StatusCoreMLState;
+  ffmpeg: boolean;
+  platform: StatusPlatform;
+}
+
+export function collectSuggestions(info: StatusInfo): string[] {
+  const suggestions: string[] = [];
+
+  if (info.platform === "mac-arm64") {
+    if (info.coreml === "missing") {
+      suggestions.push(`Run "parakeet install --coreml" to install the CoreML backend.`);
+    } else if (info.coreml === "binary-only") {
+      suggestions.push(`Run "parakeet install --coreml" to download CoreML models.`);
+    } else if (info.coreml === "stale-binary") {
+      suggestions.push(`Run "parakeet install --coreml --no-cache" to refresh the incompatible CoreML binary.`);
+    } else if (info.coreml === "probe-failed") {
+      suggestions.push(`Run "parakeet install --coreml --no-cache" to refresh the CoreML backend and restore status checks.`);
+    }
+    return suggestions;
+  }
+
+  if (!info.onnx) {
+    suggestions.push(`Run "parakeet install --onnx" to install the ONNX backend.`);
+  }
+
+  if (!info.ffmpeg) {
+    suggestions.push(`Install ffmpeg for ONNX audio conversion (see "parakeet install" output for instructions).`);
+  }
+
+  return suggestions;
+}
+
+export interface StatusDeps {
+  isMacArm64: () => boolean;
+  getCoreMLBinPath: () => string;
+  getCoreMLState: (binPath: string) => CoreMLInstallState;
+  getCoreMLSupportDir: () => string;
+  isModelCached: () => boolean;
+  getModelDir: () => string;
+  whichFfmpeg: () => string | null;
+  bunVersion: string;
+  platform: string;
+}
+
+function defaultDeps(): StatusDeps {
+  return {
+    isMacArm64,
+    getCoreMLBinPath,
+    getCoreMLState: (binPath) => getCoreMLInstallState({
+      binPath,
+      verifyReady: (path) => getCoreMLInstallStatus(path),
+    }),
+    getCoreMLSupportDir,
+    isModelCached,
+    getModelDir,
+    whichFfmpeg: () => Bun.which("ffmpeg"),
+    bunVersion: Bun.version,
+    platform: `${process.platform} ${process.arch}`,
+  };
+}
+
+function getCoreMLBinaryDisplay(state: StatusCoreMLState): { installed: boolean; missingLabel: string } {
+  switch (state) {
+    case "ready":
+    case "binary-only":
+      return { installed: true, missingLabel: "not installed" };
+    case "stale-binary":
+      return { installed: false, missingLabel: "stale binary" };
+    case "probe-failed":
+      return { installed: false, missingLabel: "probe failed" };
+    case "missing":
+    case "n/a":
+      return { installed: false, missingLabel: "not installed" };
+  }
+}
+
+function getCoreMLModelsDisplay(state: StatusCoreMLState): { installed: boolean; missingLabel: string } {
+  switch (state) {
+    case "ready":
+      return { installed: true, missingLabel: "not installed" };
+    case "stale-binary":
+      return { installed: false, missingLabel: "reinstall required" };
+    case "probe-failed":
+      return { installed: false, missingLabel: "status unknown" };
+    case "binary-only":
+    case "missing":
+    case "n/a":
+      return { installed: false, missingLabel: "not installed" };
+  }
+}
+
+export async function showStatus(deps?: Partial<StatusDeps>): Promise<void> {
+  const d = { ...defaultDeps(), ...deps };
+
+  const isMac = d.isMacArm64();
+  const platform: StatusPlatform = isMac ? "mac-arm64" : "other";
+
+  // CoreML status
+  let coremlState: StatusCoreMLState = "n/a";
+  let coremlProbeError: string | null = null;
+  if (isMac) {
+    const binPath = d.getCoreMLBinPath();
+    try {
+      coremlState = d.getCoreMLState(binPath);
+    } catch (error: unknown) {
+      coremlState = "probe-failed";
+      coremlProbeError = error instanceof Error ? error.message : String(error);
+    }
+
+    log.info("CoreML (macOS Apple Silicon):");
+    const binaryDisplay = getCoreMLBinaryDisplay(coremlState);
+    log.info(formatStatusLine("Binary", coremlState === "missing" ? null : binPath, binaryDisplay.installed, binaryDisplay.missingLabel));
+
+    const modelsDisplay = getCoreMLModelsDisplay(coremlState);
+    const modelDir = d.getCoreMLSupportDir();
+    const modelsPath = (coremlState === "ready" || coremlState === "stale-binary" || coremlState === "probe-failed") ? modelDir : null;
+    log.info(formatStatusLine("Models", modelsPath, modelsDisplay.installed, modelsDisplay.missingLabel));
+    log.info("");
+
+    if (coremlProbeError) {
+      log.warn(`CoreML status probe failed: ${coremlProbeError}`);
+    }
+  }
+
+  // ONNX status
+  const modelDir = d.getModelDir();
+  const onnxInstalled = d.isModelCached();
+  log.info("ONNX:");
+  log.info(formatStatusLine("Models", onnxInstalled ? modelDir : null, onnxInstalled));
+  log.info("");
+
+  // ffmpeg
+  const ffmpegPath = d.whichFfmpeg();
+  log.info(formatStatusLine("ffmpeg", ffmpegPath, !!ffmpegPath, "not found"));
+
+  // Runtime info
+  log.info(formatStatusLine("Runtime", `Bun ${d.bunVersion}`, true));
+  log.info(formatStatusLine("Platform", d.platform, true));
+  log.info("");
+
+  // Suggestions
+  const suggestions = collectSuggestions({
+    onnx: onnxInstalled,
+    coreml: coremlState,
+    ffmpeg: !!ffmpegPath,
+    platform,
+  });
+
+  for (const suggestion of suggestions) {
+    log.warn(suggestion);
+  }
+}

package/src/transcribe.ts

@@ -1,5 +1,6 @@
 import { requireModel, isModelCached, installHintError } from "./onnx-install";
-import { isCoreMLInstalled, transcribeCoreML } from "./coreml";
+import { isCoreMLInstalled, transcribeCoreML, isMacArm64 } from "./coreml";
+import { log } from "./log";
 import { convertToFloat32PCM } from "./audio";
 import { initPreprocessor, preprocess } from "./preprocess";
 import { initEncoder, encode } from "./encoder";
@@ -28,6 +29,7 @@ const DECODER_HIDDEN = 640;
 export interface TranscribeOptions {
   beamWidth?: number;
   modelDir?: string;
+  silent?: boolean;
 }
 
 // Minimum 0.1s of audio at 16kHz to produce meaningful output
@@ -38,6 +40,10 @@ export async function transcribe(audioPath: string, opts: TranscribeOptions = {}
     return transcribeCoreML(audioPath);
   }
 
+  if (!opts.silent && isMacArm64()) {
+    log.warn("CoreML backend unavailable, falling back to ONNX");
+  }
+
   if (isModelCached(opts.modelDir)) {
     return transcribeOnnx(audioPath, opts);
   }
@@ -49,6 +55,9 @@ async function transcribeOnnx(audioPath: string, opts: TranscribeOptions): Promi
   const audio = await convertToFloat32PCM(audioPath);
 
   if (audio.length < MIN_AUDIO_SAMPLES) {
+    if (!opts.silent) {
+      log.warn(`Audio too short (< 0.1s), skipping: ${audioPath}`);
+    }
     return "";
   }
 

package/src/__tests__/audio.test.ts

@@ -1,36 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { getFfmpegInstallHint, assertFfmpegExists, resetFfmpegCheck } from "../audio";
-
-describe("getFfmpegInstallHint", () => {
-  test("returns a non-empty string", () => {
-    const hint = getFfmpegInstallHint();
-    expect(hint).toBeTruthy();
-    expect(typeof hint).toBe("string");
-  });
-
-  test("contains install keyword", () => {
-    const hint = getFfmpegInstallHint();
-    expect(hint).toMatch(/install|ffmpeg\.org/i);
-  });
-});
-
-describe("assertFfmpegExists", () => {
-  test("includes install hint when ffmpeg is missing", () => {
-    // Save and override Bun.which to simulate missing ffmpeg
-    const originalWhich = Bun.which;
-    Bun.which = ((cmd: string) => {
-      if (cmd === "ffmpeg") return null;
-      return originalWhich(cmd);
-    }) as typeof Bun.which;
-
-    // Reset the cached check so assertFfmpegExists re-checks
-    resetFfmpegCheck();
-
-    try {
-      expect(() => assertFfmpegExists()).toThrow(/Install it:/);
-    } finally {
-      Bun.which = originalWhich;
-      resetFfmpegCheck();
-    }
-  });
-});

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

@@ -1,67 +0,0 @@
-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

@@ -1,281 +0,0 @@
-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,24 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import {
-  shouldRetryCoreMLWithWav,
-} from "../coreml";
-
-describe("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("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__/decoder.test.ts

@@ -1,50 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { beamDecode, type DecoderSession } from "../decoder";
-
-function mockSession(responses: Array<{ tokenLogits: number[]; durationLogits: number[] }>): DecoderSession {
-  let callIndex = 0;
-  return {
-    async decode(_encoderFrame, _targets, _targetLength, _state1, _state2) {
-      const resp = responses[Math.min(callIndex++, responses.length - 1)];
-      const output = new Float32Array([...resp.tokenLogits, ...resp.durationLogits]);
-      const state1 = new Float32Array(1);
-      const state2 = new Float32Array(1);
-      return { output, state1, state2 };
-    },
-    vocabSize: responses[0]?.tokenLogits.length ?? 4,
-    blankId: (responses[0]?.tokenLogits.length ?? 4) - 1,
-    stateDims: { layers: 1, hidden: 1 },
-  };
-}
-
-describe("decoder", () => {
-  test("emits non-blank tokens", async () => {
-    const session = mockSession([
-      { tokenLogits: [10, 0, 0, -10], durationLogits: [10, 0] },
-      { tokenLogits: [0, 10, 0, -10], durationLogits: [10, 0] },
-      { tokenLogits: [0, 0, 0, 10], durationLogits: [10, 0] },
-    ]);
-    const encoderData = new Float32Array(3);
-    const tokens = await beamDecode(session, 3, encoderData, 1, 1);
-    expect(tokens).toEqual([0, 1]);
-  });
-
-  test("respects duration skipping", async () => {
-    const session = mockSession([
-      { tokenLogits: [10, 0, 0, -10], durationLogits: [0, 0, 10] },
-      { tokenLogits: [0, 10, 0, -10], durationLogits: [10, 0, 0] },
-      { tokenLogits: [0, 0, 0, 10], durationLogits: [10, 0, 0] },
-    ]);
-    const encoderData = new Float32Array(5);
-    const tokens = await beamDecode(session, 5, encoderData, 1, 1);
-    expect(tokens).toEqual([0, 1]);
-  });
-
-  test("returns empty for zero-length encoder output", async () => {
-    const session = mockSession([
-      { tokenLogits: [0, 0, 0, 10], durationLogits: [10, 0] },
-    ]);
-    const tokens = await beamDecode(session, 0, new Float32Array(0), 1);
-    expect(tokens).toEqual([]);
-  });
-});

package/src/__tests__/lib.test.ts

@@ -1,8 +0,0 @@
-import { describe, expect, it } from "bun:test";
-import { transcribe } from "../lib";
-
-describe("lib API", () => {
-  it("rejects missing file", async () => {
-    await expect(transcribe("/nonexistent/audio.wav")).rejects.toThrow("File not found");
-  });
-});

package/src/__tests__/tokenizer.test.ts

@@ -1,41 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { Tokenizer } from "../tokenizer";
-
-describe("tokenizer", () => {
-  test("loads vocab from file", async () => {
-    const tok = await Tokenizer.fromFile("fixtures/test-vocab.txt");
-    expect(tok.vocabSize).toBe(6);
-    expect(tok.blankId).toBe(5);
-  });
-
-  test("detokenizes token IDs to text", async () => {
-    const tok = await Tokenizer.fromFile("fixtures/test-vocab.txt");
-    const text = tok.detokenize([0, 1]);
-    expect(text).toBe("hello world");
-  });
-
-  test("handles blank tokens by skipping them", async () => {
-    const tok = await Tokenizer.fromFile("fixtures/test-vocab.txt");
-    const text = tok.detokenize([0, 5, 1]);
-    expect(text).toBe("hello world");
-  });
-
-  test("handles empty token list", async () => {
-    const tok = await Tokenizer.fromFile("fixtures/test-vocab.txt");
-    const text = tok.detokenize([]);
-    expect(text).toBe("");
-  });
-
-  test("handles only blank tokens", async () => {
-    const tok = await Tokenizer.fromFile("fixtures/test-vocab.txt");
-    const text = tok.detokenize([5, 5, 5]);
-    expect(text).toBe("");
-  });
-
-  test("joins subword tokens correctly", async () => {
-    const tok = await Tokenizer.fromFile("fixtures/test-vocab.txt");
-    const text = tok.detokenize([3, 4]);
-    expect(text).toBe("cats");
-  });
-
-});