@drakulavich/kesha-voice-kit 1.0.0-beta.5 → 1.0.2

package/README.md

@@ -1,13 +1,19 @@
-# Kesha Voice Kit
+<p align="center">
+  <img src="assets/logo.png" alt="Kesha Voice Kit" width="200">
+</p>
 
-[![CI](https://github.com/drakulavich/kesha-voice-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/drakulavich/kesha-voice-kit/actions/workflows/ci.yml)
-[![npm version](https://img.shields.io/npm/v/@drakulavich/kesha-voice-kit)](https://www.npmjs.com/package/@drakulavich/kesha-voice-kit)
-[![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)
+<h1 align="center">Kesha Voice Kit</h1>
 
-**Open-source voice toolkit for Apple Silicon.** A collection of small, fast, open-source audio models — packaged as CLI tools and an [OpenClaw](https://github.com/nicekid1/OpenClaw) skill for LLM agents.
+<p align="center">
+  <a href="https://github.com/drakulavich/kesha-voice-kit/actions/workflows/ci.yml"><img src="https://github.com/drakulavich/kesha-voice-kit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@drakulavich/kesha-voice-kit"><img src="https://img.shields.io/npm/v/@drakulavich/kesha-voice-kit" alt="npm version"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
+</p>
 
-- **Speech-to-text** — 25 languages, ~18x faster than Whisper on Apple Silicon
+<p align="center"><b>Open-source voice toolkit.</b> Optimized for Apple Silicon (CoreML), works on any platform (ONNX fallback).<br>A collection of small, fast, open-source audio models — packaged as CLI tools and an <a href="https://github.com/openclaw/openclaw">OpenClaw</a> skill for LLM agents.</p>
+
+- **Speech-to-text** — 25 languages, ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
 - **Language detection** — 107 languages from audio, text language via NLLanguageRecognizer
 - **Rust engine** — single 20MB binary, no ffmpeg, no Python, no native Node addons
 - **OpenClaw-ready** — plug into your LLM agent as a voice processing skill
@@ -22,44 +28,17 @@ kesha audio.ogg     # transcript to stdout
 
 ## OpenClaw Integration
 
-Kesha Voice Kit is built as a skill for [OpenClaw](https://github.com/nicekid1/OpenClaw) — give your LLM agent ears. No API keys, everything runs locally on your machine.
+Kesha Voice Kit ships as a plugin for [OpenClaw](https://github.com/openclaw/openclaw) — give your LLM agent ears. No API keys, everything runs locally on your machine.
 
-### Voice message processing
+**Install the plugin** (requires the `kesha` CLI — see [Quick Start](#quick-start)):
 
-```json
-{
-  "tools": {
-    "media": {
-      "audio": {
-        "enabled": true,
-        "models": [
-          {
-            "type": "cli",
-            "command": "kesha",
-            "args": ["{{MediaPath}}"],
-            "timeoutSeconds": 120
-          }
-        ],
-        "echoTranscript": false
-      }
-    }
-  }
-}
+```bash
+openclaw plugins install @drakulavich/kesha-voice-kit
 ```
 
-Your agent receives a voice message in Telegram/WhatsApp/Slack. OpenClaw pipes it through Kesha, feeds the transcript to the LLM. The user speaks, the agent understands.
-
-### Language-aware processing
-
-```json
-{
-  "type": "cli",
-  "command": "kesha",
-  "args": ["--json", "{{MediaPath}}"]
-}
-```
+OpenClaw fetches the package from npm, auto-detects [`openclaw.plugin.json`](./openclaw.plugin.json), and wires `kesha --json {{MediaPath}}` as the audio transcription backend under `tools.media.audio`. Manage it afterwards with `openclaw plugins list`, `openclaw plugins disable kesha-voice-kit`, or `openclaw plugins uninstall kesha-voice-kit`.
 
-JSON output includes detected language — your agent knows what language the user spoke and can respond accordingly:
+Your agent receives a voice message in Telegram/WhatsApp/Slack. Kesha transcribes it locally, detects the language, and returns structured JSON:
 
 ```json
 [{
@@ -70,6 +49,8 @@ JSON output includes detected language — your agent knows what language the us
 }]
 ```
 
+The agent knows what was said and in what language — and can respond accordingly.
+
 ## CLI Tools
 
 ```bash
@@ -91,7 +72,7 @@ Kesha Voice Kit bundles open-source models optimized for on-device inference:
 
 | Model | Task | Size | Source |
 |---|---|---|---|
-| NVIDIA Parakeet TDT 0.6B v3 | Speech-to-text | ~86MB | [HuggingFace](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3) |
+| NVIDIA Parakeet TDT 0.6B v3 | Speech-to-text | ~2.5GB | [HuggingFace](https://huggingface.co/nvidia/parakeet-tdt-0.6b-v3) |
 | SpeechBrain ECAPA-TDNN | Audio language detection | ~86MB | [HuggingFace](https://huggingface.co/speechbrain/lang-id-voxlingua107-ecapa) |
 | Apple NLLanguageRecognizer | Text language detection | built-in | macOS system framework |
 
@@ -99,20 +80,16 @@ All models run through `kesha-engine` — a Rust binary using [FluidAudio](https
 
 ## Performance
 
-> **~18x faster than Whisper** on Apple Silicon
+> **~19x faster than Whisper** on Apple Silicon, **~2.5x faster** on CPU
 
-<details>
-<summary>MacBook Pro M3 Pro — 10 Russian voice messages</summary>
+Compared against Whisper `large-v3-turbo` — all engines auto-detect language.
 
-```
-faster-whisper (CPU):  35.3s  ██████████████████████████████████████
-Kesha (CoreML):         1.9s  ██
-```
+![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](assets/benchmark.svg)
 
-| | faster-whisper | Kesha | Speedup |
-|---|---|---|---|
-| Apple Silicon (CoreML) | 35.3s | **1.9s** | **~18x** |
-| Linux CI (ONNX) | 79.2s | **45.4s** | **~1.7x** |
+<details>
+<summary>Full results with per-file breakdown</summary>
+
+See [BENCHMARK.md](BENCHMARK.md) — includes Russian (real voice messages) and English transcription results with all four engines.
 
 </details>
 
@@ -157,7 +134,6 @@ const text = await transcribe("audio.ogg"); // transcribe
 
 - [Bun](https://bun.sh) >= 1.3
 - macOS arm64, Linux x64, or Windows x64
-- ~200MB disk (engine + models)
 
 ## Contributing
 

package/SKILL.md

@@ -0,0 +1,54 @@
+# Kesha Voice Kit
+
+Local speech-to-text for voice messages. Runs entirely on your machine — no API keys, no cloud.
+
+## What it does
+
+When a voice message arrives (Telegram, WhatsApp, Slack), Kesha transcribes it and returns JSON with the transcript and detected language:
+
+```json
+[{
+  "file": "voice.ogg",
+  "text": "Привет, как дела?",
+  "lang": "ru",
+  "textLanguage": { "code": "ru", "confidence": 0.99 }
+}]
+```
+
+Use the `lang` field to detect which language the user spoke and respond accordingly.
+
+## Setup
+
+After installing the plugin, run once to download the engine and models:
+
+```bash
+kesha install
+```
+
+## Plain text mode
+
+If you don't need language detection, switch to plain text output in your config:
+
+```json
+{
+  "type": "cli",
+  "command": "kesha",
+  "args": ["{{MediaPath}}"]
+}
+```
+
+This returns just the transcript text without JSON wrapping.
+
+## Available flags
+
+- `--json` — JSON output with language detection (default in this plugin)
+- `--verbose` — show language detection details (audio + text language with confidence)
+- `--lang <code>` — warn if detected language differs from expected (e.g. `--lang en`)
+
+## Supported languages
+
+Speech-to-text: 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.
+
+## Performance
+
+~19x faster than Whisper on Apple Silicon (CoreML), ~2.5x faster on CPU (ONNX).

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "kesha-voice-kit",
+  "displayName": "Kesha Voice Kit",
+  "description": "Local speech-to-text for voice messages. 25 languages, ~19x faster than Whisper on Apple Silicon. Drop-in replacement for openai-whisper.",
+  "configSchema": {},
+  "configPatch": {
+    "tools": {
+      "media": {
+        "audio": {
+          "enabled": true,
+          "models": [
+            {
+              "type": "cli",
+              "command": "kesha",
+              "args": ["--json", "{{MediaPath}}"]
+            }
+          ]
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.2",
   "description": "Open-source voice toolkit for Apple Silicon. Speech-to-text, language detection. 25 languages.",
   "type": "module",
   "bin": {
@@ -16,13 +16,17 @@
     "src/",
     "package.json",
     "tsconfig.json",
+    "openclaw.plugin.json",
+    "SKILL.md",
+    "scripts/postinstall.cjs",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
     "test": "bun test",
     "test:unit": "bun test tests/unit/",
-    "test:integration": "bun test tests/integration/"
+    "test:integration": "bun test tests/integration/",
+    "postinstall": "node scripts/postinstall.cjs"
   },
   "keywords": [
     "asr",
@@ -56,6 +60,7 @@
   },
   "dependencies": {
     "citty": "^0.2.2",
+    "fastest-levenshtein": "^1.0.16",
     "picocolors": "^1.1.1",
     "tinyld": "^1.3.4"
   }

package/scripts/postinstall.cjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+const { execSync } = require("child_process");
+
+try {
+  execSync("bun --version", { stdio: "ignore" });
+} catch {
+  console.warn(
+    "\n⚠️  Kesha Voice Kit requires Bun runtime.\n" +
+    "   Install Bun: curl -fsSL https://bun.sh/install | bash\n" +
+    "   Then run:    kesha install\n"
+  );
+}

package/src/cli.ts

@@ -8,6 +8,7 @@ import { detectAudioLanguageEngine, detectTextLanguageEngine } from "./engine";
 import type { LangDetectResult } from "./engine";
 import { log } from "./log";
 import { showStatus } from "./status";
+import { suggestCommand } from "./suggest-command";
 
 export function detectLanguage(text: string): string {
   if (!text) return "";
@@ -20,6 +21,8 @@ export function checkLanguageMismatch(expected: string | undefined, detected: st
 }
 
 interface InstallCommandArgs {
+  coreml: boolean;
+  onnx: boolean;
   "no-cache": boolean;
 }
 
@@ -32,9 +35,19 @@ interface MainCommandArgs {
 
 const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
 
-async function performInstall(noCache: boolean) {
+function resolveBackendFlag(coreml: boolean, onnx: boolean): string | undefined {
+  if (coreml && onnx) {
+    log.error('Choose only one backend: "--coreml" or "--onnx".');
+    process.exit(1);
+  }
+  if (coreml) return "coreml";
+  if (onnx) return "onnx";
+  return undefined;
+}
+
+async function performInstall(noCache: boolean, backend?: string) {
   try {
-    await downloadEngine(noCache);
+    await downloadEngine(noCache, backend);
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);
     log.error(message);
@@ -48,6 +61,16 @@ export const installCommand = defineCommand({
     description: "Download inference engine and 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",
@@ -55,7 +78,8 @@ export const installCommand = defineCommand({
     },
   },
   async run({ args }: { args: InstallCommandArgs }) {
-    await performInstall(args["no-cache"]);
+    const backend = resolveBackendFlag(args.coreml, args.onnx);
+    await performInstall(args["no-cache"], backend);
   },
 });
 
@@ -109,12 +133,15 @@ export const mainCommand = defineCommand({
 
     for (const file of files) {
       try {
+        // Run audio lang-id and transcription concurrently
+        const [audioResult, text] = await Promise.all([
+          wantsLangId ? detectAudioLanguageEngine(file) : Promise.resolve(null),
+          transcribe(file),
+        ]);
+
         let audioLanguage: LangDetectResult | undefined;
-        if (wantsLangId) {
-          const audioResult = await detectAudioLanguageEngine(file);
-          if (audioResult && audioResult.code) {
-            audioLanguage = audioResult;
-          }
+        if (audioResult && audioResult.code) {
+          audioLanguage = audioResult;
         }
 
         if (audioLanguage && args.lang && audioLanguage.confidence > 0.8) {
@@ -122,9 +149,7 @@ export const mainCommand = defineCommand({
           if (mismatch) log.warn(`${file}: ${mismatch} (from audio)`);
         }
 
-        const text = await transcribe(file);
-
-        const tinyldLang = detectLanguage(text);
+        const tinyldLang = wantsLangId ? detectLanguage(text) : "";
         let textLanguage: LangDetectResult | undefined;
 
         if (wantsLangId) {
@@ -165,6 +190,8 @@ export const mainCommand = defineCommand({
   },
 });
 
+const SUBCOMMANDS = ["install", "status"];
+
 export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
   const [firstArg, ...restArgs] = rawArgs;
 
@@ -178,6 +205,16 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
     return;
   }
 
+  // Check for unknown subcommands (non-flag, non-file-path args)
+  if (firstArg && !firstArg.startsWith("-") && !firstArg.includes(".") && !firstArg.includes("/")) {
+    const suggestion = suggestCommand(firstArg, SUBCOMMANDS);
+    if (suggestion && suggestion !== firstArg) {
+      log.error(`unknown command '${firstArg}'`);
+      log.warn(`(Did you mean ${suggestion}?)`);
+      process.exit(1);
+    }
+  }
+
   await runMain(mainCommand, { rawArgs });
 }
 

package/src/engine-install.ts

@@ -1,6 +1,6 @@
 import { dirname } from "path";
 import { existsSync, mkdirSync, chmodSync } from "fs";
-import { getEngineBinPath } from "./engine";
+import { getEngineBinPath, getEngineCapabilities } from "./engine";
 import { log } from "./log";
 import { streamResponseToFile } from "./progress";
 
@@ -17,7 +17,7 @@ function getEngineBinaryName(): string {
   throw new Error(`Unsupported platform: ${platform} ${arch}`);
 }
 
-export async function downloadEngine(noCache = false): Promise<string> {
+export async function downloadEngine(noCache = false, backend?: string): Promise<string> {
   const binPath = getEngineBinPath();
 
   if (!noCache && existsSync(binPath)) {
@@ -50,18 +50,29 @@ export async function downloadEngine(noCache = false): Promise<string> {
     log.success("Engine binary downloaded.");
   }
 
+  if (backend) {
+    const caps = await getEngineCapabilities();
+    if (caps && caps.backend !== backend) {
+      throw new Error(
+        `Requested backend "${backend}" is not available: the installed engine for this platform uses "${caps.backend}".\n  Fix: omit --${backend} to use the auto-detected backend, or run on a platform that ships the "${backend}" build.`,
+      );
+    }
+  }
+
   log.progress("Installing models...");
-  const proc = Bun.spawnSync([binPath, "install", ...(noCache ? ["--no-cache"] : [])], {
+  const installArgs = ["install", ...(noCache ? ["--no-cache"] : [])];
+  const proc = Bun.spawnSync([binPath, ...installArgs], {
     stdout: "pipe",
     stderr: "pipe",
   });
 
-  if (proc.stderr.toString()) {
-    process.stderr.write(proc.stderr.toString());
+  const stderr = proc.stderr.toString();
+  if (stderr) {
+    process.stderr.write(stderr);
   }
 
   if (proc.exitCode !== 0) {
-    const detail = proc.stderr.toString().trim();
+    const detail = stderr.trim();
     throw new Error(detail ? `Failed to install models: ${detail}` : "Failed to install models");
   }
 

package/src/engine.ts

@@ -7,8 +7,10 @@ export interface LangDetectResult {
   confidence: number;
 }
 
+const ENGINE_BIN_PATH = join(homedir(), ".cache", "kesha", "engine", "bin", "kesha-engine");
+
 export function getEngineBinPath(): string {
-  return join(homedir(), ".cache", "kesha", "engine", "bin", "kesha-engine");
+  return ENGINE_BIN_PATH;
 }
 
 export function isEngineInstalled(): boolean {

package/src/lib.ts

@@ -5,6 +5,9 @@ import { downloadEngine } from "./engine-install";
 export type { TranscribeOptions };
 export { downloadEngine as downloadModel };
 
+/** @deprecated Use `downloadModel` instead. */
+export const downloadCoreML = downloadEngine;
+
 export async function transcribe(
   audioPath: string,
   options: TranscribeOptions = {},

package/src/suggest-command.ts

@@ -0,0 +1,21 @@
+import { closest, distance } from "fastest-levenshtein";
+
+export function suggestCommand(input: string, commands: string[]): string | null {
+  if (!input || commands.length === 0) return null;
+
+  const lowerInput = input.toLowerCase();
+  const lowerCommands = commands.map((c) => c.toLowerCase());
+
+  const exactIdx = lowerCommands.indexOf(lowerInput);
+  if (exactIdx !== -1) return commands[exactIdx];
+
+  const match = closest(lowerInput, lowerCommands);
+  const dist = distance(lowerInput, match);
+
+  // Threshold: distance <= 3 AND distance <= 40% of target length
+  const maxDist = Math.min(3, Math.ceil(match.length * 0.4));
+  if (dist > maxDist) return null;
+
+  const idx = lowerCommands.indexOf(match);
+  return commands[idx];
+}

package/src/benchmark-report.ts

@@ -1,92 +0,0 @@
-export interface BenchmarkSystemInfo {
-  os: string;
-  arch: string;
-  chip: string;
-  ram: string;
-  backend: string;
-}
-
-export interface BenchmarkResult {
-  time: number;
-  text: string;
-}
-
-export interface BenchmarkSummary {
-  whisper_total: number;
-  parakeet_total: number;
-  speedup: number;
-}
-
-export interface BenchmarkReport {
-  markdown: string;
-  summary: BenchmarkSummary;
-}
-
-function roundToTenths(value: number): number {
-  return Math.round(value * 10) / 10;
-}
-
-export function createBenchmarkSummary(
-  whisperResults: BenchmarkResult[],
-  parakeetResults: BenchmarkResult[],
-): BenchmarkSummary {
-  if (whisperResults.length !== parakeetResults.length) {
-    throw new Error(
-      `Benchmark result count mismatch: faster-whisper=${whisperResults.length}, parakeet=${parakeetResults.length}`,
-    );
-  }
-
-  const whisperTotal = roundToTenths(
-    whisperResults.reduce((total, result) => total + result.time, 0),
-  );
-  const parakeetTotal = roundToTenths(
-    parakeetResults.reduce((total, result) => total + result.time, 0),
-  );
-
-  return {
-    whisper_total: whisperTotal,
-    parakeet_total: parakeetTotal,
-    speedup: parakeetTotal > 0 ? roundToTenths(whisperTotal / parakeetTotal) : 0,
-  };
-}
-
-export function renderBenchmarkReport(args: {
-  date: string;
-  version: string;
-  system: BenchmarkSystemInfo;
-  whisperResults: BenchmarkResult[];
-  parakeetResults: BenchmarkResult[];
-}): BenchmarkReport {
-  const { date, version, system, whisperResults, parakeetResults } = args;
-  const summary = createBenchmarkSummary(whisperResults, parakeetResults);
-
-  const lines: string[] = [
-    "",
-    `**Date:** ${date}`,
-    `**Version:** v${version}`,
-    `**Runner:** ${system.os} ${system.arch} (${system.chip}, ${system.ram} RAM)`,
-    `**Backend:** ${system.backend}`,
-    "",
-    `| # | faster-whisper | Kesha (${system.backend}) | faster-whisper Transcript | Kesha Transcript |`,
-    "|---|---------|----------|--------------------|---------------------|",
-  ];
-
-  for (let i = 0; i < whisperResults.length; i++) {
-    const whisper = whisperResults[i];
-    const parakeet = parakeetResults[i];
-    lines.push(
-      `| ${i + 1} | ${whisper.time}s | ${parakeet.time}s | ${whisper.text} | ${parakeet.text} |`,
-    );
-  }
-
-  lines.push(
-    `| **Total** | **${summary.whisper_total}s** | **${summary.parakeet_total}s** | | |`,
-  );
-  lines.push("");
-  lines.push(`**Kesha is ~${summary.speedup}x faster.**`);
-
-  return {
-    markdown: lines.join("\n"),
-    summary,
-  };
-}