@drakulavich/parakeet-cli 0.4.0 → 0.6.0

package/README.md

@@ -1,149 +1,88 @@
-# parakeet-cli
+# 🦜 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)
+[![Test Report](https://img.shields.io/badge/Test_Report-Allure-orange)](https://drakulavich.github.io/parakeet-cli/reports/allure)
 
-## Features
+Fast local speech-to-text. 25 languages. ~18x faster than Whisper on Apple Silicon.
 
-- **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
-- **Any audio format** — ffmpeg handles OGG, MP3, WAV, FLAC, M4A, etc.
+- **CoreML on Apple Silicon** — ~155x real-time via [FluidAudio](https://github.com/FluidInference/FluidAudio)
+- **ONNX on CPU** — cross-platform fallback, 3x faster than Whisper
+- **Any audio format** — ffmpeg handles OGG, MP3, WAV, FLAC, M4A
+- **Zero Python** — Bun + TypeScript, native Swift binary for CoreML
 
-## Install
-
-Using Bun (recommended):
+## Quick Start
 
 ```bash
 bun install -g @drakulavich/parakeet-cli
+parakeet install          # CoreML on macOS arm64, ONNX elsewhere
+parakeet audio.ogg        # → transcript to stdout
 ```
 
-Using npm (requires Bun runtime installed):
-
-```bash
-npm install -g @drakulavich/parakeet-cli
-```
-
-Or clone and link locally:
-
-```bash
-git clone https://github.com/drakulavich/parakeet-cli.git
-cd parakeet-cli
-bun install
-bun link
-```
-
-> **Note:** Bun is required as the runtime — the CLI uses Bun-native APIs and TypeScript execution. You can use either `bun` or `npm` as the package manager to install it, but Bun must be available in PATH to run the `parakeet` command.
-
 ## Usage
 
 ```bash
-# Transcribe any audio file (language auto-detected)
-parakeet audio.ogg
-
-# Force re-download models
-parakeet --no-cache audio.wav
-
-# Show version
+parakeet install                 # auto-detect backend
+parakeet install --coreml        # force CoreML (macOS arm64)
+parakeet install --onnx          # force ONNX (~3GB)
+parakeet audio.ogg               # transcribe (language auto-detected)
 parakeet --version
 ```
 
-Output goes to stdout, errors to stderr. Designed for piping and scripting.
+Stdout: transcript. Stderr: errors. Pipe-friendly.
 
-## Benchmark
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.3
+- [ffmpeg](https://ffmpeg.org) in PATH (ONNX backend only)
+- ~3GB disk (ONNX models)
 
-Tested on 10 real Telegram voice messages (Russian, 3-10s each).
-VM: AMD EPYC 7763 8C/16T, 64GB RAM, CPU-only.
+## Supported Languages
 
-| # | 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** | | |
+:bulgaria: Bulgarian, :croatia: Croatian, :czech_republic: Czech, :denmark: Danish, :netherlands: Dutch, :gb: English, :estonia: Estonian, :finland: Finnish, :fr: French, :de: German, :greece: Greek, :hungary: Hungarian, :it: Italian, :latvia: Latvian, :lithuania: Lithuanian, :malta: Maltese, :poland: Polish, :portugal: Portuguese, :romania: Romanian, :ru: Russian, :slovakia: Slovak, :slovenia: Slovenian, :es: Spanish, :sweden: Swedish, :ukraine: Ukrainian
 
-**Parakeet is 3x faster.** Whisper handles mixed-language words better (`.env`, `Workspace`). Parakeet transliterates them phonetically. Both produce transcripts usable by LLMs.
+## Benchmark
 
-Models: Whisper medium (int8) vs Parakeet TDT 0.6B v3 (ONNX, CPU).
+MacBook Pro M3 Pro — 10 Russian voice messages:
 
-## Supported Languages
+| | faster-whisper (CPU) | Parakeet (CoreML) |
+|---|---|---|
+| **Total** | 35.3s | 1.9s |
+| **Speed** | | **~18x faster** |
 
-Bulgarian, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hungarian, Italian, Latvian, Lithuanian, Maltese, Polish, Portuguese, Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Ukrainian.
+Full results with transcripts: [BENCHMARK.md](BENCHMARK.md)
 
 ## How It Works
 
 ```
 parakeet audio.ogg
-  |
-  +-- ffmpeg: any format -> 16kHz mono float32
-  +-- nemo128.onnx: waveform -> 128-dim log-mel spectrogram
-  +-- per-utterance normalization (mean=0, std=1)
-  +-- encoder-model.onnx: mel features -> encoder output
-  +-- TDT greedy decoder: encoder output -> token IDs + durations
-  +-- vocab.txt: token IDs -> text
-  |
-  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).
-
-## Requirements
-
-- [Bun](https://bun.sh) >= 1.3 (runtime)
-- [ffmpeg](https://ffmpeg.org) installed and in PATH
-- ~3GB disk space for model cache
-- npm or Bun can be used as the package manager
-
-### macOS (Apple Silicon)
-
-Works natively on M1/M2/M3/M4. 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
+  ├── CoreML installed? → parakeet-coreml subprocess → stdout
+  └── ONNX installed?   → ffmpeg → mel → encoder → decoder → stdout
 ```
 
-### Linux
-
-```bash
-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
-```
+- **CoreML**: Swift binary wraps [FluidAudio](https://github.com/FluidInference/FluidAudio) + [CoreML model](https://huggingface.co/FluidInference/parakeet-tdt-0.6b-v3-coreml)
+- **ONNX**: [NVIDIA Parakeet TDT 0.6B v3](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3) via [onnxruntime-node](https://www.npmjs.com/package/onnxruntime-node)
 
 ## OpenClaw Integration
 
-To use parakeet as the voice transcription engine in [OpenClaw](https://docs.openclaw.ai), update `~/.openclaw/openclaw.json`:
+Drop-in replacement for OpenClaw voice processing — no API keys, runs locally.
 
 ```json
-"tools": {
-  "media": {
-    "audio": {
-      "enabled": true,
-      "models": [
-        {
-          "type": "cli",
-          "command": "parakeet",
-          "args": ["{{MediaPath}}"],
-          "timeoutSeconds": 120
-        }
-      ],
-      "echoTranscript": false
+{
+  "tools": {
+    "media": {
+      "audio": {
+        "enabled": true,
+        "models": [{"type": "cli", "command": "parakeet", "args": ["{{MediaPath}}"], "timeoutSeconds": 120}],
+        "echoTranscript": false
+      }
     }
   }
 }
 ```
 
-Then restart the gateway: `openclaw gateway restart`
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/parakeet-cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "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,7 +1,8 @@
 #!/usr/bin/env bun
 
 import { transcribe } from "./lib";
-import { downloadModel } from "./models";
+import { downloadModel, downloadCoreML } from "./models";
+import { isMacArm64 } from "./coreml";
 
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
@@ -16,8 +17,23 @@ async function main(): Promise<void> {
 
   if (positional[0] === "install") {
     const noCache = args.includes("--no-cache");
+    const forceCoreML = args.includes("--coreml");
+    const forceOnnx = args.includes("--onnx");
+
     try {
-      await downloadModel(noCache);
+      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}`);
@@ -30,7 +46,7 @@ async function main(): Promise<void> {
 
   if (!file) {
     console.error("Usage: parakeet [--version] <audio_file>");
-    console.error("       parakeet install [--no-cache]");
+    console.error("       parakeet install [--coreml | --onnx] [--no-cache]");
     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,9 +1,9 @@
 import { existsSync } from "fs";
 import { transcribe as internalTranscribe, type TranscribeOptions } from "./transcribe";
-import { downloadModel } from "./models";
+import { downloadModel, downloadCoreML } from "./models";
 
 export type { TranscribeOptions };
-export { downloadModel };
+export { downloadModel, downloadCoreML };
 
 export async function transcribe(
   audioPath: string,

package/src/models.ts

@@ -1,6 +1,7 @@
-import { join } from "path";
+import { join, dirname } from "path";
 import { homedir } from "os";
-import { existsSync, mkdirSync } from "fs";
+import { existsSync, mkdirSync, chmodSync } from "fs";
+import { isCoreMLInstalled } from "./coreml";
 
 export const HF_REPO = "istupakov/parakeet-tdt-0.6b-v3-onnx";
 
@@ -21,21 +22,28 @@ export function isModelCached(dir?: string): boolean {
   return MODEL_FILES.every((f) => existsSync(join(d, f)));
 }
 
+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)) {
-    const lines = [
-      `Error: Model not found at ${dir}`,
-      "",
-      "╔══════════════════════════════════════════════════════════╗",
-      "║ Looks like Parakeet model is not downloaded yet.         ║",
-      "║ Please run the following command to download the model:  ║",
-      "║                                                          ║",
-      "║     npx @drakulavich/parakeet-cli install                ║",
-      "╚══════════════════════════════════════════════════════════╝",
-    ];
-    throw new Error(lines.join("\n"));
+    throw installHintError(`Error: Model not found at ${dir}`);
   }
 
   return dir;
@@ -71,3 +79,37 @@ export async function downloadModel(noCache = false, modelDir?: string): Promise
   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 { requireModel } 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";
@@ -33,6 +34,18 @@ 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) {
@@ -41,11 +54,13 @@ export async function transcribe(audioPath: string, opts: TranscribeOptions = {}
 
   const beamWidth = opts.beamWidth ?? 4;
   const modelDir = requireModel(opts.modelDir);
-  const tokenizer = await Tokenizer.fromFile(join(modelDir, "vocab.txt"));
 
-  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);

package/src/__tests__/audio.test.ts

@@ -1,28 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { convertToFloat32PCM } from "../audio";
-import { spawnSync } from "child_process";
-
-const hasFfmpeg = spawnSync("which", ["ffmpeg"]).status === 0;
-
-describe.skipIf(!hasFfmpeg)("audio", () => {
-  test("converts WAV to 16kHz mono Float32Array", async () => {
-    const buffer = await convertToFloat32PCM("fixtures/silence.wav");
-    expect(buffer).toBeInstanceOf(Float32Array);
-    // 1 second at 16kHz = 16000 samples
-    expect(buffer.length).toBeGreaterThan(15000);
-    expect(buffer.length).toBeLessThan(17000);
-  });
-
-  test("throws on missing file", async () => {
-    expect(convertToFloat32PCM("nonexistent.wav")).rejects.toThrow(
-      "file not found"
-    );
-  });
-
-  test("throws on corrupt file", async () => {
-    await Bun.write("fixtures/corrupt.bin", "not audio data");
-    expect(convertToFloat32PCM("fixtures/corrupt.bin")).rejects.toThrow(
-      "failed to convert audio"
-    );
-  });
-});