@drakulavich/kesha-voice-kit 1.2.2 → 1.4.1

package/NOTICES.md

@@ -0,0 +1,67 @@
+# Third-Party Notices
+
+Kesha Voice Kit itself is MIT-licensed (see `LICENSE`). It bundles or downloads
+third-party models and libraries at runtime. Their licenses and attributions
+are listed below.
+
+## Models downloaded by `kesha install`
+
+### NVIDIA Parakeet TDT 0.6B v3
+
+Automatic speech recognition. CC-BY 4.0. Trained and published by NVIDIA
+Corporation; ONNX export by [istupakov/parakeet-tdt-0.6b-v3-onnx](https://huggingface.co/istupakov/parakeet-tdt-0.6b-v3-onnx).
+
+### SpeechBrain ECAPA-TDNN VoxLingua107
+
+Audio language identification. Apache 2.0. Trained by the SpeechBrain team;
+see [speechbrain/lang-id-voxlingua107-ecapa](https://huggingface.co/speechbrain/lang-id-voxlingua107-ecapa).
+
+### Silero VAD v5 (opt-in: `kesha install --vad`)
+
+Voice activity detection. MIT. Authored by [Silero Team](https://github.com/snakers4/silero-vad).
+Pinned to the `v6.2.1` tag.
+
+## Models downloaded by `kesha install --tts`
+
+### Kokoro-82M
+
+Text-to-speech (English). Apache 2.0. ONNX export by [onnx-community/Kokoro-82M-v1.0-ONNX](https://huggingface.co/onnx-community/Kokoro-82M-v1.0-ONNX).
+
+### Piper voices (Russian: `ru-denis`)
+
+Text-to-speech (multilingual, Piper VITS). MIT. Voice packs from [rhasspy/piper-voices](https://huggingface.co/rhasspy/piper-voices).
+
+### CharsiuG2P ByT5-tiny (ONNX export)
+
+Grapheme-to-phoneme conversion for Kokoro and Piper pipelines (#123).
+
+**License: CC-BY 4.0** (declared on the ONNX-export repo). Attribution required.
+
+- ONNX export: [klebster/g2p_multilingual_byT5_tiny_onnx](https://huggingface.co/klebster/g2p_multilingual_byT5_tiny_onnx) by Kleber Noel — CC-BY 4.0.
+- Base checkpoint: [charsiu/g2p_multilingual_byT5_tiny_16_layers_100](https://huggingface.co/charsiu/g2p_multilingual_byT5_tiny_16_layers_100) — **no explicit license declared on HuggingFace**; usage here follows the CC-BY 4.0 declared by the downstream export and the paper's terms.
+- Paper: Zhu, J., Zhang, C., & Jurgens, D. (2022). "ByT5 model for massively multilingual grapheme-to-phoneme conversion." [arXiv:2204.03067](https://arxiv.org/abs/2204.03067) · Interspeech 2022.
+
+## System libraries linked by the engine binary
+
+### ONNX Runtime (`ort` / `ort-sys` crates)
+
+MIT. Microsoft. The engine dynamically links a vendored `onnxruntime` shared
+library downloaded to `~/Library/Caches/ort.pyke.io/` on first build.
+
+### FluidAudio (`fluidaudio-rs` crate, CoreML backend only)
+
+Apache 2.0. [FluidInference/FluidAudio](https://github.com/FluidInference/FluidAudio).
+Linked into the engine when built with `--features coreml`.
+
+### symphonia
+
+MPL-2.0. [pdeljanov/Symphonia](https://github.com/pdeljanov/Symphonia). Audio
+container decoder.
+
+### symphonia-adapter-libopus
+
+MIT OR Apache-2.0. Opus-decoder adapter, by [aschey](https://github.com/aschey/symphonia-adapters).
+
+### libopus
+
+BSD-3-Clause. Upstream Opus codec, by Xiph.Org / the IETF Opus working group. Statically linked via `opusic-sys`.

package/README.md

@@ -30,6 +30,18 @@ kesha install       # downloads engine + models
 kesha audio.ogg     # transcript to stdout
 ```
 
+### Air-gapped / corporate mirrors
+
+Set `KESHA_MODEL_MIRROR` to redirect all HuggingFace model downloads to an internal mirror ([#121](https://github.com/drakulavich/kesha-voice-kit/issues/121)). The HF path hierarchy is preserved, so any HTTP-readable mirror populated with `wget --mirror` or `rsync` works:
+
+```bash
+export KESHA_MODEL_MIRROR=https://models.corp.internal/kesha
+kesha install        # ASR + lang-id + TTS models fetch from your mirror
+kesha status         # confirms the active Mirror URL
+```
+
+Unset / empty falls back to `huggingface.co` with no regression. The engine binary itself still comes from GitHub Releases — this env var only redirects model downloads.
+
 ## OpenClaw Integration
 
 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.
@@ -60,8 +72,10 @@ kesha audio.ogg                            # transcribe (plain text)
 kesha --format transcript audio.ogg        # text + language/confidence
 kesha --format json audio.ogg              # full JSON with lang fields
 kesha --json audio.ogg                     # alias for --format json
+kesha --toon audio.ogg                     # compact LLM-friendly TOON (same data as --json)
 kesha --verbose audio.ogg                  # show language detection details
 kesha --lang en audio.ogg                  # warn if detected language differs
+kesha --vad lecture.m4a                    # segment with Silero VAD first (long/silence-heavy audio)
 kesha status                               # show installed backend info
 ```
 
@@ -78,13 +92,25 @@ $ kesha freedom.ogg tahiti.ogg
 
 Stdout: transcript. Stderr: errors. Pipe-friendly. Also available as `parakeet` command (backward-compatible alias).
 
+### Long / silence-heavy audio: `--vad`
+
+For meetings, lectures, and podcasts, enable Silero VAD so Parakeet only sees the speech bits. Segment boundaries land at natural speech starts/ends instead of arbitrary cuts, and long silences are skipped entirely.
+
+```bash
+kesha install --vad                   # one-time, ~2.3MB
+kesha lecture.m4a                     # auto-on when audio ≥ 120s and VAD installed
+kesha --vad short-clip.ogg            # force VAD on any input
+kesha --no-vad meeting.m4a            # force VAD off even on long audio
+```
+
+Auto-triggers at 120 s so voice messages (< 30 s of near-pure speech) stay on the fast path. If you have long audio without VAD installed, Kesha prints a one-time stderr hint. Defaults: threshold 0.5, min-speech 250 ms, min-silence 100 ms, 30 ms edge padding. See issues #128 (base) and #187 (auto-trigger).
+
 ## Text-to-Speech
 
 Kesha speaks back via Kokoro-82M (English) and Piper (Russian). Voice is auto-picked from the input text's language — `en` routes to Kokoro, `ru` to Piper. Pass `--voice` to override.
 
 ```bash
-brew install espeak-ng              # one-time system dep (macOS — apt/choco elsewhere)
-kesha install --tts                 # ~390MB (Kokoro + Piper RU, opt-in)
+kesha install --tts                 # ~490MB (Kokoro + Piper RU + ONNX G2P, opt-in)
 kesha say "Hello, world" > hello.wav
 kesha say "Привет, мир" > privet.wav    # auto-routes to ru-denis
 echo "long text" | kesha say > reply.wav
@@ -93,21 +119,21 @@ kesha say --voice en-af_heart "text"    # explicit voice overrides auto-routing
 kesha say --list-voices
 ```
 
-Output format: WAV mono float32 (24 kHz for Kokoro, 22.05 kHz for Piper). OGG/Opus and MP3 are tracked in follow-up issues. Static-linking of `espeak-ng` to remove the system dep is [#124](https://github.com/drakulavich/kesha-voice-kit/issues/124).
+Output format: WAV mono float32 (24 kHz for Kokoro, 22.05 kHz for Piper). OGG/Opus and MP3 are tracked in follow-up issues. Grapheme-to-phoneme runs entirely through ONNX (CharsiuG2P ByT5-tiny, [#123](https://github.com/drakulavich/kesha-voice-kit/issues/123)) — no `espeak-ng` system dep.
 
 **Supported voices:**
 - English: `en-af_heart` (default), plus any Kokoro voice you download into `~/.cache/kesha/models/kokoro-82m/voices/`
 - Russian: `ru-denis` (default). More speakers (dmitri, irina, ruslan) are ready to drop in once needed.
-- macOS system voices (preview — dev builds only, see below): `macos-<identifier-or-language>` routes to `AVSpeechSynthesizer`. Zero install, any of the 180+ voices already on your Mac.
+- macOS system voices: `macos-<identifier-or-language>` routes to `AVSpeechSynthesizer`. Zero install, any of the 180+ voices already on your Mac.
 
-### macOS system voices (preview)
+### macOS system voices
 
-`kesha say --voice macos-*` routes through `AVSpeechSynthesizer` on macOS, so you get voice synthesis for free — no 390 MB TTS bundle, no `espeak-ng` dep. Currently gated behind the `system_tts` cargo feature; release-binary integration is tracked as part of [#141](https://github.com/drakulavich/kesha-voice-kit/issues/141).
+`kesha say --voice macos-*` routes through `AVSpeechSynthesizer` on macOS, so you get voice synthesis for free — no 490 MB TTS bundle. The sidecar binary ships alongside `kesha-engine` on darwin-arm64 releases (#141); `kesha install` places both in `~/.cache/kesha/bin/`.
 
 ```bash
-# From a dev build: `cargo build --release --features system_tts` in rust/.
-kesha say --voice macos-com.apple.voice.compact.en-US.Samantha "Hello from system TTS" > out.wav
-kesha say --voice macos-ru-RU "Привет, мир" > hello-ru.wav   # language-code fallback
+kesha say --list-voices | grep ^macos-                                       # discover installed voices
+kesha say --voice macos-com.apple.voice.compact.en-US.Samantha "Hello" > out.wav
+kesha say --voice macos-ru-RU "Привет, мир" > hello-ru.wav                   # language-code fallback
 ```
 
 Voice id format: `macos-<id>` where `<id>` is either a full Apple identifier (`com.apple.voice.compact.en-US.Samantha`) or a language code (`en-US`, `ru-RU`) — the Swift helper tries the identifier first and falls back to the language. Output is mono float32 @ 22050 Hz, structurally identical to Piper.
@@ -142,6 +168,7 @@ Kesha Voice Kit bundles open-source models optimized for on-device inference:
 | 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 |
+| Silero VAD v5 (opt-in) | Voice activity detection | ~2.3MB | [snakers4/silero-vad](https://github.com/snakers4/silero-vad) |
 
 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.
 

package/SKILL.md

@@ -1,54 +1,100 @@
-# Kesha Voice Kit
+---
+name: kesha-voice-kit
+description: Local multilingual voice toolkit — speech-to-text (STT), text-to-speech (TTS), and language detection. Runs entirely offline on Apple Silicon, Linux, and Windows. No API keys, no cloud. NVIDIA Parakeet TDT for STT across 25 European languages, Kokoro-82M + Piper VITS for TTS, plus macOS AVSpeechSynthesizer for ~180 system voices with zero install.
+emoji: 🎙️
 
-Local speech-to-text for voice messages. Runs entirely on your machine — no API keys, no cloud.
+requires:
+  bins: [kesha]
 
-## What it does
+install:
+  - kind: npm
+    packages: [@drakulavich/kesha-voice-kit]
+    flags: [--global]
+  - kind: bash
+    cmd: kesha install
+---
 
-When a voice message arrives (Telegram, WhatsApp, Slack), Kesha transcribes it and returns JSON with the transcript and detected language:
+# kesha-voice-kit
+
+Local voice toolkit: transcribe voice messages to text, synthesize speech, detect language of audio or text. Fully offline after `kesha install`. No API keys, no per-minute billing.
+
+**Trigger keywords for when to use this skill:** voice message, voice memo, .ogg, .wav, .mp3, audio file, transcribe, transcription, speech-to-text, STT, text-to-speech, TTS, synthesize speech, say, multilingual voice, multilingual ASR, language detection, offline voice, privacy, Apple Silicon, CoreML.
+
+## When to use
+
+- **Voice memo arrived** (Telegram, WhatsApp, Slack, Signal .ogg/.opus/.m4a): transcribe with `kesha --json <path>` and branch on the detected language.
+- **Need to reply with audio**: synthesize with `kesha say "<text>" > reply.wav`. Auto-routes by detected language (Kokoro-82M for English, Piper for Russian). For other languages and ~180 more voices use `--voice macos-*` on macOS (zero model download).
+- **Need to detect what language a file is in** before choosing a pipeline: `kesha --json audio.ogg` returns both audio-based and text-based language detection with confidence scores.
+
+## STT: transcribe audio
+
+```bash
+# JSON output with language detection (recommended for automation)
+kesha --json voice.ogg
+```
 
 ```json
 [{
   "file": "voice.ogg",
   "text": "Привет, как дела?",
   "lang": "ru",
+  "audioLanguage": { "code": "ru", "confidence": 0.98 },
   "textLanguage": { "code": "ru", "confidence": 0.99 }
 }]
 ```
 
-Use the `lang` field to detect which language the user spoke and respond accordingly.
+Use `lang` (or the more detailed `audioLanguage`/`textLanguage`) to decide how to respond.
+
+**Formats:** .ogg, .opus, .mp3, .m4a, .wav, .flac, .webm — decoded via symphonia, no ffmpeg required.
 
-## Setup
+**Other output modes:**
+- `kesha audio.ogg` — plain transcript on stdout
+- `kesha --format transcript audio.ogg` — transcript + `[lang: ru, confidence: 0.99]` footer
+- `kesha --verbose audio.ogg` — human-readable with language info
+- `kesha --lang en audio.ogg` — warn if detected language differs (useful sanity check)
 
-After installing the plugin, run once to download the engine and models:
+## TTS: synthesize speech
 
 ```bash
-kesha install
+kesha say "Hello, world" > hello.wav               # auto-routes en → Kokoro-82M
+kesha say "Привет, мир" > privet.wav              # auto-routes ru → Piper
+kesha say --voice macos-de-DE "Guten Tag" > de.wav # any macOS system voice — German, French, Italian, ...
+kesha say --list-voices                            # Kokoro + Piper + ~180 macos-* voices
 ```
 
-## Plain text mode
+Output: WAV mono float32. `--out <path>` writes to a file instead of stdout.
 
-If you don't need language detection, switch to plain text output in your config:
+## Language detection standalone
 
-```json
-{
-  "type": "cli",
-  "command": "kesha",
-  "args": ["{{MediaPath}}"]
-}
-```
+`kesha --json audio.ogg` includes both audio-based (`audioLanguage`) and text-based (`textLanguage`) detection. Use audio detection to identify the language before running language-specific logic.
 
-This returns just the transcript text without JSON wrapping.
+## Install
 
-## Available flags
+```bash
+bun add --global @drakulavich/kesha-voice-kit    # or: npm i -g @drakulavich/kesha-voice-kit
+kesha install                                    # downloads engine (~350 MB)
+kesha install --tts                              # adds Kokoro + Piper RU + ONNX G2P (~490 MB more, for TTS)
+```
 
-- `--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`)
+No system deps — G2P runs as ONNX alongside Kokoro/Piper. `macos-*` voices need no install either — they use voices already on the Mac.
 
 ## 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.
+**Speech-to-text (25):** 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.
+
+**Text-to-speech:** English (Kokoro-82M, ~70 voices), Russian (Piper `ru-denis`), plus any macOS system voice via `--voice macos-*`.
 
 ## Performance
 
-~19x faster than Whisper on Apple Silicon (CoreML), ~2.5x faster on CPU (ONNX).
+- ASR: ~19× faster than OpenAI Whisper on Apple Silicon (CoreML via FluidAudio), ~2.5× on CPU (ONNX via `ort`).
+- TTS: sub-second latency for short utterances on Apple Silicon.
+
+## Why local
+
+No API keys to manage. No per-minute billing. Voice data never leaves the machine — important for regulated industries, personal messaging, and anything that shouldn't be in a third-party log.
+
+## Links
+
+- Source: https://github.com/drakulavich/kesha-voice-kit
+- npm: https://www.npmjs.com/package/@drakulavich/kesha-voice-kit
+- Releases: https://github.com/drakulavich/kesha-voice-kit/releases

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.2.2",
+  "version": "1.4.1",
   "description": "Open-source voice toolkit for Apple Silicon. Speech-to-text, language detection. 25 languages.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "SKILL.md",
     "scripts/postinstall.cjs",
     "LICENSE",
+    "NOTICES.md",
     "README.md"
   ],
   "openclaw": {
@@ -29,7 +30,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.2.0"
+    "version": "1.4.1"
   },
   "scripts": {
     "test": "bun test",
@@ -68,6 +69,7 @@
     "typescript": "^6.0.2"
   },
   "dependencies": {
+    "@toon-format/toon": "^2.1.0",
     "citty": "^0.2.2",
     "fastest-levenshtein": "^1.0.16",
     "picocolors": "^1.1.1",

package/src/cli/dispatch.ts

@@ -0,0 +1,40 @@
+import { runMain } from "citty";
+import { log } from "../log";
+import { suggestCommand } from "../suggest-command";
+import { installCommand } from "./install";
+import { sayCommand } from "./say";
+import { statusCommand } from "./status";
+import { mainCommand } from "./main";
+
+const SUBCOMMANDS = ["install", "status", "say"];
+
+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;
+  }
+
+  if (firstArg === "say") {
+    await runMain(sayCommand, { rawArgs: restArgs });
+    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/cli/install.ts

@@ -0,0 +1,108 @@
+import { defineCommand } from "citty";
+import { downloadEngine } from "../engine-install";
+import { getEngineBinPath } from "../engine";
+import { readStarSeen, shouldShowStarPrompt, writeStarSeen } from "../star";
+import { log } from "../log";
+
+interface InstallCommandArgs {
+  coreml: boolean;
+  onnx: boolean;
+  "no-cache": boolean;
+  tts: boolean;
+  vad: boolean;
+}
+
+const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json();
+
+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 askForStar() {
+  // Gate on major-or-minor bump only — patch releases and re-installs of the
+  // same version shouldn't nag. First-ever install (no marker) still prompts.
+  const currentVersion = typeof pkg.version === "string" ? pkg.version : null;
+  if (!currentVersion) return;
+  const binPath = getEngineBinPath();
+  const seen = readStarSeen(binPath);
+  if (!shouldShowStarPrompt(currentVersion, seen)) {
+    return;
+  }
+  // Record the version up front so a single run never prompts twice, even
+  // if the gh subprocess below throws.
+  try {
+    writeStarSeen(binPath, currentVersion);
+  } catch {
+    // Non-fatal — falling through to the prompt is still OK, just means we
+    // may nag again on the next install if the write failed for IO reasons.
+  }
+
+  const gh = Bun.which("gh");
+  if (!gh) {
+    log.info("\nIf you enjoy Kesha Voice Kit, consider starring the repo:");
+    log.info("  https://github.com/drakulavich/kesha-voice-kit");
+    return;
+  }
+  const authCheck = Bun.spawnSync([gh, "auth", "status"], { stdout: "ignore", stderr: "ignore" });
+  if (authCheck.exitCode !== 0) return;
+  const starred = Bun.spawnSync([gh, "api", "user/starred/drakulavich/kesha-voice-kit"], { stdout: "ignore", stderr: "ignore" });
+  if (starred.exitCode === 0) return; // already starred
+  log.info("\n⭐ If you enjoy Kesha Voice Kit, star it on GitHub:");
+  log.info("  https://github.com/drakulavich/kesha-voice-kit");
+  log.info('  Or run: gh api -X PUT /user/starred/drakulavich/kesha-voice-kit');
+}
+
+async function performInstall(noCache: boolean, backend?: string, tts = false, vad = false) {
+  try {
+    await downloadEngine(noCache, backend, { tts, vad });
+    await askForStar();
+  } 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: {
+    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",
+      default: false,
+    },
+    tts: {
+      type: "boolean",
+      description: "Also install TTS models (Kokoro EN + Piper RU + ONNX G2P, ~490MB)",
+      default: false,
+    },
+    vad: {
+      type: "boolean",
+      description: "Also install Silero VAD (~2.3MB) for long-audio preprocessing",
+      default: false,
+    },
+  },
+  async run({ args }: { args: InstallCommandArgs }) {
+    const backend = resolveBackendFlag(args.coreml, args.onnx);
+    await performInstall(args["no-cache"], backend, args.tts, args.vad);
+  },
+});

package/src/cli/main.ts

@@ -0,0 +1,177 @@
+import { defineCommand } from "citty";
+import { detect } from "tinyld";
+import { transcribe } from "../lib";
+import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
+import type { LangDetectResult } from "../engine";
+import { log } from "../log";
+import type { TranscribeResult } from "../types";
+import {
+  formatJsonOutput,
+  formatTextOutput,
+  formatTranscriptOutput,
+  formatVerboseOutput,
+} from "../format";
+import { formatToonOutput } from "../toon";
+
+const pkg = await Bun.file(new URL("../../package.json", import.meta.url)).json();
+
+interface MainCommandArgs {
+  _: string[];
+  json: boolean;
+  toon: boolean;
+  verbose: boolean;
+  debug: boolean;
+  vad: boolean;
+  "no-vad": boolean;
+  format?: string;
+  lang?: string;
+}
+
+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}"`;
+}
+
+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,
+    },
+    toon: {
+      type: "boolean",
+      description: "Output results as TOON (compact, LLM-friendly encoding of the same data as --json)",
+      default: false,
+    },
+    verbose: {
+      type: "boolean",
+      description: "Show language detection details",
+      default: false,
+    },
+    format: {
+      type: "string",
+      description: "Output format: transcript (enriched text with lang/confidence)",
+    },
+    lang: {
+      type: "string",
+      description: "Expected language code (ISO 639-1), warn if mismatch",
+    },
+    debug: {
+      type: "boolean",
+      description: "Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)",
+      default: false,
+    },
+    vad: {
+      type: "boolean",
+      description: "Force Silero VAD preprocessing (kesha install --vad first). Without this, VAD auto-engages on audio ≥ 120s.",
+      default: false,
+    },
+    "no-vad": {
+      type: "boolean",
+      description: "Disable VAD preprocessing regardless of duration or install state",
+      default: false,
+    },
+  },
+  async run({ args }: { args: MainCommandArgs }) {
+    if (args.debug) log.debugEnabled = true;
+    const files = args._;
+
+    if ((args.json || args.format === "json") && args.toon) {
+      log.error("--json and --toon are mutually exclusive (pick one output format).");
+      process.exit(2);
+    }
+
+    if (args.vad && args["no-vad"]) {
+      log.error("--vad and --no-vad are mutually exclusive.");
+      process.exit(2);
+    }
+    const vadMode = args.vad ? "on" : args["no-vad"] ? "off" : "auto";
+
+    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 || args.toon || args.format === "transcript" || args.format === "json");
+
+    for (const file of files) {
+      const startedAt = performance.now();
+      try {
+        // Run audio lang-id and transcription concurrently
+        const [audioResult, text] = await Promise.all([
+          wantsLangId ? detectAudioLanguageEngine(file) : Promise.resolve(null),
+          transcribe(file, { vad: vadMode }),
+        ]);
+
+        let audioLanguage: LangDetectResult | undefined;
+        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 tinyldLang = wantsLangId ? 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),
+          sttTimeMs: Math.round(performance.now() - startedAt),
+        });
+      } catch (err: unknown) {
+        hasError = true;
+        const message = err instanceof Error ? err.message : String(err);
+        log.error(`${file}: ${message}`);
+      }
+    }
+
+    if (args.json || args.format === "json") {
+      process.stdout.write(formatJsonOutput(results));
+    } else if (args.toon) {
+      process.stdout.write(formatToonOutput(results));
+    } else if (args.format === "transcript") {
+      process.stdout.write(formatTranscriptOutput(results));
+    } else if (args.verbose) {
+      process.stdout.write(formatVerboseOutput(results));
+    } else {
+      process.stdout.write(formatTextOutput(results));
+    }
+
+    if (hasError) process.exit(1);
+  },
+});