@drakulavich/parakeet-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 drakulavich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# parakeet-cli
+
+Fast multilingual speech-to-text CLI powered by NVIDIA Parakeet ONNX models. Zero Python. Runs 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
+- **Any audio format** — ffmpeg handles OGG, MP3, WAV, FLAC, M4A, etc.
+
+## Install
+
+```bash
+bun 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
+```
+
+## Usage
+
+```bash
+# Transcribe any audio file (language auto-detected)
+parakeet audio.ogg
+
+# Force re-download models
+parakeet --no-cache audio.wav
+
+# Show version
+parakeet --version
+```
+
+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.
+
+| # | 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** | | |
+
+**Parakeet is 3x faster.** Whisper handles mixed-language words better (`.env`, `Workspace`). Parakeet transliterates them phonetically. Both produce transcripts usable by LLMs.
+
+Models: Whisper medium (int8) vs Parakeet TDT 0.6B v3 (ONNX, CPU).
+
+## Supported Languages
+
+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.
+
+## 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
+- [ffmpeg](https://ffmpeg.org) installed and in PATH
+- ~3GB disk space for model cache
+
+### 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
+```
+
+### Linux
+
+```bash
+apt install ffmpeg   # or yum, pacman, etc.
+curl -fsSL https://bun.sh/install | bash
+bun install -g @drakulavich/parakeet-cli
+```
+
+## License
+
+MIT

package/bin/parakeet.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+await import("../src/cli.ts");

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@drakulavich/parakeet-cli",
+  "version": "0.1.1",
+  "description": "Fast multilingual speech-to-text CLI powered by NVIDIA Parakeet ONNX models",
+  "type": "module",
+  "bin": {
+    "parakeet": "bin/parakeet.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:unit": "bun test src/__tests__/",
+    "test:integration": "bun test tests/integration/"
+  },
+  "keywords": [
+    "asr",
+    "speech-to-text",
+    "transcription",
+    "parakeet",
+    "nvidia",
+    "onnx",
+    "multilingual",
+    "bun",
+    "cli"
+  ],
+  "author": "drakulavich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drakulavich/parakeet-cli.git"
+  },
+  "homepage": "https://github.com/drakulavich/parakeet-cli#readme",
+  "bugs": {
+    "url": "https://github.com/drakulavich/parakeet-cli/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "dependencies": {
+    "onnxruntime-node": "^1.24.0"
+  }
+}

package/src/__tests__/audio.test.ts

@@ -0,0 +1,26 @@
+import { describe, test, expect } from "bun:test";
+import { convertToFloat32PCM } from "../audio";
+import { existsSync } from "fs";
+
+describe("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"
+    );
+  });
+});

package/src/__tests__/decoder.test.ts

@@ -0,0 +1,57 @@
+import { describe, test, expect } from "bun:test";
+import { greedyDecode, 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 tokens = await greedyDecode(session, 3);
+    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 tokens = await greedyDecode(session, 5);
+    expect(tokens).toEqual([0, 1]);
+  });
+
+  test("handles max_tokens_per_step limit", async () => {
+    const session = mockSession([
+      { tokenLogits: [10, 0, 0, -10], durationLogits: [10, 0] },
+    ]);
+    const tokens = await greedyDecode(session, 2);
+    expect(tokens.length).toBeLessThanOrEqual(20);
+    expect(tokens.length).toBeGreaterThan(0);
+  });
+
+  test("returns empty for zero-length encoder output", async () => {
+    const session = mockSession([
+      { tokenLogits: [0, 0, 0, 10], durationLogits: [10, 0] },
+    ]);
+    const tokens = await greedyDecode(session, 0);
+    expect(tokens).toEqual([]);
+  });
+});

package/src/__tests__/models.test.ts

@@ -0,0 +1,29 @@
+import { describe, test, expect } from "bun:test";
+import { getModelDir, MODEL_FILES, HF_REPOS } from "../models";
+import { join } from "path";
+import { homedir } from "os";
+
+describe("models", () => {
+  test("getModelDir returns correct cache path for v2", () => {
+    const dir = getModelDir("v2");
+    expect(dir).toBe(join(homedir(), ".cache", "parakeet", "v2"));
+  });
+
+  test("getModelDir returns correct cache path for v3", () => {
+    const dir = getModelDir("v3");
+    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_REPOS maps versions to repo IDs", () => {
+    expect(HF_REPOS.v2).toBe("istupakov/parakeet-tdt-0.6b-v2-onnx");
+    expect(HF_REPOS.v3).toBe("istupakov/parakeet-tdt-0.6b-v3-onnx");
+  });
+});

package/src/__tests__/tokenizer.test.ts

@@ -0,0 +1,45 @@
+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");
+  });
+
+  test("isAsciiDominant returns true for ASCII tokens", async () => {
+    const tok = await Tokenizer.fromFile("fixtures/test-vocab.txt");
+    expect(tok.isAsciiDominant([0, 1, 2])).toBe(true);
+  });
+});

package/src/__tests__/transcribe.test.ts

@@ -0,0 +1,11 @@
+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");
+  });
+});

package/src/audio.ts

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

package/src/cli.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env bun
+
+import { existsSync } from "fs";
+import { transcribe } from "./transcribe";
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+
+  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 noCache = args.includes("--no-cache");
+  const file = args.filter((a) => !a.startsWith("--"))[0];
+
+  if (!file) {
+    console.error("Usage: parakeet [--no-cache] <audio_file>");
+    process.exit(1);
+  }
+
+  if (!existsSync(file)) {
+    console.error(`Error: file not found: ${file}`);
+    process.exit(1);
+  }
+
+  try {
+    const text = await transcribe(file, { noCache });
+    if (text) process.stdout.write(text + "\n");
+  } catch (err: any) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/decoder.ts

@@ -0,0 +1,135 @@
+import * as ort from "onnxruntime-node";
+import { join } from "path";
+import { ensureOrtBackend } from "./ort-backend-fix";
+
+const MAX_TOKENS_PER_STEP = 10;
+
+export interface DecoderSession {
+  decode(
+    encoderFrame: Float32Array,
+    targets: number[],
+    targetLength: number,
+    state1: Float32Array,
+    state2: Float32Array
+  ): Promise<{ output: Float32Array; state1: Float32Array; state2: Float32Array }>;
+  vocabSize: number;
+  blankId: number;
+  stateDims: { layers: number; hidden: number };
+}
+
+export async function greedyDecode(
+  session: DecoderSession,
+  encoderLength: number,
+  encoderData?: Float32Array,
+  encoderDim?: number
+): Promise<number[]> {
+  if (encoderLength === 0) return [];
+
+  const tokens: number[] = [];
+  const stateSize = session.stateDims.layers * session.stateDims.hidden;
+  let state1 = new Float32Array(stateSize);
+  let state2 = new Float32Array(stateSize);
+  let lastToken = session.blankId;
+
+  let t = 0;
+  while (t < encoderLength) {
+    let tokensThisStep = 0;
+
+    while (tokensThisStep < MAX_TOKENS_PER_STEP) {
+      let frame: Float32Array;
+      if (encoderData && encoderDim) {
+        // Must copy — ort.Tensor doesn't work with subarray views under Bun
+        frame = encoderData.slice(t * encoderDim, (t + 1) * encoderDim);
+      } else {
+        frame = new Float32Array(1);
+      }
+
+      const result = await session.decode(frame, [lastToken], 1, state1, state2);
+      const output = result.output;
+
+      const tokenLogits = output.slice(0, session.vocabSize);
+      const durationLogits = output.slice(session.vocabSize);
+
+      const tokenId = argmax(tokenLogits);
+      const duration = argmax(durationLogits);
+
+      state1 = result.state1;
+      state2 = result.state2;
+
+      if (tokenId === session.blankId) {
+        t += 1;
+        break;
+      }
+
+      tokens.push(tokenId);
+      lastToken = tokenId;
+      tokensThisStep++;
+
+      if (duration > 0) {
+        t += duration;
+        break;
+      }
+    }
+
+    if (tokensThisStep >= MAX_TOKENS_PER_STEP) {
+      t += 1;
+    }
+  }
+
+  return tokens;
+}
+
+function argmax(arr: Float32Array): number {
+  let maxIdx = 0;
+  let maxVal = arr[0];
+  for (let i = 1; i < arr.length; i++) {
+    if (arr[i] > maxVal) {
+      maxVal = arr[i];
+      maxIdx = i;
+    }
+  }
+  return maxIdx;
+}
+
+let onnxSession: ort.InferenceSession | null = null;
+
+export async function initDecoder(modelDir: string): Promise<void> {
+  if (onnxSession) return;
+  ensureOrtBackend();
+  onnxSession = await ort.InferenceSession.create(join(modelDir, "decoder_joint-model.onnx"));
+}
+
+export function createOnnxDecoderSession(
+  vocabSize: number,
+  blankId: number,
+  layers: number,
+  hidden: number
+): DecoderSession {
+  return {
+    vocabSize,
+    blankId,
+    stateDims: { layers, hidden },
+    async decode(encoderFrame, targets, targetLength, state1, state2) {
+      if (!onnxSession) throw new Error("decoder not initialized");
+
+      const D = encoderFrame.length;
+      const results = await onnxSession.run({
+        encoder_outputs: new ort.Tensor("float32", encoderFrame, [1, D, 1]),
+        targets: new ort.Tensor("int32", Int32Array.from(targets), [1, targets.length]),
+        target_length: new ort.Tensor("int32", Int32Array.from([targetLength]), [1]),
+        input_states_1: new ort.Tensor("float32", state1, [layers, 1, hidden]),
+        input_states_2: new ort.Tensor("float32", state2, [layers, 1, hidden]),
+      });
+
+      return {
+        output: new Float32Array(results["outputs"].data as Float32Array),
+        state1: new Float32Array(results["output_states_1"].data as Float32Array),
+        state2: new Float32Array(results["output_states_2"].data as Float32Array),
+      };
+    },
+  };
+}
+
+export function releaseDecoder(): void {
+  onnxSession = null;
+}

package/src/encoder.ts

@@ -0,0 +1,32 @@
+import * as ort from "onnxruntime-node";
+import { join } from "path";
+import { ensureOrtBackend } from "./ort-backend-fix";
+
+let session: ort.InferenceSession | null = null;
+
+export async function initEncoder(modelDir: string): Promise<void> {
+  if (session) return;
+  ensureOrtBackend();
+  session = await ort.InferenceSession.create(join(modelDir, "encoder-model.onnx"));
+}
+
+export async function encode(
+  features: ort.Tensor,
+  length: ort.Tensor
+): Promise<{ encoderOutput: ort.Tensor; encodedLength: number }> {
+  if (!session) throw new Error("encoder not initialized");
+
+  const results = await session.run({
+    audio_signal: features,
+    length: length,
+  });
+
+  const encoderOutput = results["outputs"];
+  const encodedLength = Number((results["encoded_lengths"].data as BigInt64Array)[0]);
+
+  return { encoderOutput, encodedLength };
+}
+
+export function releaseEncoder(): void {
+  session = null;
+}

package/src/models.ts

@@ -0,0 +1,58 @@
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, mkdirSync } from "fs";
+
+export type ModelVersion = "v2" | "v3";
+
+export const HF_REPOS: Record<ModelVersion, string> = {
+  v2: "istupakov/parakeet-tdt-0.6b-v2-onnx",
+  v3: "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(version: ModelVersion): string {
+  return join(homedir(), ".cache", "parakeet", version);
+}
+
+export function isModelCached(version: ModelVersion): boolean {
+  const dir = getModelDir(version);
+  return MODEL_FILES.every((f) => existsSync(join(dir, f)));
+}
+
+export async function ensureModel(version: ModelVersion, noCache = false): Promise<string> {
+  const dir = getModelDir(version);
+
+  if (!noCache && isModelCached(version)) {
+    return dir;
+  }
+
+  mkdirSync(dir, { recursive: true });
+
+  const repo = HF_REPOS[version];
+
+  for (const file of MODEL_FILES) {
+    const url = `https://huggingface.co/${repo}/resolve/main/${file}`;
+    const dest = join(dir, file);
+
+    if (!noCache && existsSync(dest)) continue;
+
+    console.error(`Downloading ${file}...`);
+
+    const res = await fetch(url, { redirect: "follow" });
+
+    if (!res.ok) {
+      throw new Error(`failed to download model: ${url} (${res.status})`);
+    }
+
+    await Bun.write(dest, res);
+  }
+
+  return dir;
+}

package/src/ort-backend-fix.ts

@@ -0,0 +1,26 @@
+/**
+ * Workaround for Bun + onnxruntime-node backend registration issue.
+ *
+ * When Bun imports onnxruntime-node (CJS), the backend gets registered
+ * in the CJS instance of onnxruntime-common. But our ESM code gets the
+ * ESM instance of onnxruntime-common, which has no backends registered.
+ *
+ * This module manually registers the native backend into the ESM module.
+ */
+
+let registered = false;
+
+export function ensureOrtBackend(): void {
+  if (registered) return;
+  registered = true;
+
+  try {
+    // Force-load onnxruntime-node via require() to trigger CJS side-effects
+    // that register the native backend. Under bun test this happens
+    // automatically, but bun run may need the nudge.
+    require("onnxruntime-node");
+  } catch {
+    // If it fails, the native backend might already be registered
+    // (e.g. running under Node.js or a future Bun version that fixes this)
+  }
+}

package/src/preprocess.ts

@@ -0,0 +1,59 @@
+import * as ort from "onnxruntime-node";
+import { join } from "path";
+import { ensureOrtBackend } from "./ort-backend-fix";
+
+let session: ort.InferenceSession | null = null;
+
+export async function initPreprocessor(modelDir: string): Promise<void> {
+  if (session) return;
+  ensureOrtBackend();
+  session = await ort.InferenceSession.create(join(modelDir, "nemo128.onnx"));
+}
+
+export async function preprocess(audio: Float32Array): Promise<{ features: ort.Tensor; length: ort.Tensor }> {
+  if (!session) throw new Error("preprocessor not initialized");
+
+  const inputTensor = new ort.Tensor("float32", audio, [1, audio.length]);
+  const lengthTensor = new ort.Tensor("int64", BigInt64Array.from([BigInt(audio.length)]), [1]);
+
+  const results = await session.run({
+    waveforms: inputTensor,
+    waveforms_lens: lengthTensor,
+  });
+
+  const melData = results["features"].data as Float32Array;
+  const melDims = results["features"].dims as readonly number[];
+  const T = melDims[2];
+  const actualLength = Number((results["features_lens"].data as BigInt64Array)[0]);
+
+  const numFeatures = melDims[1];
+  const normalized = new Float32Array(melData.length);
+
+  for (let f = 0; f < numFeatures; f++) {
+    let sum = 0;
+    let sumSq = 0;
+
+    for (let t = 0; t < actualLength; t++) {
+      const val = melData[f * T + t];
+      sum += val;
+      sumSq += val * val;
+    }
+
+    const mean = sum / actualLength;
+    const variance = sumSq / actualLength - mean * mean;
+    const std = Math.sqrt(Math.max(variance, 1e-10));
+
+    for (let t = 0; t < T; t++) {
+      normalized[f * T + t] = t < actualLength ? (melData[f * T + t] - mean) / std : 0;
+    }
+  }
+
+  const featureTensor = new ort.Tensor("float32", normalized, melDims as number[]);
+  const outputLength = new ort.Tensor("int64", BigInt64Array.from([BigInt(actualLength)]), [1]);
+
+  return { features: featureTensor, length: outputLength };
+}
+
+export function releasePreprocessor(): void {
+  session = null;
+}

package/src/tokenizer.ts

@@ -0,0 +1,59 @@
+export class Tokenizer {
+  private idToToken: Map<number, string>;
+  readonly vocabSize: number;
+  readonly blankId: number;
+
+  private constructor(idToToken: Map<number, string>, blankId: number) {
+    this.idToToken = idToToken;
+    this.vocabSize = idToToken.size;
+    this.blankId = blankId;
+  }
+
+  static async fromFile(path: string): Promise<Tokenizer> {
+    const content = await Bun.file(path).text();
+    const idToToken = new Map<number, string>();
+    let blankId = -1;
+
+    for (const line of content.trim().split("\n")) {
+      const lastSpace = line.lastIndexOf(" ");
+      if (lastSpace === -1) continue;
+      const token = line.slice(0, lastSpace);
+      const id = parseInt(line.slice(lastSpace + 1), 10);
+      if (isNaN(id)) continue;
+      idToToken.set(id, token);
+      if (token === "<blk>") blankId = id;
+    }
+
+    if (blankId === -1) {
+      blankId = idToToken.size - 1;
+    }
+
+    return new Tokenizer(idToToken, blankId);
+  }
+
+  detokenize(tokenIds: number[]): string {
+    const pieces: string[] = [];
+    for (const id of tokenIds) {
+      if (id === this.blankId) continue;
+      const token = this.idToToken.get(id);
+      if (token !== undefined) pieces.push(token);
+    }
+    return pieces.join("").replaceAll("\u2581", " ").trim();
+  }
+
+  isAsciiDominant(tokenIds: number[], threshold = 0.9): boolean {
+    const nonBlank = tokenIds.filter((id) => id !== this.blankId);
+    if (nonBlank.length === 0) return false;
+
+    let asciiCount = 0;
+    for (const id of nonBlank) {
+      const token = this.idToToken.get(id) ?? "";
+      const cleaned = token.replaceAll("\u2581", "");
+      if (cleaned.length > 0 && /^[\x00-\x7F]+$/.test(cleaned)) {
+        asciiCount++;
+      }
+    }
+
+    return asciiCount / nonBlank.length >= threshold;
+  }
+}

package/src/transcribe.ts

@@ -0,0 +1,61 @@
+import { ensureModel } from "./models";
+import { convertToFloat32PCM } from "./audio";
+import { initPreprocessor, preprocess } from "./preprocess";
+import { initEncoder, encode } from "./encoder";
+import {
+  initDecoder,
+  createOnnxDecoderSession,
+  greedyDecode,
+} from "./decoder";
+import { Tokenizer } from "./tokenizer";
+import { join } from "path";
+
+// Parakeet TDT 0.6B decoder state dimensions (from ONNX model input shapes)
+const DECODER_LAYERS = 2;
+const DECODER_HIDDEN = 640;
+
+export interface TranscribeOptions {
+  noCache?: boolean;
+}
+
+export async function transcribe(audioPath: string, opts: TranscribeOptions = {}): Promise<string> {
+  const audio = await convertToFloat32PCM(audioPath);
+
+  if (audio.length < 1600) {
+    return "";
+  }
+
+  const noCache = opts.noCache ?? false;
+  const modelDir = await ensureModel("v3", noCache);
+  const tokenizer = await Tokenizer.fromFile(join(modelDir, "vocab.txt"));
+
+  await initPreprocessor(modelDir);
+  await initEncoder(modelDir);
+  await initDecoder(modelDir);
+
+  const { features, length } = await preprocess(audio);
+  const { encoderOutput, encodedLength } = await encode(features, length);
+
+  const encoderData = encoderOutput.data as Float32Array;
+  const dims = encoderOutput.dims as readonly number[];
+  const D = dims[1];
+  const T = dims[2];
+
+  // Transpose from [1, D, T] to [T, D] so each frame is contiguous
+  const transposed = new Float32Array(T * D);
+  for (let t = 0; t < T; t++) {
+    for (let d = 0; d < D; d++) {
+      transposed[t * D + d] = encoderData[d * T + t];
+    }
+  }
+
+  const session = createOnnxDecoderSession(
+    tokenizer.vocabSize,
+    tokenizer.blankId,
+    DECODER_LAYERS,
+    DECODER_HIDDEN,
+  );
+
+  const tokens = await greedyDecode(session, encodedLength, transposed, D);
+  return tokenizer.detokenize(tokens);
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "types": ["bun-types"],
+    "strict": true,
+    "skipLibCheck": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}