@drakulavich/parakeet-cli 0.1.2 → 0.1.4

package/README.md

@@ -12,10 +12,18 @@ Fast multilingual speech-to-text CLI powered by NVIDIA Parakeet ONNX models. Zer
 
 ## Install
 
+Using Bun (recommended):
+
 ```bash
 bun install -g @drakulavich/parakeet-cli
 ```
 
+Using npm (requires Bun runtime installed):
+
+```bash
+npm install -g @drakulavich/parakeet-cli
+```
+
 Or clone and link locally:
 
 ```bash
@@ -25,6 +33,8 @@ 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
@@ -86,9 +96,10 @@ Uses [NVIDIA Parakeet TDT 0.6B v3](https://huggingface.co/nvidia/parakeet-tdt-0.
 
 ## Requirements
 
-- [Bun](https://bun.sh) >= 1.3
+- [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)
 
@@ -97,7 +108,7 @@ 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
+bun install -g @drakulavich/parakeet-cli    # or: npm install -g @drakulavich/parakeet-cli
 ```
 
 ### Linux
@@ -105,7 +116,7 @@ bun install -g @drakulavich/parakeet-cli
 ```bash
 apt install ffmpeg   # or yum, pacman, etc.
 curl -fsSL https://bun.sh/install | bash
-bun install -g @drakulavich/parakeet-cli
+bun install -g @drakulavich/parakeet-cli    # or: npm install -g @drakulavich/parakeet-cli
 ```
 
 ## OpenClaw Integration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/parakeet-cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Fast multilingual speech-to-text CLI powered by NVIDIA Parakeet ONNX models",
   "type": "module",
   "bin": {
@@ -44,7 +44,8 @@
     "bun": ">=1.3.0"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "typescript": "^6.0.2"
   },
   "dependencies": {
     "onnxruntime-node": "^1.24.0"

package/src/__tests__/audio.test.ts

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

package/src/__tests__/models.test.ts

@@ -1,16 +1,11 @@
 import { describe, test, expect } from "bun:test";
-import { getModelDir, MODEL_FILES, HF_REPOS } from "../models";
+import { getModelDir, MODEL_FILES, HF_REPO } 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");
+  test("getModelDir returns correct cache path", () => {
+    const dir = getModelDir();
     expect(dir).toBe(join(homedir(), ".cache", "parakeet", "v3"));
   });
 
@@ -22,8 +17,7 @@ describe("models", () => {
     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");
+  test("HF_REPO points to v3 ONNX repo", () => {
+    expect(HF_REPO).toBe("istupakov/parakeet-tdt-0.6b-v3-onnx");
   });
 });

package/src/__tests__/tokenizer.test.ts

@@ -38,8 +38,4 @@ describe("tokenizer", () => {
     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/audio.ts

@@ -30,6 +30,7 @@ export async function convertToFloat32PCM(inputPath: string): Promise<Float32Arr
     const raw = await Bun.file(tmpPath).arrayBuffer();
     return new Float32Array(raw);
   } finally {
+    // Best-effort cleanup; file may already be gone
     try { unlinkSync(tmpPath); } catch {}
   }
 }

package/src/cli.ts

@@ -28,8 +28,9 @@ async function main(): Promise<void> {
   try {
     const text = await transcribe(file, { noCache });
     if (text) process.stdout.write(text + "\n");
-  } catch (err: any) {
-    console.error(`Error: ${err.message}`);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error: ${message}`);
     process.exit(1);
   }
 }

package/src/decoder.ts

@@ -2,16 +2,19 @@ import * as ort from "onnxruntime-node";
 import { join } from "path";
 import { ensureOrtBackend } from "./ort-backend-fix";
 
+// TDT allows multiple tokens per encoder frame; cap to prevent runaway decoding
 const MAX_TOKENS_PER_STEP = 10;
 
+type F32 = Float32Array<ArrayBufferLike>;
+
 export interface DecoderSession {
   decode(
-    encoderFrame: Float32Array,
+    encoderFrame: F32,
     targets: number[],
     targetLength: number,
-    state1: Float32Array,
-    state2: Float32Array
-  ): Promise<{ output: Float32Array; state1: Float32Array; state2: Float32Array }>;
+    state1: F32,
+    state2: F32
+  ): Promise<{ output: F32; state1: F32; state2: F32 }>;
   vocabSize: number;
   blankId: number;
   stateDims: { layers: number; hidden: number };
@@ -27,8 +30,8 @@ export async function greedyDecode(
 
   const tokens: number[] = [];
   const stateSize = session.stateDims.layers * session.stateDims.hidden;
-  let state1 = new Float32Array(stateSize);
-  let state2 = new Float32Array(stateSize);
+  let state1: F32 = new Float32Array(stateSize);
+  let state2: F32 = new Float32Array(stateSize);
   let lastToken = session.blankId;
 
   let t = 0;
@@ -129,7 +132,3 @@ export function createOnnxDecoderSession(
     },
   };
 }
-
-export function releaseDecoder(): void {
-  onnxSession = null;
-}

package/src/encoder.ts

@@ -26,7 +26,3 @@ export async function encode(
 
   return { encoderOutput, encodedLength };
 }
-
-export function releaseEncoder(): void {
-  session = null;
-}

package/src/models.ts

@@ -2,12 +2,7 @@ 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 HF_REPO = "istupakov/parakeet-tdt-0.6b-v3-onnx";
 
 export const MODEL_FILES = [
   "encoder-model.onnx",
@@ -17,28 +12,26 @@ export const MODEL_FILES = [
   "vocab.txt",
 ];
 
-export function getModelDir(version: ModelVersion): string {
-  return join(homedir(), ".cache", "parakeet", version);
+export function getModelDir(): string {
+  return join(homedir(), ".cache", "parakeet", "v3");
 }
 
-export function isModelCached(version: ModelVersion): boolean {
-  const dir = getModelDir(version);
+export function isModelCached(): boolean {
+  const dir = getModelDir();
   return MODEL_FILES.every((f) => existsSync(join(dir, f)));
 }
 
-export async function ensureModel(version: ModelVersion, noCache = false): Promise<string> {
-  const dir = getModelDir(version);
+export async function ensureModel(noCache = false): Promise<string> {
+  const dir = getModelDir();
 
-  if (!noCache && isModelCached(version)) {
+  if (!noCache && isModelCached()) {
     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 url = `https://huggingface.co/${HF_REPO}/resolve/main/${file}`;
     const dest = join(dir, file);
 
     if (!noCache && existsSync(dest)) continue;

package/src/preprocess.ts

@@ -2,6 +2,8 @@ import * as ort from "onnxruntime-node";
 import { join } from "path";
 import { ensureOrtBackend } from "./ort-backend-fix";
 
+const NORM_EPSILON = 1e-10;
+
 let session: ort.InferenceSession | null = null;
 
 export async function initPreprocessor(modelDir: string): Promise<void> {
@@ -41,7 +43,7 @@ export async function preprocess(audio: Float32Array): Promise<{ features: ort.T
 
     const mean = sum / actualLength;
     const variance = sumSq / actualLength - mean * mean;
-    const std = Math.sqrt(Math.max(variance, 1e-10));
+    const std = Math.sqrt(Math.max(variance, NORM_EPSILON));
 
     for (let t = 0; t < T; t++) {
       normalized[f * T + t] = t < actualLength ? (melData[f * T + t] - mean) / std : 0;
@@ -53,7 +55,3 @@ export async function preprocess(audio: Float32Array): Promise<{ features: ort.T
 
   return { features: featureTensor, length: outputLength };
 }
-
-export function releasePreprocessor(): void {
-  session = null;
-}

package/src/tokenizer.ts

@@ -40,20 +40,4 @@ export class Tokenizer {
     }
     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

@@ -10,6 +10,16 @@ import {
 import { Tokenizer } from "./tokenizer";
 import { join } from "path";
 
+function transpose2D(data: Float32Array, rows: number, cols: number): Float32Array {
+  const out = new Float32Array(cols * rows);
+  for (let c = 0; c < cols; c++) {
+    for (let r = 0; r < rows; r++) {
+      out[c * rows + r] = data[r * cols + c];
+    }
+  }
+  return out;
+}
+
 // Parakeet TDT 0.6B decoder state dimensions (from ONNX model input shapes)
 const DECODER_LAYERS = 2;
 const DECODER_HIDDEN = 640;
@@ -18,15 +28,18 @@ export interface TranscribeOptions {
   noCache?: boolean;
 }
 
+// Minimum 0.1s of audio at 16kHz to produce meaningful output
+const MIN_AUDIO_SAMPLES = 1600;
+
 export async function transcribe(audioPath: string, opts: TranscribeOptions = {}): Promise<string> {
   const audio = await convertToFloat32PCM(audioPath);
 
-  if (audio.length < 1600) {
+  if (audio.length < MIN_AUDIO_SAMPLES) {
     return "";
   }
 
   const noCache = opts.noCache ?? false;
-  const modelDir = await ensureModel("v3", noCache);
+  const modelDir = await ensureModel(noCache);
   const tokenizer = await Tokenizer.fromFile(join(modelDir, "vocab.txt"));
 
   await initPreprocessor(modelDir);
@@ -41,13 +54,7 @@ export async function transcribe(audioPath: string, opts: TranscribeOptions = {}
   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 transposed = transpose2D(encoderData, D, T);
 
   const session = createOnnxDecoderSession(
     tokenizer.vocabSize,

package/tsconfig.json

@@ -7,7 +7,7 @@
     "strict": true,
     "skipLibCheck": true,
     "outDir": "./dist",
-    "rootDir": "./src"
+    "rootDir": "."
   },
   "include": ["src/**/*.ts", "tests/**/*.ts"]
 }