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

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,168 @@
+# Kesha Voice Kit
+
+[![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)
+
+**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.
+
+- **Speech-to-text** — 25 languages, ~18x faster than Whisper on Apple Silicon
+- **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
+
+## Quick Start
+
+```bash
+bun install -g @drakulavich/kesha-voice-kit
+kesha install       # downloads engine + models
+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.
+
+### Voice message processing
+
+```json
+{
+  "tools": {
+    "media": {
+      "audio": {
+        "enabled": true,
+        "models": [
+          {
+            "type": "cli",
+            "command": "kesha",
+            "args": ["{{MediaPath}}"],
+            "timeoutSeconds": 120
+          }
+        ],
+        "echoTranscript": false
+      }
+    }
+  }
+}
+```
+
+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}}"]
+}
+```
+
+JSON output includes detected language — your agent knows what language the user spoke and can respond accordingly:
+
+```json
+[{
+  "file": "voice.ogg",
+  "text": "Привет, как дела?",
+  "lang": "ru",
+  "textLanguage": { "code": "ru", "confidence": 0.99 }
+}]
+```
+
+## CLI Tools
+
+```bash
+kesha install                    # download engine and models
+kesha audio.ogg                  # transcribe
+kesha --json audio.ogg           # JSON output with language info
+kesha --verbose audio.ogg        # show language detection details
+kesha --lang en audio.ogg        # warn if detected language differs
+kesha status                     # show installed backend info
+```
+
+Stdout: transcript. Stderr: errors. Pipe-friendly.
+
+**Also available as `parakeet` command** (backward-compatible alias).
+
+## What's Inside
+
+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) |
+| 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 |
+
+All models run through `kesha-engine` — a Rust binary using [FluidAudio](https://github.com/FluidInference/FluidAudio) (CoreML) on Apple Silicon and [ort](https://github.com/pykeio/ort) (ONNX Runtime) on other platforms.
+
+## Performance
+
+> **~18x faster than Whisper** on Apple Silicon
+
+<details>
+<summary>MacBook Pro M3 Pro — 10 Russian voice messages</summary>
+
+```
+faster-whisper (CPU):  35.3s  ██████████████████████████████████████
+Kesha (CoreML):         1.9s  ██
+```
+
+| | faster-whisper | Kesha | Speedup |
+|---|---|---|---|
+| Apple Silicon (CoreML) | 35.3s | **1.9s** | **~18x** |
+| Linux CI (ONNX) | 79.2s | **45.4s** | **~1.7x** |
+
+</details>
+
+## Supported Audio Formats
+
+Built-in audio decoding via [symphonia](https://github.com/pdeljanov/Symphonia) — no ffmpeg required:
+
+| Format | Extension |
+|---|---|
+| WAV | `.wav` |
+| MP3 | `.mp3` |
+| OGG Vorbis/Opus | `.ogg`, `.opus` |
+| FLAC | `.flac` |
+| AAC / M4A | `.aac`, `.m4a` |
+
+## Supported Languages
+
+**Speech-to-text (25):** :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
+
+**Audio language detection (107):** Full list at [speechbrain/lang-id-voxlingua107-ecapa](https://huggingface.co/speechbrain/lang-id-voxlingua107-ecapa)
+
+## Architecture
+
+```
+kesha audio.ogg
+  → kesha-engine (Rust binary)
+    ├── Apple Silicon? → FluidAudio (CoreML / Neural Engine)
+    └── Other?        → ort (ONNX Runtime / CPU)
+  → transcript to stdout
+```
+
+## Programmatic API
+
+```typescript
+import { transcribe, downloadModel } from "@drakulavich/kesha-voice-kit/core";
+
+await downloadModel();                    // install engine + models
+const text = await transcribe("audio.ogg"); // transcribe
+```
+
+## Requirements
+
+- [Bun](https://bun.sh) >= 1.3
+- macOS arm64, Linux x64, or Windows x64
+- ~200MB disk (engine + models)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+Made with 💛🩵 Published under MIT License.

package/bin/kesha.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { runCli } from "../src/cli.ts";
+
+await runCli();

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@drakulavich/kesha-voice-kit",
+  "version": "1.0.0-beta.5",
+  "description": "Open-source voice toolkit for Apple Silicon. Speech-to-text, language detection. 25 languages.",
+  "type": "module",
+  "bin": {
+    "kesha": "bin/kesha.js",
+    "parakeet": "bin/kesha.js"
+  },
+  "exports": {
+    ".": "./src/cli.ts",
+    "./core": "./src/lib.ts"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "package.json",
+    "tsconfig.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:unit": "bun test tests/unit/",
+    "test:integration": "bun test tests/integration/"
+  },
+  "keywords": [
+    "asr",
+    "speech-to-text",
+    "transcription",
+    "voice",
+    "kesha",
+    "multilingual",
+    "apple-silicon",
+    "coreml",
+    "bun",
+    "cli"
+  ],
+  "author": "drakulavich",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drakulavich/kesha-voice-kit.git"
+  },
+  "homepage": "https://github.com/drakulavich/kesha-voice-kit#readme",
+  "bugs": {
+    "url": "https://github.com/drakulavich/kesha-voice-kit/issues"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "fast-xml-parser": "^5.5.10",
+    "typescript": "^6.0.2"
+  },
+  "dependencies": {
+    "citty": "^0.2.2",
+    "picocolors": "^1.1.1",
+    "tinyld": "^1.3.4"
+  }
+}

package/src/benchmark-report.ts

@@ -0,0 +1,92 @@
+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,
+  };
+}

package/src/cli.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env bun
+
+import { defineCommand, runMain } from "citty";
+import { detect } from "tinyld";
+import { transcribe } from "./lib";
+import { downloadEngine } from "./engine-install";
+import { detectAudioLanguageEngine, detectTextLanguageEngine } from "./engine";
+import type { LangDetectResult } from "./engine";
+import { log } from "./log";
+import { showStatus } from "./status";
+
+export function detectLanguage(text: string): string {
+  if (!text) return "";
+  return detect(text);
+}
+
+export function checkLanguageMismatch(expected: string | undefined, detected: string): string | null {
+  if (!expected || !detected || expected === detected) return null;
+  return `warning: expected language "${expected}" but detected "${detected}"`;
+}
+
+interface InstallCommandArgs {
+  "no-cache": boolean;
+}
+
+interface MainCommandArgs {
+  _: string[];
+  json: boolean;
+  verbose: boolean;
+  lang?: string;
+}
+
+const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+
+async function performInstall(noCache: boolean) {
+  try {
+    await downloadEngine(noCache);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error(message);
+    process.exit(1);
+  }
+}
+
+export const installCommand = defineCommand({
+  meta: {
+    name: "install",
+    description: "Download inference engine and models",
+  },
+  args: {
+    "no-cache": {
+      type: "boolean",
+      description: "Re-download even if cached",
+      default: false,
+    },
+  },
+  async run({ args }: { args: InstallCommandArgs }) {
+    await performInstall(args["no-cache"]);
+  },
+});
+
+export const statusCommand = defineCommand({
+  meta: {
+    name: "status",
+    description: "Show backend installation status",
+  },
+  async run() {
+    await showStatus();
+  },
+});
+
+export const mainCommand = defineCommand({
+  meta: {
+    name: "kesha",
+    version: pkg.version,
+    description:
+      "Kesha Voice Kit — open-source voice toolkit for Apple Silicon.\n" +
+      "  Run 'kesha install [--no-cache]' to download engine and models.\n" +
+      "  Run 'kesha status' to inspect installed backend.",
+  },
+  args: {
+    json: {
+      type: "boolean",
+      description: "Output results as JSON",
+      default: false,
+    },
+    verbose: {
+      type: "boolean",
+      description: "Show language detection details",
+      default: false,
+    },
+    lang: {
+      type: "string",
+      description: "Expected language code (ISO 639-1), warn if mismatch",
+    },
+  },
+  async run({ args }: { args: MainCommandArgs }) {
+    const files = args._;
+
+    if (files.length === 0) {
+      log.info("Usage: kesha <audio_file> [audio_file ...]\n       kesha install [--no-cache]\n       kesha status");
+      process.exit(1);
+    }
+
+    let hasError = false;
+    const results: TranscribeResult[] = [];
+
+    const wantsLangId = !!(args.lang || args.verbose || args.json);
+
+    for (const file of files) {
+      try {
+        let audioLanguage: LangDetectResult | undefined;
+        if (wantsLangId) {
+          const audioResult = await detectAudioLanguageEngine(file);
+          if (audioResult && audioResult.code) {
+            audioLanguage = audioResult;
+          }
+        }
+
+        if (audioLanguage && args.lang && audioLanguage.confidence > 0.8) {
+          const mismatch = checkLanguageMismatch(args.lang, audioLanguage.code);
+          if (mismatch) log.warn(`${file}: ${mismatch} (from audio)`);
+        }
+
+        const text = await transcribe(file);
+
+        const tinyldLang = detectLanguage(text);
+        let textLanguage: LangDetectResult | undefined;
+
+        if (wantsLangId) {
+          const engineTextResult = await detectTextLanguageEngine(text);
+          if (engineTextResult && engineTextResult.code) {
+            textLanguage = engineTextResult;
+          }
+        }
+
+        const lang = textLanguage?.code || tinyldLang;
+
+        const mismatchWarning = checkLanguageMismatch(args.lang, lang);
+        if (mismatchWarning) log.warn(`${file}: ${mismatchWarning}`);
+
+        results.push({
+          file,
+          text,
+          lang,
+          audioLanguage,
+          textLanguage: textLanguage ?? (tinyldLang ? { code: tinyldLang, confidence: 0 } : undefined),
+        });
+      } catch (err: unknown) {
+        hasError = true;
+        const message = err instanceof Error ? err.message : String(err);
+        log.error(`${file}: ${message}`);
+      }
+    }
+
+    if (args.json) {
+      process.stdout.write(formatJsonOutput(results));
+    } else if (args.verbose) {
+      process.stdout.write(formatVerboseOutput(results));
+    } else {
+      process.stdout.write(formatTextOutput(results));
+    }
+
+    if (hasError) process.exit(1);
+  },
+});
+
+export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
+  const [firstArg, ...restArgs] = rawArgs;
+
+  if (firstArg === "install") {
+    await runMain(installCommand, { rawArgs: restArgs });
+    return;
+  }
+
+  if (firstArg === "status") {
+    await runMain(statusCommand, { rawArgs: restArgs });
+    return;
+  }
+
+  await runMain(mainCommand, { rawArgs });
+}
+
+export type TranscribeResult = {
+  file: string;
+  text: string;
+  lang: string;
+  audioLanguage?: LangDetectResult;
+  textLanguage?: LangDetectResult;
+};
+
+export function formatTextOutput(results: TranscribeResult[]): string {
+  if (results.length === 1) {
+    return results[0].text + "\n";
+  }
+  return results
+    .map((r, i) => (i > 0 ? "\n" : "") + `=== ${r.file} ===\n${r.text}\n`)
+    .join("");
+}
+
+export function formatVerboseOutput(results: TranscribeResult[]): string {
+  return results
+    .map((r, i) => {
+      const lines: string[] = [];
+      if (results.length > 1) {
+        if (i > 0) lines.push("");
+        lines.push(`=== ${r.file} ===`);
+      }
+      if (r.audioLanguage) {
+        lines.push(`Audio language: ${r.audioLanguage.code} (confidence: ${r.audioLanguage.confidence.toFixed(2)})`);
+      }
+      const textLang = r.textLanguage ?? (r.lang ? { code: r.lang, confidence: 0 } : null);
+      if (textLang) {
+        const confStr = textLang.confidence > 0 ? ` (confidence: ${textLang.confidence.toFixed(2)})` : "";
+        lines.push(`Text language: ${textLang.code}${confStr}`);
+      }
+      lines.push("---");
+      lines.push(r.text);
+      return lines.join("\n");
+    })
+    .join("\n") + "\n";
+}
+
+export function formatJsonOutput(results: TranscribeResult[]): string {
+  return JSON.stringify(results, null, 2) + "\n";
+}
+
+if (import.meta.main) {
+  await runCli();
+}

package/src/engine-install.ts

@@ -0,0 +1,70 @@
+import { dirname } from "path";
+import { existsSync, mkdirSync, chmodSync } from "fs";
+import { getEngineBinPath } from "./engine";
+import { log } from "./log";
+import { streamResponseToFile } from "./progress";
+
+const GITHUB_REPO = "drakulavich/kesha-voice-kit";
+
+function getEngineBinaryName(): string {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  if (platform === "darwin" && arch === "arm64") return "kesha-engine-darwin-arm64";
+  if (platform === "linux" && arch === "x64") return "kesha-engine-linux-x64";
+  if (platform === "win32" && arch === "x64") return "kesha-engine-windows-x64.exe";
+
+  throw new Error(`Unsupported platform: ${platform} ${arch}`);
+}
+
+export async function downloadEngine(noCache = false): Promise<string> {
+  const binPath = getEngineBinPath();
+
+  if (!noCache && existsSync(binPath)) {
+    log.success("Engine binary already installed.");
+  } else {
+    const binaryName = getEngineBinaryName();
+    const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+    const version = typeof pkg.version === "string" ? pkg.version : "unknown";
+    const url = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${binaryName}`;
+
+    mkdirSync(dirname(binPath), { recursive: true });
+
+    let res: Response;
+    try {
+      res = await fetch(url, { redirect: "follow" });
+    } catch (e) {
+      throw new Error(
+        `Failed to fetch engine binary: ${e instanceof Error ? e.message : e}\n  Fix: Check your network connection and try again`,
+      );
+    }
+
+    if (!res.ok) {
+      throw new Error(
+        `Failed to download engine binary (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
+      );
+    }
+
+    await streamResponseToFile(res, binPath, "kesha-engine binary");
+    chmodSync(binPath, 0o755);
+    log.success("Engine binary downloaded.");
+  }
+
+  log.progress("Installing models...");
+  const proc = Bun.spawnSync([binPath, "install", ...(noCache ? ["--no-cache"] : [])], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (proc.stderr.toString()) {
+    process.stderr.write(proc.stderr.toString());
+  }
+
+  if (proc.exitCode !== 0) {
+    const detail = proc.stderr.toString().trim();
+    throw new Error(detail ? `Failed to install models: ${detail}` : "Failed to install models");
+  }
+
+  log.success("Backend installed successfully.");
+  return binPath;
+}

package/src/engine.ts

@@ -0,0 +1,83 @@
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync } from "fs";
+
+export interface LangDetectResult {
+  code: string;
+  confidence: number;
+}
+
+export function getEngineBinPath(): string {
+  return join(homedir(), ".cache", "kesha", "engine", "bin", "kesha-engine");
+}
+
+export function isEngineInstalled(): boolean {
+  return existsSync(getEngineBinPath());
+}
+
+async function runEngine(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const binPath = getEngineBinPath();
+  const proc = Bun.spawn([binPath, ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
+}
+
+export async function transcribeEngine(audioPath: string): Promise<string> {
+  const { stdout, stderr, exitCode } = await runEngine(["transcribe", audioPath]);
+  if (exitCode !== 0) {
+    throw new Error(stderr || `kesha-engine exited with code ${exitCode}`);
+  }
+  return stdout;
+}
+
+export function parseLangResult(stdout: string): LangDetectResult | null {
+  try {
+    const parsed = JSON.parse(stdout);
+    if (typeof parsed.code !== "string" || typeof parsed.confidence !== "number") {
+      return null;
+    }
+    return { code: parsed.code, confidence: parsed.confidence };
+  } catch {
+    return null;
+  }
+}
+
+export async function detectAudioLanguageEngine(audioPath: string): Promise<LangDetectResult | null> {
+  if (!isEngineInstalled()) return null;
+  const { stdout, exitCode } = await runEngine(["detect-lang", audioPath]);
+  if (exitCode !== 0) return null;
+  return parseLangResult(stdout);
+}
+
+export async function detectTextLanguageEngine(text: string): Promise<LangDetectResult | null> {
+  if (!isEngineInstalled()) return null;
+  const { stdout, exitCode } = await runEngine(["detect-text-lang", text]);
+  if (exitCode !== 0) return null;
+  return parseLangResult(stdout);
+}
+
+export interface EngineCapabilities {
+  protocolVersion: number;
+  backend: string;
+  features: string[];
+}
+
+export async function getEngineCapabilities(): Promise<EngineCapabilities | null> {
+  if (!isEngineInstalled()) return null;
+  const { stdout, exitCode } = await runEngine(["--capabilities-json"]);
+  if (exitCode !== 0) return null;
+  try {
+    return JSON.parse(stdout) as EngineCapabilities;
+  } catch {
+    return null;
+  }
+}

package/src/lang-id.ts

@@ -0,0 +1,2 @@
+export type { LangDetectResult } from "./engine";
+export { detectAudioLanguageEngine as detectAudioLanguage } from "./engine";

package/src/lib.ts

@@ -0,0 +1,17 @@
+import { existsSync } from "fs";
+import { transcribe as internalTranscribe, type TranscribeOptions } from "./transcribe";
+import { downloadEngine } from "./engine-install";
+
+export type { TranscribeOptions };
+export { downloadEngine as downloadModel };
+
+export async function transcribe(
+  audioPath: string,
+  options: TranscribeOptions = {},
+): Promise<string> {
+  if (!existsSync(audioPath)) {
+    throw new Error(`File not found: ${audioPath}`);
+  }
+
+  return internalTranscribe(audioPath, { ...options, silent: true });
+}

package/src/log.ts

@@ -0,0 +1,9 @@
+import pc from "picocolors";
+
+export const log = {
+  info: (msg: string) => console.log(msg),
+  success: (msg: string) => console.log(pc.green(msg)),
+  progress: (msg: string) => console.log(pc.cyan(msg)),
+  warn: (msg: string) => console.error(pc.yellow(msg)),
+  error: (msg: string) => console.error(pc.red(msg)),
+};

package/src/models.ts

@@ -0,0 +1,6 @@
+import { isEngineInstalled } from "./engine";
+export { downloadEngine } from "./engine-install";
+
+export function isModelInstalled(): boolean {
+  return isEngineInstalled();
+}

package/src/progress.ts

@@ -0,0 +1,80 @@
+import { log } from "./log";
+
+const BAR_WIDTH = 20;
+
+export function formatBytes(bytes: number): string {
+  return `${(bytes / 1024 / 1024).toFixed(1)}MB`;
+}
+
+export function formatProgressBar(label: string, downloaded: number, total: number): string {
+  const pct = total <= 0 ? 0 : Math.min(100, Math.floor((downloaded / total) * 100));
+  const filled = Math.round((pct / 100) * BAR_WIDTH);
+  const empty = BAR_WIDTH - filled;
+  const bar = "█".repeat(filled) + "░".repeat(empty);
+  return `${label}  [${bar}] ${pct}%  ${formatBytes(downloaded)}/${formatBytes(total)}`;
+}
+
+export async function streamResponseToFile(
+  res: Response,
+  destPath: string,
+  label: string,
+): Promise<number> {
+  if (!res.body) {
+    throw new Error(
+      `Download failed: empty response for ${label}\n  Fix: Try again — the server may be temporarily unavailable`,
+    );
+  }
+
+  const totalBytes = Number(res.headers.get("content-length") || 0);
+  const progress = createProgressBar(label, totalBytes);
+
+  const writer = Bun.file(destPath).writer();
+  let bytes = 0;
+  try {
+    for await (const chunk of res.body) {
+      writer.write(chunk);
+      bytes += chunk.length;
+      progress.update(chunk.length);
+    }
+  } finally {
+    writer.end();
+  }
+
+  progress.finish();
+  return bytes;
+}
+
+export function createProgressBar(label: string, totalBytes: number): {
+  update(downloadedBytes: number): void;
+  finish(): void;
+} {
+  const isTTY = process.stderr.isTTY;
+
+  if (!isTTY || totalBytes <= 0) {
+    const sizeInfo = totalBytes > 0 ? ` (${formatBytes(totalBytes)})` : "";
+    log.progress(`Downloading ${label}${sizeInfo}...`);
+    return {
+      update() {},
+      finish() {
+        log.success(`Downloaded ${label} ✓`);
+      },
+    };
+  }
+
+  let current = 0;
+  let lastPct = -1;
+  return {
+    update(downloadedBytes: number) {
+      current += downloadedBytes;
+      const pct = totalBytes > 0 ? Math.floor((current / totalBytes) * 100) : 0;
+      if (pct === lastPct) return;
+      lastPct = pct;
+      const line = formatProgressBar(label, current, totalBytes);
+      process.stderr.write(`\r${line}`);
+    },
+    finish() {
+      const line = formatProgressBar(label, totalBytes, totalBytes);
+      process.stderr.write(`\r${line}\n`);
+    },
+  };
+}

package/src/status.ts

@@ -0,0 +1,43 @@
+import { isEngineInstalled, getEngineBinPath, getEngineCapabilities } from "./engine";
+import { log } from "./log";
+import pc from "picocolors";
+
+export function formatStatusLine(
+  label: string,
+  path: string | null,
+  installed: boolean,
+  missingLabel = "not installed",
+): string {
+  const status = installed ? pc.green("✓") : pc.red(`✗ ${missingLabel}`);
+  const pathStr = path ?? "";
+  const padding = " ".repeat(Math.max(1, 50 - label.length - pathStr.length));
+  return `  ${label}:${pathStr ? `   ${pathStr}` : ""}${padding}${status}`;
+}
+
+export async function showStatus(): Promise<void> {
+  const binPath = getEngineBinPath();
+  const installed = isEngineInstalled();
+
+  log.info("Engine:");
+  log.info(formatStatusLine("Binary", installed ? binPath : null, installed));
+
+  if (installed) {
+    const caps = await getEngineCapabilities();
+    if (caps) {
+      log.info(formatStatusLine("Backend", caps.backend, true));
+      log.info(formatStatusLine("Protocol", `v${caps.protocolVersion}`, true));
+      log.info(formatStatusLine("Features", caps.features.join(", "), true));
+    } else {
+      log.info(formatStatusLine("Capabilities", null, false, "probe failed"));
+    }
+  }
+  log.info("");
+
+  log.info(formatStatusLine("Runtime", `Bun ${Bun.version}`, true));
+  log.info(formatStatusLine("Platform", `${process.platform} ${process.arch}`, true));
+  log.info("");
+
+  if (!installed) {
+    log.warn('Run "kesha install" to download the engine and models.');
+  }
+}

package/src/transcribe.ts

@@ -0,0 +1,20 @@
+import { isEngineInstalled, transcribeEngine } from "./engine";
+
+export interface TranscribeOptions {
+  silent?: boolean;
+}
+
+export async function transcribe(audioPath: string, _opts: TranscribeOptions = {}): Promise<string> {
+  if (!isEngineInstalled()) {
+    throw new Error(
+      "Error: No transcription backend is installed\n\n" +
+      "╔══════════════════════════════════════════════════════════╗\n" +
+      "║ Please run the following command to get started:         ║\n" +
+      "║                                                          ║\n" +
+      "║     bunx @drakulavich/kesha-voice-kit install               ║\n" +
+      "╚══════════════════════════════════════════════════════════╝",
+    );
+  }
+
+  return transcribeEngine(audioPath);
+}

package/tsconfig.json

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