@drakulavich/parakeet-cli 0.3.0 → 0.5.3

package/README.md

@@ -1,13 +1,19 @@
 # parakeet-cli
 
-Fast multilingual speech-to-text CLI powered by NVIDIA Parakeet ONNX models. Zero Python. Runs on CPU.
+[![npm version](https://img.shields.io/npm/v/@drakulavich/parakeet-cli)](https://www.npmjs.com/package/@drakulavich/parakeet-cli)
+[![CI](https://github.com/drakulavich/parakeet-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/drakulavich/parakeet-cli/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Bun](https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun)](https://bun.sh)
+
+Fast multilingual speech-to-text CLI powered by NVIDIA Parakeet models. Zero Python. CoreML on Apple Silicon, ONNX on CPU.
 
 ## Features
 
 - **25 languages** — automatic language detection, no prompting needed
-- **3x faster than Whisper** on CPU (see [benchmark](#benchmark))
-- **Zero Python** — pure TypeScript/Bun with onnxruntime-node
-- **Auto-downloads models** — ~3GB cached in `~/.cache/parakeet/` on first run
+- **~155x real-time on Apple Silicon** — CoreML backend via [FluidAudio](https://github.com/FluidInference/FluidAudio) (1 min audio in ~0.4s)
+- **3x faster than Whisper** on CPU with ONNX fallback (see [benchmark](#benchmark))
+- **Zero Python** — pure TypeScript/Bun, native Swift binary for CoreML
+- **Smart install** — `parakeet install` auto-detects platform: CoreML on macOS arm64, ONNX elsewhere
 - **Any audio format** — ffmpeg handles OGG, MP3, WAV, FLAC, M4A, etc.
 
 ## Install
@@ -38,11 +44,20 @@ bun link
 ## Usage
 
 ```bash
+# Download backend (required before first use)
+# On macOS Apple Silicon: downloads CoreML binary
+# On Linux/other: downloads ONNX models (~3GB)
+parakeet install
+
+# Force a specific backend
+parakeet install --coreml    # CoreML (macOS arm64 only)
+parakeet install --onnx      # ONNX (any platform)
+
 # Transcribe any audio file (language auto-detected)
 parakeet audio.ogg
 
-# Force re-download models
-parakeet --no-cache audio.wav
+# Force re-download
+parakeet install --no-cache
 
 # Show version
 parakeet --version
@@ -52,26 +67,16 @@ Output goes to stdout, errors to stderr. Designed for piping and scripting.
 
 ## Benchmark
 
-Tested on 10 real Telegram voice messages (Russian, 3-10s each).
-VM: AMD EPYC 7763 8C/16T, 64GB RAM, CPU-only.
+10 Telegram voice messages (Russian, 3-10s each) on MacBook Pro M3 Pro:
 
-| # | Whisper | Parakeet | Whisper Transcript | Parakeet Transcript |
-|---|---------|----------|--------------------|---------------------|
-| 1 | 13.3s | 4.4s | Проверь все свои конфиги и перенеси секреты в .env файл. | проверь все свои конфигии и перенеси секреты в дот энф файл |
-| 2 | 13.1s | 4.2s | Вынеси еще секрет от Клода, который я тебе добавил. | неси еще секрет от Клода, который я тебе добавил |
-| 3 | 12.7s | 4.0s | Установи пока Клод Код | Установи пока клот кот |
-| 4 | 13.1s | 4.1s | Какие еще Telegram-юзеры имеют доступ к тебе? | ки еще телеграм юзеры имеют доступ к тебе |
-| 5 | 12.7s | 4.0s | Закомите изменения в ГИТ | Закомить изменения в Гет |
-| 6 | 13.1s | 4.1s | Узнай второго юзера в телеграме. | Узнай второго юзера в Телеграме |
-| 7 | 13.4s | 5.0s | Ты добавил себе в память информацию из Vantage Handbook Репозитория | Ты добавил себе в память информацию из Вентаж хэндбук репозитория |
-| 8 | 13.1s | 4.8s | Покажи его username в телеграмме, хочу написать ему. | жи его юзернейм в телеграме хочу написать ему |
-| 9 | 14.2s | 4.5s | Не нужно посылать сообщение с транскрипцией. Сразу выполняй инструкцию. | жно слать сообщение с транскрипцией сразу выполняй инструкцию |
-| 10 | 13.5s | 4.8s | То, что находится в папке Workspace, ты тоже коммитишь? | То, что находится в папке Воркспейс, ты тоже комитишь? |
-| **Total** | **132.1s** | **43.8s** | | |
+| | faster-whisper (CPU) | Parakeet (CoreML) |
+|---|---|---|
+| **Total time** | 35.3s | 1.9s |
+| **Speedup** | | **~18x faster** |
 
-**Parakeet is 3x faster.** Whisper handles mixed-language words better (`.env`, `Workspace`). Parakeet transliterates them phonetically. Both produce transcripts usable by LLMs.
+Models: faster-whisper medium (int8) vs Parakeet TDT 0.6B v3 (CoreML, Apple Neural Engine).
 
-Models: Whisper medium (int8) vs Parakeet TDT 0.6B v3 (ONNX, CPU).
+See [BENCHMARK.md](BENCHMARK.md) for full results with transcripts. Updated automatically on each release.
 
 ## Supported Languages
 
@@ -79,6 +84,22 @@ Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, G
 
 ## How It Works
 
+### CoreML backend (macOS Apple Silicon)
+
+```
+parakeet audio.ogg
+  |
+  +-- parakeet-coreml (Swift binary via FluidAudio)
+  |   +-- CoreML inference on Apple Neural Engine
+  |   +-- ~155x real-time on M4 Pro
+  |
+  stdout: transcript
+```
+
+Uses [FluidAudio](https://github.com/FluidInference/FluidAudio) with the [CoreML model](https://huggingface.co/FluidInference/parakeet-tdt-0.6b-v3-coreml). CoreML model files are downloaded by FluidAudio on first transcription.
+
+### ONNX backend (cross-platform fallback)
+
 ```
 parakeet audio.ogg
   |
@@ -92,7 +113,7 @@ parakeet audio.ogg
   stdout: transcript
 ```
 
-Uses [NVIDIA Parakeet TDT 0.6B v3](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3) exported to ONNX by [istupakov](https://huggingface.co/istupakov/parakeet-tdt-0.6b-v3-onnx). Models auto-download from HuggingFace on first run (~3GB).
+Uses [NVIDIA Parakeet TDT 0.6B v3](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3) exported to ONNX by [istupakov](https://huggingface.co/istupakov/parakeet-tdt-0.6b-v3-onnx). Run `parakeet install --onnx` to download models from HuggingFace (~3GB).
 
 ## Requirements
 
@@ -103,12 +124,13 @@ Uses [NVIDIA Parakeet TDT 0.6B v3](https://huggingface.co/nvidia/parakeet-tdt-0.
 
 ### macOS (Apple Silicon)
 
-Works natively on M1/M2/M3/M4. Install dependencies with Homebrew:
+Works natively on M1/M2/M3/M4 with CoreML acceleration. Install dependencies with Homebrew:
 
 ```bash
 brew install ffmpeg
 curl -fsSL https://bun.sh/install | bash
 bun install -g @drakulavich/parakeet-cli    # or: npm install -g @drakulavich/parakeet-cli
+parakeet install                             # downloads CoreML binary
 ```
 
 ### Linux
@@ -117,6 +139,7 @@ bun install -g @drakulavich/parakeet-cli    # or: npm install -g @drakulavich/pa
 apt install ffmpeg   # or yum, pacman, etc.
 curl -fsSL https://bun.sh/install | bash
 bun install -g @drakulavich/parakeet-cli    # or: npm install -g @drakulavich/parakeet-cli
+parakeet install                             # downloads ONNX models (~3GB)
 ```
 
 ## OpenClaw Integration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/parakeet-cli",
-  "version": "0.3.0",
+  "version": "0.5.3",
   "description": "Fast multilingual speech-to-text CLI powered by NVIDIA Parakeet ONNX models",
   "type": "module",
   "bin": {

package/src/__tests__/coreml.test.ts

@@ -0,0 +1,28 @@
+import { describe, test, expect } from "bun:test";
+import { getCoreMLBinPath, isMacArm64, isCoreMLInstalled } from "../coreml";
+import { join } from "path";
+import { homedir } from "os";
+
+describe("coreml", () => {
+  test("getCoreMLBinPath returns correct cache path", () => {
+    const binPath = getCoreMLBinPath();
+    expect(binPath).toBe(
+      join(homedir(), ".cache", "parakeet", "coreml", "bin", "parakeet-coreml"),
+    );
+  });
+
+  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");
+  });
+});

package/src/__tests__/models.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "bun:test";
-import { getModelDir, MODEL_FILES, HF_REPO } from "../models";
+import { getModelDir, MODEL_FILES, HF_REPO, getCoreMLDownloadURL } from "../models";
 import { join } from "path";
 import { homedir } from "os";
 
@@ -20,4 +20,11 @@ describe("models", () => {
   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/cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env bun
 
 import { transcribe } from "./lib";
+import { downloadModel, downloadCoreML } from "./models";
+import { isMacArm64 } from "./coreml";
 
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
@@ -11,20 +13,49 @@ async function main(): Promise<void> {
     process.exit(0);
   }
 
-  const noCache = args.includes("--no-cache");
-  const file = args.filter((a) => !a.startsWith("--"))[0];
+  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()) {
+          console.error("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);
+      console.error(`Error: ${message}`);
+      process.exit(1);
+    }
+    process.exit(0);
+  }
+
+  const file = positional[0];
 
   if (!file) {
-    console.error("Usage: parakeet [--no-cache] <audio_file>");
+    console.error("Usage: parakeet [--version] <audio_file>");
+    console.error("       parakeet install [--coreml | --onnx] [--no-cache]");
     process.exit(1);
   }
 
   try {
-    const text = await transcribe(file, { noCache });
+    const text = await transcribe(file);
     if (text) process.stdout.write(text + "\n");
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`Error: ${message}`);
+    console.error(message);
     process.exit(1);
   }
 }

package/src/coreml.ts

@@ -0,0 +1,35 @@
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync } from "fs";
+
+export function isMacArm64(): boolean {
+  return process.platform === "darwin" && process.arch === "arm64";
+}
+
+export function getCoreMLBinPath(): string {
+  return join(homedir(), ".cache", "parakeet", "coreml", "bin", "parakeet-coreml");
+}
+
+export function isCoreMLInstalled(): boolean {
+  return isMacArm64() && existsSync(getCoreMLBinPath());
+}
+
+export async function transcribeCoreML(audioPath: string): Promise<string> {
+  const binPath = getCoreMLBinPath();
+  const proc = Bun.spawn([binPath, audioPath], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  if (exitCode !== 0) {
+    throw new Error(stderr);
+  }
+
+  return stdout.trim();
+}

package/src/lib.ts

@@ -1,11 +1,9 @@
 import { existsSync } from "fs";
-import { transcribe as internalTranscribe } from "./transcribe";
+import { transcribe as internalTranscribe, type TranscribeOptions } from "./transcribe";
+import { downloadModel, downloadCoreML } from "./models";
 
-export interface TranscribeOptions {
-  beamWidth?: number;
-  noCache?: boolean;
-  modelDir?: string;
-}
+export type { TranscribeOptions };
+export { downloadModel, downloadCoreML };
 
 export async function transcribe(
   audioPath: string,
@@ -15,9 +13,5 @@ export async function transcribe(
     throw new Error(`File not found: ${audioPath}`);
   }
 
-  return internalTranscribe(audioPath, {
-    noCache: options.noCache ?? false,
-    beamWidth: options.beamWidth,
-    modelDir: options.modelDir,
-  });
+  return internalTranscribe(audioPath, options);
 }

package/src/models.ts

@@ -1,6 +1,6 @@
-import { join } from "path";
+import { join, dirname } from "path";
 import { homedir } from "os";
-import { existsSync, mkdirSync } from "fs";
+import { existsSync, mkdirSync, chmodSync } from "fs";
 
 export const HF_REPO = "istupakov/parakeet-tdt-0.6b-v3-onnx";
 
@@ -21,10 +21,34 @@ export function isModelCached(dir?: string): boolean {
   return MODEL_FILES.every((f) => existsSync(join(d, f)));
 }
 
-export async function ensureModel(noCache = false, modelDir?: string): Promise<string> {
+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()) {
+  if (!noCache && isModelCached(dir)) {
+    console.error("Model already downloaded.");
     return dir;
   }
 
@@ -47,5 +71,40 @@ export async function ensureModel(noCache = false, modelDir?: string): Promise<s
     await Bun.write(dest, res);
   }
 
+  console.error("Model downloaded successfully.");
   return dir;
 }
+
+export function getCoreMLDownloadURL(version: string): string {
+  return `https://github.com/drakulavich/parakeet-cli/releases/download/v${version}/parakeet-coreml-darwin-arm64`;
+}
+
+export async function downloadCoreML(noCache = false): Promise<string> {
+  const { getCoreMLBinPath } = await import("./coreml");
+  const binPath = getCoreMLBinPath();
+
+  if (!noCache && existsSync(binPath)) {
+    console.error("CoreML backend already installed.");
+    return binPath;
+  }
+
+  const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+  const url = getCoreMLDownloadURL(pkg.version);
+
+  console.error("Downloading parakeet-coreml binary...");
+
+  const res = await fetch(url, { redirect: "follow" });
+
+  if (!res.ok) {
+    throw new Error(`Failed to download CoreML binary: ${url} (${res.status})`);
+  }
+
+  mkdirSync(dirname(binPath), { recursive: true });
+
+  await Bun.write(binPath, res);
+
+  chmodSync(binPath, 0o755);
+
+  console.error("CoreML backend installed successfully.");
+  return binPath;
+}

package/src/transcribe.ts

@@ -1,4 +1,5 @@
-import { ensureModel } from "./models";
+import { requireModel, isModelCached, installHintError } from "./models";
+import { isCoreMLInstalled, transcribeCoreML } from "./coreml";
 import { convertToFloat32PCM } from "./audio";
 import { initPreprocessor, preprocess } from "./preprocess";
 import { initEncoder, encode } from "./encoder";
@@ -25,7 +26,6 @@ const DECODER_LAYERS = 2;
 const DECODER_HIDDEN = 640;
 
 export interface TranscribeOptions {
-  noCache?: boolean;
   beamWidth?: number;
   modelDir?: string;
 }
@@ -34,20 +34,33 @@ export interface TranscribeOptions {
 const MIN_AUDIO_SAMPLES = 1600;
 
 export async function transcribe(audioPath: string, opts: TranscribeOptions = {}): Promise<string> {
+  if (isCoreMLInstalled()) {
+    return transcribeCoreML(audioPath);
+  }
+
+  if (isModelCached(opts.modelDir)) {
+    return transcribeOnnx(audioPath, opts);
+  }
+
+  throw installHintError("Error: No transcription backend is installed");
+}
+
+async function transcribeOnnx(audioPath: string, opts: TranscribeOptions): Promise<string> {
   const audio = await convertToFloat32PCM(audioPath);
 
   if (audio.length < MIN_AUDIO_SAMPLES) {
     return "";
   }
 
-  const noCache = opts.noCache ?? false;
   const beamWidth = opts.beamWidth ?? 4;
-  const modelDir = await ensureModel(noCache, opts.modelDir);
-  const tokenizer = await Tokenizer.fromFile(join(modelDir, "vocab.txt"));
+  const modelDir = requireModel(opts.modelDir);
 
-  await initPreprocessor(modelDir);
-  await initEncoder(modelDir);
-  await initDecoder(modelDir);
+  const [tokenizer] = await Promise.all([
+    Tokenizer.fromFile(join(modelDir, "vocab.txt")),
+    initPreprocessor(modelDir),
+    initEncoder(modelDir),
+    initDecoder(modelDir),
+  ]);
 
   const { features, length } = await preprocess(audio);
   const { encoderOutput, encodedLength } = await encode(features, length);