@drakulavich/kesha-voice-kit 1.27.0 → 1.28.0-alpha.1

package/README.md

@@ -11,12 +11,12 @@
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
 </p>
 
-<p align="center"><b>Give your local tools and LLM agents a voice.</b><br>Fast speech-to-text, text-to-speech, voice-activity detection, and language detection in one local-first CLI: Apple Silicon CoreML first, ONNX fallback on supported Linux/Windows builds.</p>
+<p align="center"><b>Give your local tools and LLM agents a voice.</b><br>Fast speech-to-text, text-to-speech, voice-activity detection, and language detection in one local-first CLI — CoreML on Apple Silicon, ONNX on Linux and Windows.</p>
 
 - **Transcribe locally** — [25 languages](docs/languages.md#speech-to-text-25), up to ~19x faster than Whisper on Apple Silicon, ~2.5x on CPU
 - **Speak back** — text-to-speech in [9 languages](docs/languages.md#text-to-speech)
 - **Plug into agents** — ship voice workflows as CLI commands, an MCP server, an <a href="docs/openclaw.md">OpenClaw</a> skill, or a <a href="docs/hermes.md">Hermes</a> agent
-- **Small Rust engine** — single ~60MB binary, no ffmpeg, no Python, no native Node addons
+- **Small Rust engine** — single ~65MB binary, no ffmpeg, no Python, no native Node addons
 
 <p align="center">
   <img src="https://github.com/drakulavich/kesha-voice-kit/raw/main/demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
@@ -24,30 +24,46 @@
 
 ## Quick Start
 
-Runtime: **[Bun](https://bun.sh)** >= 1.3.0 · Platforms: macOS arm64, Linux x64, Windows x64. Linux and Windows run the ONNX engine — everything except microphone capture (`kesha record`), macOS system voices, speaker diarization, and text language detection, which need Apple frameworks.
+Runtime: **[Bun](https://bun.sh)** >= 1.3.0.
 
 ```bash
-# 1. Install Bun (skip if you have it) — Linux & macOS:
-curl -fsSL https://bun.sh/install | bash        # or: brew install oven-sh/bun/bun
-# Windows: powershell -c "irm bun.sh/install.ps1 | iex"
-# if `bun --version` fails, reload PATH: exec $SHELL -l
+# 1. Install Bun (skip if you have it)
+curl -fsSL https://bun.sh/install | bash        # macOS/Linux — or: brew install oven-sh/bun/bun
+powershell -c "irm bun.sh/install.ps1 | iex"    # Windows
 
-# 2. Install Kesha:
+# 2. Install Kesha
 bun add -g @drakulavich/kesha-voice-kit
 kesha --version                                 # confirms `kesha` resolved on PATH
-kesha install --plan                            # preview exact download/disk sizes first — downloads nothing
-kesha install        # ~2.5 GB on Linux/Windows; ~0.6 GB on Apple Silicon, whose CoreML
-                      # engine uses a different, smaller model set. Explicit — never automatic.
-                      # No progress bar during the model step; can take several minutes.
-                      # Prefer a guided wizard? `kesha init` walks through the same choices interactively.
-
-# 3. Transcribe:
-kesha audio.ogg      # transcript to stdout
+
+# 3. Download the engine and models — pick one path
+kesha init                                      # guided: backend, languages, TTS voices
+kesha install --plan && kesha install           # manual: preview the sizes, then download
+
+# 4. Transcribe
+kesha audio.ogg                                 # transcript to stdout
 ```
 
-Prefer Homebrew, Docker, or Nix? See [Other install methods](#other-install-methods).
+`kesha install` pulls ~2.5 GB on Linux/Windows and ~0.6 GB on Apple Silicon, whose CoreML engine reads a smaller model set. It is always explicit — nothing downloads behind your back — and the model step has no progress bar, so expect a few quiet minutes. If `bun --version` fails right after step 1, reload your PATH: `exec $SHELL -l`.
+
+Prefer Homebrew or Docker? See [Other install methods](#other-install-methods).
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
 
+### Platform support
+
+All three targets transcribe, detect the spoken language, run VAD, and speak. The macOS-only rows need Apple frameworks — they are not a missing port. Windows is a tested path rather than a published binary nobody ran: CI does a cold `kesha install` on `windows-latest`, transcribes a fixture, and round-trips a synthesis ([#216](https://github.com/drakulavich/kesha-voice-kit/issues/216), [#667](https://github.com/drakulavich/kesha-voice-kit/pull/667)).
+
+| | macOS arm64 | Linux x64 | Windows x64 |
+|---|:---:|:---:|:---:|
+| Transcribe · audio language ID · [VAD](docs/vad.md) | CoreML / ANE | ONNX CPU | ONNX CPU |
+| TTS — `en` `ru` `es` `fr` `it` `pt` | ✅ | ✅ | ✅ |
+| TTS — `hi` `ja` `zh` and macOS system voices | ✅ | — | — |
+| Mic capture and live dictation (`kesha record`) | ✅ | — | — |
+| Speaker diarization (`--speakers`) | ✅ | — | — |
+| Word-level timestamps (`words` in `--json`) | ✅ | ✅ | ✅ |
+| Voice auto-routing from the text's language | ✅ | pass `--lang` | pass `--lang` |
+
+Intel Macs get no published engine binary. Full matrix with maturity labels: [docs/product-positioning.md](docs/product-positioning.md#platform-matrix).
+
 ## Speech-to-text
 
 ```bash
@@ -55,6 +71,7 @@ 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 --timestamps audio.ogg        # JSON with timestamped segments
+kesha --itn audio.ogg                      # spelled-out numbers -> digits
 kesha --toon audio.ogg                     # compact LLM-friendly TOON
 kesha status                               # show installed backend info
 kesha status --disk                        # + recursive cache disk usage
@@ -73,18 +90,22 @@ $ kesha freedom.ogg tahiti.ogg
 ```
 
 - **Record from the mic (macOS):** `kesha record --out hello.wav` writes microphone audio to a WAV file (`kesha hello.wav` transcribes it). macOS prompts for microphone access on first use — grant it under System Settings → Privacy & Security → Microphone if it was denied. On Linux/Windows or headless boxes, pass any existing audio file straight to `kesha` instead.
+- **Dictate straight to text (darwin-arm64):** `kesha record --live` transcribes the mic as it captures and prints the transcript to stdout — no WAV in between, so it pipes (`kesha record --live | pbcopy`). Progress goes to stderr. Other platforms keep the two-step `record --out` + transcribe flow. An interruption is recoverable: Ctrl-C (or SIGTERM) stops the session, still prints what you dictated, and exits 130/143, and the audio is spilled to a recovery WAV under `~/.cache/kesha/recordings/` — named on stderr when the session starts, deleted once the transcript has actually been delivered, kept if anything — a signal, a crash, a closed terminal, a dead pipe — got in the way first ([#962](https://github.com/drakulavich/kesha-voice-kit/issues/962)).
 - **Long / silence-heavy audio:** install VAD (`kesha install --vad`); Kesha auto-uses it past 120 s. Without VAD, long audio falls back to fixed ASR chunks. See [docs/vad.md](docs/vad.md).
 - **Speaker diarization** (darwin-arm64): `kesha install --diarize` (which installs VAD too), then `kesha --json --speakers meeting.m4a` stamps each segment with a `speaker` id. `--speakers` engages VAD windowing itself at any duration, so it cannot be combined with `--no-vad`. Linux/Windows return a clear "darwin-arm64 only" error ([#199](https://github.com/drakulavich/kesha-voice-kit/issues/199)).
+- **Word-level timestamps** (every platform): `kesha --json --timestamps audio.ogg` adds a `words` array to each segment — `{ "word": "email", "start": 0.72, "end": 1.12 }` — on the same file-relative clock as the segment, so a word always lies inside the segment carrying it. Read them off the decoder's own frame grid, so: times are quantised to 0.08 s, consecutive spans may overlap (each `end` is a per-word duration prediction, not the next word's `start`), `end >= start` rather than strictly greater, and punctuation stays attached to its word. The key is simply absent where a segment has none — any segment `--itn` rewrote, for one — so check the `transcribe.words` capability rather than expecting an empty array ([#720](https://github.com/drakulavich/kesha-voice-kit/issues/720)).
+- **Written-form numbers:** `--itn` rewrites what the model spells out — `"two hundred thirty two"` → `"232"`, `"five dollars and fifty cents"` → `"$5.50"`. Opt-in, every platform, timestamps untouched. English-only in practice; Russian and the rest pass through unchanged. Spoken punctuation names stay words (`"dot"`, `"comma"`, `"the period of growth"`) because Kesha transcribes speech rather than dictation — so `"example dot com"` keeps its words too ([#822](https://github.com/drakulavich/kesha-voice-kit/issues/822)).
 
 ## Text-to-speech
 
-Kesha speaks back in [9 languages](docs/languages.md#text-to-speech), auto-picking the voice from the text's language. Override with `--lang <code>` or `--voice <id>`.
+Kesha speaks back in [9 languages](docs/languages.md#text-to-speech). On macOS it picks the voice from the text's own language; on Linux and Windows text detection needs Apple frameworks, so state the language with `--lang <code>` (or the voice with `--voice <id>`) — otherwise the engine default speaks.
 
 ```bash
 kesha install --tts                              # English voices; sizes differ per platform — preview: kesha install --plan
 kesha install --tts en ru                        # + Russian (+~890 MB, Vosk)
 kesha say "Hello, world" > hello.wav
-kesha say "Привет, мир" > privet.wav             # auto-routes by language
+kesha say "Привет, мир" > privet.wav             # auto-routes by language (macOS)
+kesha say --lang ru "Привет, мир" > privet.wav   # explicit — the Linux/Windows path
 kesha say --voice ru-vosk-m02 "Голос в текст." > ru.wav
 ```
 
@@ -100,7 +121,7 @@ kesha say "Hello" --format flac --out hi.flac     # FLAC — lossless, plays in
 
 ## Languages
 
-**Speech-to-text** spans 25 languages and **text-to-speech** covers English, Russian, and select multilingual voices — full tables with codes and flags in **[docs/languages.md](docs/languages.md)**. Audio language detection identifies [107 languages](https://huggingface.co/speechbrain/lang-id-voxlingua107-ecapa).
+**Speech-to-text** spans 25 languages and **text-to-speech** 9 — full tables with codes, flags, and per-platform availability in **[docs/languages.md](docs/languages.md)**. Audio language detection identifies [107 languages](https://huggingface.co/speechbrain/lang-id-voxlingua107-ecapa).
 
 ## Performance
 
@@ -110,16 +131,16 @@ Compared against Whisper `large-v3-turbo`, all engines auto-detecting language:
 
 ![Benchmark: openai-whisper vs faster-whisper vs Kesha Voice Kit](https://github.com/drakulavich/kesha-voice-kit/raw/main/docs/assets/benchmark.svg)
 
-Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md).
+Full per-file breakdown (Russian + English): [BENCHMARK.md](BENCHMARK.md). The CPU figure is the ONNX engine on an M2's CPU cores; no x86 numbers are published yet.
 
 ## Other install methods
 
-All of these install the Bun CLI wrapper; engine + models still download explicitly via `kesha install`.
+All of these install the Bun CLI wrapper; engine + models still download explicitly via `kesha install`. (Nix is the exception — it currently builds only the engine from source; see below.)
 
 - **Homebrew** — `brew install drakulavich/tap/kesha-voice-kit` · [docs/homebrew.md](docs/homebrew.md)
-- **Linux packages** (`.deb`/`.rpm`, x64) — not currently published, see [docs/linux-packages.md](docs/linux-packages.md)
+- **Linux packages** (`.deb`/`.rpm`, x64) — published on CLI releases, see [docs/linux-packages.md](docs/linux-packages.md)
 - **Docker** (GHCR image) — [docs/docker.md](docs/docker.md)
-- **Nix** (`aarch64-darwin` / `x86_64-linux`) — `nix run github:drakulavich/kesha-voice-kit -- install` · [docs/nix-install.md](docs/nix-install.md)
+- **Nix** (`aarch64-darwin` / `x86_64-linux`) — builds the engine from source (`nix build github:drakulavich/kesha-voice-kit#kesha-engine`). The full `kesha` CLI via `nix run` / `nix profile install` is **not yet available** — it needs a maintainer with Nix to populate a build hash ([#946](https://github.com/drakulavich/kesha-voice-kit/issues/946)). · [docs/nix-install.md](docs/nix-install.md)
 - **Shell completions + manpage** — `kesha completions bash|zsh|fish` and `kesha manpage` print the packaged files to install wherever your shell expects them.
 
 ## Integrations
@@ -135,13 +156,14 @@ All of these install the Bun CLI wrapper; engine + models still download explici
 - [Architecture](docs/architecture.md) — runtime data flow, the models that ship, the CLI ↔ Rust engine boundary, model pinning, and where tests live.
 - [Use cases](docs/use-cases.md) — copy-paste recipes (transcribe a meeting, speak from OpenClaw, run offline, move the cache).
 - [Product positioning](docs/product-positioning.md) — supported workflows, non-goals, maturity labels, platform matrix.
+- [Changelog](CHANGELOG.md) — every release, with the behaviour changes spelled out.
 - **Diagnostics:** `kesha doctor`, `kesha support-bundle` (redacted `.tar.gz` for issues), and `kesha logs` produce local, content-free diagnostics — see [docs/diagnostic-logs.md](docs/diagnostic-logs.md). Every failure prints a stable `error [CODE]: …` line and a documented [process exit code](docs/errors.md#process-exit-codes).
-- **Scripting & CI:** `--json` (or `--toon`) for machine-readable output, `--quiet`/`-q` to silence progress, and `--no-color` (or `NO_COLOR=1`) for plain logs. Colors switch off automatically when `CI=true`.
+- **Scripting & CI:** `--json` (or `--toon`) for machine-readable output, `--include-errors` (with either) to get per-file failures on stdout alongside the results, `--quiet`/`-q` to silence progress, and `--no-color` (or `NO_COLOR=1`) for plain logs. Colors switch off automatically when `CI=true`.
 - **Privacy / Local Stats:** Stats are **off by default** and fully local. Opt in with `kesha stats enable` to record content-free operational metrics in a local SQLite database — never networked, never storing audio, transcripts, text, or paths. Full commands & lifecycle: [docs/local-stats.md](docs/local-stats.md).
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md), the [Roadmap](ROADMAP.md) (Now / Next / Later), and the [Decision log](docs/decision-log.md) (why platform/model choices were made — and reversed). Dev setup: `make dev-setup` (Bun, Rust, nextest, platform libs).
+See [CONTRIBUTING.md](CONTRIBUTING.md), the [Roadmap](ROADMAP.md) (Now / Next / Later), and the [Decision log](docs/decision-log.md) (why platform/model choices were made — and reversed). Dev setup: `just dev-setup` (Bun, Rust, nextest, platform libs).
 
 ## License
 

package/SKILL.md

@@ -196,7 +196,7 @@ Format is also inferred from `--out` extension (`.ogg` / `.opus` / `.oga` → OG
 
 **Russian abbreviations** (`ru-vosk-*`): all-uppercase Cyrillic 2-5-char tokens auto-expand letter-by-letter when not pronounceable as a Russian syllable (ФСБ → "эф-эс-бэ", ВОЗ → "воз"). Disable with `--no-expand-abbrev`. See [docs/tts.md#russian-abbreviation-auto-expansion](docs/tts.md#russian-abbreviation-auto-expansion).
 
-**English acronyms** (`en-*`, Kokoro): three-table mechanism (letter-spell rule + STOP_LIST + IPA_LEXICON) auto-expands FBI → "ef bee eye" and gives EPAM/JSON/Anthropic the right IPA. Disable letter-spell with `--no-expand-abbrev`. See [docs/tts.md#english-acronym-auto-expansion](docs/tts.md#english-acronym-auto-expansion).
+**English acronyms** (`en-*`, Kokoro): three-table mechanism (letter-spell rule + STOP_LIST + IPA_LEXICON) auto-expands FBI → "ef bee eye" and gives EPAM/JSON/Anthropic the right IPA. Disable letter-spell with `--no-expand-abbrev` — honored on ONNX builds only; the released darwin-arm64 binary spells initialisms inside FluidAudio's own G2P and warns that the flag is a no-op ([#842](https://github.com/drakulavich/kesha-voice-kit/issues/842)). See [docs/tts.md#english-acronym-auto-expansion](docs/tts.md#english-acronym-auto-expansion).
 
 **Russian word stress** (`ru-vosk-*` only): `<emphasis>сл+ово</emphasis>` shifts stress to the vowel marked with `+`. `<emphasis level="none">сл+ово</emphasis>` strips the `+` (cancel inherited emphasis). Other voices (`en-*`, `macos-*`) silently strip the `+` and warn once per process. Auto-stress dictionary not provided — caller writes the `+` manually. Closes [#233](https://github.com/drakulavich/kesha-voice-kit/issues/233).
 

package/completions/kesha.bash

@@ -10,7 +10,7 @@ _kesha_completion() {
 
   if [[ "$COMP_CWORD" -eq 1 ]]; then
     if [[ "$cur" == -* ]]; then
-      COMPREPLY=( $(compgen -W "--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad --quiet --no-color" -- "$cur") )
+      COMPREPLY=( $(compgen -W "--help -h --version -v --json --toon --timestamps --speakers --itn --include-errors --verbose --format --lang --debug --vad --no-vad --quiet --no-color" -- "$cur") )
     else
       COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
     fi
@@ -25,12 +25,12 @@ _kesha_completion() {
     logs) opts="--help -h --json" ;;
     manpage) opts="--help -h" ;;
     mcp) opts="--help -h" ;;
-    record) opts="--help -h --out --max-seconds --debug" ;;
+    record) opts="--help -h --out --live --max-seconds --debug" ;;
     say) opts="--help -h --voice --lang --out --rate --list-voices --ssml --format --bitrate --sample-rate --no-expand-abbrev --verbose --debug" ;;
     stats) opts="--help -h --format" ;;
     status) opts="--help -h --disk --json" ;;
     support-bundle) opts="--help -h --output --include-logs" ;;
-    *) opts="--help -h --version -v --json --toon --timestamps --speakers --include-errors --verbose --format --lang --debug --vad --no-vad --quiet --no-color" ;;
+    *) opts="--help -h --version -v --json --toon --timestamps --speakers --itn --include-errors --verbose --format --lang --debug --vad --no-vad --quiet --no-color" ;;
   esac
 
   if [[ "$cur" == -* ]]; then

package/completions/kesha.fish

@@ -7,7 +7,7 @@ complete -c kesha -n '__fish_use_subcommand' -a 'install' -d 'Download inference
 complete -c kesha -n '__fish_use_subcommand' -a 'logs' -d 'Manage local privacy-safe diagnostic logs'
 complete -c kesha -n '__fish_use_subcommand' -a 'manpage' -d 'Print the kesha(1) manpage'
 complete -c kesha -n '__fish_use_subcommand' -a 'mcp' -d 'Run a Model Context Protocol server over stdio (transcribe_audio, synthesize_speech, list_voices, list_languages). Configure an MCP client with: { command: \'kesha\', args: [\'mcp\'] }.'
-complete -c kesha -n '__fish_use_subcommand' -a 'record' -d 'Record microphone audio to a WAV file'
+complete -c kesha -n '__fish_use_subcommand' -a 'record' -d 'Record microphone audio to a WAV file, or transcribe it live'
 complete -c kesha -n '__fish_use_subcommand' -a 'say' -d 'Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
 complete -c kesha -n '__fish_use_subcommand' -a 'stats' -d 'Manage local anonymous Kesha Stats'
 complete -c kesha -n '__fish_use_subcommand' -a 'status' -d 'Show backend installation status'
@@ -20,7 +20,8 @@ complete -c kesha -n '__fish_use_subcommand' -l json -d 'Output results as JSON'
 complete -c kesha -n '__fish_use_subcommand' -l toon -d 'Output results as TOON (compact, LLM-friendly encoding of the same data as --json)'
 complete -c kesha -n '__fish_use_subcommand' -l timestamps -d 'Include timestamped transcript segments in JSON/TOON output'
 complete -c kesha -n '__fish_use_subcommand' -l speakers -d 'Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first (it installs VAD too). Implies --timestamps, and engages VAD windowing at any duration (so it cannot be combined with --no-vad).'
-complete -c kesha -n '__fish_use_subcommand' -l include-errors -d 'With --json, output { results, errors } so scripts can read per-file failures without parsing stderr'
+complete -c kesha -n '__fish_use_subcommand' -l itn -d 'Rewrite spoken-form numbers, money, dates and times to written form ("two hundred thirty two" -> "232"). English-only; other languages pass through unchanged.'
+complete -c kesha -n '__fish_use_subcommand' -l include-errors -d 'With --json or --toon, output { results, errors } so scripts can read per-file failures without parsing stderr'
 complete -c kesha -n '__fish_use_subcommand' -l verbose -d 'Show language detection details'
 complete -c kesha -n '__fish_use_subcommand' -l format -r -d 'Output format: transcript | json | toon (long-form alias for --json / --toon)'
 complete -c kesha -n '__fish_use_subcommand' -l lang -r -d 'Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch'
@@ -65,6 +66,7 @@ complete -c kesha -n '__fish_seen_subcommand_from mcp' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l help -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from record' -s h -d 'Show help'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l out -r -d 'Write recorded WAV audio to this path'
+complete -c kesha -n '__fish_seen_subcommand_from record' -l live -d 'Transcribe the microphone live and print the transcript to stdout (CoreML on Apple Silicon only)'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l max-seconds -r -d 'Maximum recording duration in seconds'
 complete -c kesha -n '__fish_seen_subcommand_from record' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l help -d 'Show help'
@@ -78,7 +80,7 @@ complete -c kesha -n '__fish_seen_subcommand_from say' -l ssml -d 'Parse input a
 complete -c kesha -n '__fish_seen_subcommand_from say' -l format -r -d 'Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l bitrate -r -d 'Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l sample-rate -r -d 'Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.'
-complete -c kesha -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable Russian acronym auto-expansion (ВОЗ → \'вэ о зэ\') for ru-vosk-* voices. <say-as interpret-as=\'characters\'> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.'
+complete -c kesha -n '__fish_seen_subcommand_from say' -l no-expand-abbrev -d 'Disable acronym auto-expansion on ru-vosk-* voices (ВОЗ → \'вэ о зэ\') and English on ONNX engine builds (FBI → \'ef bee eye\'). No effect on macOS arm64 FluidAudio, macos-* or non-English voices, which spell initialisms in their own G2P; the engine warns when the flag is ignored. <say-as interpret-as=\'characters\'> still works.'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l verbose -d 'Log TTS synthesis time to stderr'
 complete -c kesha -n '__fish_seen_subcommand_from say' -l debug -d 'Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)'
 complete -c kesha -n '__fish_seen_subcommand_from stats' -l help -d 'Show help'

package/completions/kesha.zsh

@@ -11,7 +11,7 @@ _kesha() {
     'logs:Manage local privacy-safe diagnostic logs'
     'manpage:Print the kesha(1) manpage'
     'mcp:Run a Model Context Protocol server over stdio (transcribe_audio, synthesize_speech, list_voices, list_languages). Configure an MCP client with: { command: '\''kesha'\'', args: \['\''mcp'\''\] }.'
-    'record:Record microphone audio to a WAV file'
+    'record:Record microphone audio to a WAV file, or transcribe it live'
     'say:Synthesize speech from text (TTS). Writes audio to stdout (or --out file). Defaults to WAV; use --format ogg-opus for messenger-ready voice notes.'
     'stats:Manage local anonymous Kesha Stats'
     'status:Show backend installation status'
@@ -28,7 +28,8 @@ _kesha() {
       '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
       '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
       '--speakers[Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first (it installs VAD too). Implies --timestamps, and engages VAD windowing at any duration (so it cannot be combined with --no-vad).]' \
-      '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
+      '--itn[Rewrite spoken-form numbers, money, dates and times to written form ("two hundred thirty two" -> "232"). English-only; other languages pass through unchanged.]' \
+      '--include-errors[With --json or --toon, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
       '--verbose[Show language detection details]' \
       '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
       '--lang=[Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch]:lang:' \
@@ -95,6 +96,7 @@ _kesha() {
       _arguments '--help[Show help]' \
         '-h[Show help]' \
         '--out=[Write recorded WAV audio to this path]:out:' \
+        '--live[Transcribe the microphone live and print the transcript to stdout (CoreML on Apple Silicon only)]' \
         '--max-seconds=[Maximum recording duration in seconds]:max seconds:' \
         '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]'
       ;;
@@ -110,7 +112,7 @@ _kesha() {
         '--format=[Output format: wav (default), ogg-opus (Telegram-ready voice note), or flac (lossless, plays in all browsers incl. Safari). Inferred from --out extension when omitted.]:format:' \
         '--bitrate=[Opus bitrate in bits/sec (e.g. 32000). Only with --format ogg-opus.]:bitrate:' \
         '--sample-rate=[Opus encoder sample rate (8000/12000/16000/24000/48000). Only with --format ogg-opus.]:sample rate:' \
-        '--no-expand-abbrev[Disable Russian acronym auto-expansion (ВОЗ → '\''вэ о зэ'\'') for ru-vosk-* voices. <say-as interpret-as='\''characters'\''> still works. Applies to Russian (ru-vosk-*) and English (en-*) voices.]' \
+        '--no-expand-abbrev[Disable acronym auto-expansion on ru-vosk-* voices (ВОЗ → '\''вэ о зэ'\'') and English on ONNX engine builds (FBI → '\''ef bee eye'\''). No effect on macOS arm64 FluidAudio, macos-* or non-English voices, which spell initialisms in their own G2P; the engine warns when the flag is ignored. <say-as interpret-as='\''characters'\''> still works.]' \
         '--verbose[Log TTS synthesis time to stderr]' \
         '--debug[Trace engine subprocess calls on stderr (or KESHA_DEBUG=1)]'
       ;;
@@ -140,7 +142,8 @@ _kesha() {
       '--toon[Output results as TOON (compact, LLM-friendly encoding of the same data as --json)]' \
       '--timestamps[Include timestamped transcript segments in JSON/TOON output]' \
       '--speakers[Include speaker labels in segments. Needs --json/--toon and darwin-arm64; run `kesha install --diarize` first (it installs VAD too). Implies --timestamps, and engages VAD windowing at any duration (so it cannot be combined with --no-vad).]' \
-      '--include-errors[With --json, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
+      '--itn[Rewrite spoken-form numbers, money, dates and times to written form ("two hundred thirty two" -> "232"). English-only; other languages pass through unchanged.]' \
+      '--include-errors[With --json or --toon, output { results, errors } so scripts can read per-file failures without parsing stderr]' \
       '--verbose[Show language detection details]' \
       '--format=[Output format: transcript | json | toon (long-form alias for --json / --toon)]:format:' \
       '--lang=[Expected language code, e.g. en or en-us (see docs/languages.md); warn if mismatch]:lang:' \

package/man/kesha.1

@@ -33,7 +33,7 @@ Print the kesha(1) manpage
 Run a Model Context Protocol server over stdio (transcribe_audio, synthesize_speech, list_voices, list_languages). Configure an MCP client with: { command: 'kesha', args: ['mcp'] }.
 .TP
 .B record
-Record microphone audio to a WAV file
+Record microphone audio to a WAV file, or transcribe it live
 .TP
 .B say
 Synthesize speech from text (TTS). Writes audio to stdout (or \-\-out file). Defaults to WAV; use \-\-format ogg\-opus for messenger\-ready voice notes.
@@ -60,8 +60,11 @@ Include timestamped transcript segments in JSON/TOON output
 .B \-\-speakers
 Include speaker labels in segments. Needs \-\-json/\-\-toon and darwin\-arm64; run `kesha install \-\-diarize` first (it installs VAD too). Implies \-\-timestamps, and engages VAD windowing at any duration (so it cannot be combined with \-\-no\-vad).
 .TP
+.B \-\-itn
+Rewrite spoken\-form numbers, money, dates and times to written form ("two hundred thirty two" \-> "232"). English\-only; other languages pass through unchanged.
+.TP
 .B \-\-include\-errors
-With \-\-json, output { results, errors } so scripts can read per\-file failures without parsing stderr
+With \-\-json or \-\-toon, output { results, errors } so scripts can read per\-file failures without parsing stderr
 .TP
 .B \-\-verbose
 Show language detection details
@@ -153,6 +156,9 @@ Output status as JSON
 .B \-\-out
 Write recorded WAV audio to this path
 .TP
+.B \-\-live
+Transcribe the microphone live and print the transcript to stdout (CoreML on Apple Silicon only)
+.TP
 .B \-\-max\-seconds
 Maximum recording duration in seconds
 .TP
@@ -188,7 +194,7 @@ Opus bitrate in bits/sec (e.g. 32000). Only with \-\-format ogg\-opus.
 Opus encoder sample rate (8000/12000/16000/24000/48000). Only with \-\-format ogg\-opus.
 .TP
 .B \-\-no\-expand\-abbrev
-Disable Russian acronym auto\-expansion (ВОЗ → 'вэ о зэ') for ru\-vosk\-* voices. <say\-as interpret\-as='characters'> still works. Applies to Russian (ru\-vosk\-*) and English (en\-*) voices.
+Disable acronym auto\-expansion on ru\-vosk\-* voices (ВОЗ → 'вэ о зэ') and English on ONNX engine builds (FBI → 'ef bee eye'). No effect on macOS arm64 FluidAudio, macos\-* or non\-English voices, which spell initialisms in their own G2P; the engine warns when the flag is ignored. <say\-as interpret\-as='characters'> still works.
 .TP
 .B \-\-verbose
 Log TTS synthesis time to stderr

package/model-plan.json

@@ -15,9 +15,9 @@
     { "relPath": "models/silero-vad/silero_vad.onnx", "sizeBytes": 2327524 }
   ],
   "g2pCharsiu": [
-    { "relPath": "models/g2p/byt5-tiny/encoder_model.onnx", "sizeBytes": 12478704 },
-    { "relPath": "models/g2p/byt5-tiny/decoder_model.onnx", "sizeBytes": 11983268 },
-    { "relPath": "models/g2p/byt5-tiny/decoder_with_past_model.onnx", "sizeBytes": 5427260 }
+    { "relPath": "models/g2p/byt5-tiny/encoder_model.onnx", "sizeBytes": 57234020 },
+    { "relPath": "models/g2p/byt5-tiny/decoder_model.onnx", "sizeBytes": 26118052 },
+    { "relPath": "models/g2p/byt5-tiny/decoder_with_past_model.onnx", "sizeBytes": 22960684 }
   ],
   "kokoroGraph": { "relPath": "models/kokoro-82m/model.onnx", "sizeBytes": 325532387 },
   "kokoroVoices": {
@@ -36,8 +36,8 @@
   ],
   "diarize": [
     { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Manifest.json", "sizeBytes": 617 },
-    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/model.mlmodel", "sizeBytes": 7080357 },
-    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/weights/0-weight.bin", "sizeBytes": 5930400 },
-    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/weights/1-weight.bin", "sizeBytes": 232161600 }
+    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/model.mlmodel", "sizeBytes": 856521 },
+    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/weights/0-weight.bin", "sizeBytes": 8948544 },
+    { "relPath": "models/diarize/SortformerNvidiaLow_v2.mlpackage/Data/com.apple.CoreML/weights/1-weight.bin", "sizeBytes": 235580992 }
   ]
 }

package/openclaw-plugin.cjs

@@ -1,74 +1,36 @@
 // Kesha Voice Kit — OpenClaw plugin entry.
 //
-// Registers the locally-installed `kesha` CLI as an audio transcription
-// provider so OpenClaw routes voice messages from any connected channel
-// through Kesha (Parakeet TDT via CoreML on Apple Silicon, ONNX elsewhere).
-// 25 languages, no cloud, ~19x faster than Whisper.
+// Declares the locally-installed `kesha` CLI as an audio media-understanding
+// provider so it is discoverable in `openclaw plugins inspect`
+// (Shape: plain-capability) — Parakeet TDT via CoreML on Apple Silicon, ONNX
+// elsewhere, 25 languages, no cloud.
+//
+// This registration is declaration-only and does NOT transcribe. OpenClaw only
+// routes audio to a media-understanding provider once model auth resolves for it
+// (an API key), which a local, keyless CLI cannot satisfy on any sane config, so
+// this provider is never selected to run. Real transcription is wired by the
+// user through the documented `type: "cli"` entry in tools.media.audio.models,
+// which runs `kesha {{MediaPath}}` directly and reads its stdout — see
+// docs/openclaw.md and docs/runbooks/openclaw-plugin.md.
 //
 // The same `kesha` CLI also produces messenger-ready voice notes via
-// `kesha say "..." --format ogg-opus --out reply.ogg` (Telegram /
-// Discord ingest OGG/Opus directly — no transcoding needed). Not wired into
-// OpenClaw's media-understanding capability here; invoke it from a hook or
-// agent tool when you want Kesha to speak.
+// `kesha say "..." --format ogg-opus --out reply.ogg` (Telegram / Discord ingest
+// OGG/Opus directly — no transcoding needed). Not wired into OpenClaw's
+// media-understanding capability here; invoke it from a hook or agent tool when
+// you want Kesha to speak.
 //
 // Prerequisite: the `kesha` binary must be on PATH. Install it with:
 //   bun add -g @drakulavich/kesha-voice-kit
 //   kesha install            # ASR models
 //   kesha install --tts      # TTS models (Kokoro + Vosk-TTS), only if you use `kesha say`
 //
-// The module specifier below is split across `+` on purpose — see the
-// OpenClaw skill-scanner rule "dangerous-exec" in
-// src/security/skill-scanner.ts. It gates on a per-file substring match,
-// and splitting the specifier keeps that substring out of this source so
-// the rule does not fire on this legitimate local-CLI wrapper.
-const { spawnSync } = require("node:child_" + "process");
-const fs = require("node:fs");
-const os = require("node:os");
-const path = require("node:path");
+// Editing note: OpenClaw's `dangerous-exec` scanner is a naive per-file regex
+// that also reads comments. Do not name the forbidden Node runtime module or a
+// bare command-running call anywhere in this file — see
+// docs/runbooks/openclaw-plugin.md.
 
-const DEFAULT_TIMEOUT_MS = 60_000;
 const MODEL_ID = "parakeet-tdt-0.6b-v3";
 
-function tempAudioPath(fileName) {
-  const ext = (fileName && path.extname(fileName)) || ".ogg";
-  return path.join(os.tmpdir(), `kesha-${process.pid}-${Date.now()}${ext}`);
-}
-
-async function transcribeAudio(req) {
-  if (!req || !req.buffer) {
-    return { text: "" };
-  }
-
-  const tmp = tempAudioPath(req.fileName);
-  fs.writeFileSync(tmp, req.buffer);
-
-  try {
-    const result = spawnSync("kesha", ["--json", tmp], {
-      encoding: "utf8",
-      timeout: req.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-    });
-
-    if (result.error || result.status !== 0) {
-      return { text: "" };
-    }
-
-    const parsed = JSON.parse(result.stdout || "[]");
-    const text = Array.isArray(parsed) && parsed[0] && typeof parsed[0].text === "string"
-      ? parsed[0].text
-      : "";
-
-    return { text, model: MODEL_ID };
-  } catch {
-    return { text: "" };
-  } finally {
-    try {
-      fs.unlinkSync(tmp);
-    } catch {
-      // best effort cleanup
-    }
-  }
-}
-
 module.exports = {
   id: "kesha-voice-kit",
   name: "Kesha Voice Kit",
@@ -78,7 +40,6 @@ module.exports = {
       capabilities: ["audio"],
       defaultModels: { audio: MODEL_ID },
       autoPriority: { audio: 50 },
-      transcribeAudio,
     });
   },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.27.0",
+  "version": "1.28.0-alpha.1",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {
@@ -46,7 +46,7 @@
     "test": "bun test --timeout 30000",
     "test:watch": "bun test --timeout 30000 --watch",
     "test:unit": "bun test --timeout 30000 tests/unit/",
-    "test:cli-fast": "bun test --timeout 30000 tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/e2e-cli.test.ts tests/integration/say.test.ts",
+    "test:cli-fast": "bun test --timeout 30000 tests/unit/ tests/integration/cli-contracts.test.ts tests/integration/say.test.ts",
     "test:integration": "bun test --timeout 30000 tests/integration/",
     "coverage:ts": "bun run test:cli-fast --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage/ts",
     "coverage:check:ts": "bun .github/scripts/check-coverage.ts --preset=ts --lcov=coverage/ts/lcov.info --summary=coverage/ts/summary.md",
@@ -54,12 +54,14 @@
     "coverage:check:rust": "bun .github/scripts/check-coverage.ts --preset=rust --lcov=coverage/rust/lcov.info --summary=coverage/rust/summary.md",
     "generate:shell-artifacts": "bun scripts/generate-shell-artifacts.ts",
     "lint": "bunx tsc --noEmit",
-    "check": "bun run lint && bun run check:versions && bun run test:cli-fast",
+    "check": "bun run lint && bun run check:versions && bun run check:recipes && bun run test:cli-fast",
     "check:workflows": "bun .github/scripts/check-workflows.ts",
+    "check:recipes": "bun .github/scripts/check-recipes.ts",
     "check:specs": "bunx @fission-ai/openspec@1.4.1 validate --specs --strict",
     "check:release-manifest": "bun .github/scripts/release-manifest.mjs --check",
     "check:versions": "bun .github/scripts/check-versions.ts",
-    "check:engine-targets": "bun .github/scripts/check-engine-targets.ts"
+    "check:engine-targets": "bun .github/scripts/check-engine-targets.ts",
+    "mutants:ts": "bun scripts/mutants-ts.ts"
   },
   "keywords": [
     "asr",
@@ -87,6 +89,8 @@
     "bun": ">=1.3.0"
   },
   "devDependencies": {
+    "@hughescr/stryker-bun-runner": "^1.3.8",
+    "@stryker-mutator/core": "^9.6.1",
     "@types/bun": "latest",
     "fast-xml-parser": "^5.8.0",
     "typescript": "^7.0.2",

package/src/asset-modules.d.ts

@@ -0,0 +1,20 @@
+// Bun's `with { type: "text" }` imports; tsc has no loader for these extensions.
+declare module "*.bash" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.zsh" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.fish" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.1" {
+  const content: string;
+  export default content;
+}

package/src/cache-layout.ts

@@ -0,0 +1,44 @@
+import { join, resolve, sep } from "path";
+
+export interface CachePathEntry {
+  label: string;
+  path: string;
+}
+
+/**
+ * Whether `child` is `parent` itself or lives under it — the one answer `status --disk` and
+ * `doctor` both need before deciding whether an engine dir is already inside the cache total.
+ * A bare `startsWith` reads the sibling `~/.cache/kesha-alt` as inside `~/.cache/kesha` and
+ * drops its size (#790); `KESHA_CACHE_DIR` and `KESHA_ENGINE_BIN` are taken verbatim, so both
+ * sides are resolved first.
+ */
+export function isInsideDir(child: string, parent: string): boolean {
+  const resolvedChild = resolve(child);
+  const resolvedParent = resolve(parent);
+  return resolvedChild === resolvedParent || resolvedChild.startsWith(`${resolvedParent}${sep}`);
+}
+
+/**
+ * The Kesha-managed directories both `kesha status --disk` and `kesha doctor` report, in one
+ * place so a new model dir cannot be added to only one of them. The two ASR rows are mutually
+ * exclusive: a CoreML engine never populates the ONNX dir, and instead roots FluidAudio's own
+ * subsystems under `<cache>/fluidaudio`, which is where the relocated bundles land (#688).
+ * Whatever stayed in FluidAudio's own trees is outside this cache and is reported separately
+ * by `fluidExternalRoots`.
+ */
+export function cacheComponentPaths(
+  cacheRoot: string,
+  engineDir: string,
+  coreml: boolean,
+): CachePathEntry[] {
+  return [
+    { label: "Engine", path: engineDir },
+    ...(coreml
+      ? [{ label: "FluidAudio (in cache)", path: join(cacheRoot, "fluidaudio") }]
+      : [{ label: "ASR (Parakeet)", path: join(cacheRoot, "models/parakeet-tdt-v3") }]),
+    { label: "Language ID", path: join(cacheRoot, "models/lang-id-ecapa") },
+    { label: "VAD (Silero)", path: join(cacheRoot, "models/silero-vad") },
+    { label: "TTS (Kokoro)", path: join(cacheRoot, "models/kokoro-82m") },
+    { label: "TTS (Vosk)", path: join(cacheRoot, "models/vosk-ru") },
+  ];
+}

package/src/cli/completions.ts

@@ -1,13 +1,17 @@
 import { defineCommand } from "citty";
 import { log } from "../log";
+// Inlined because import.meta.url escapes the embedded filesystem in the compiled .deb/.rpm binary (#914).
+import bashCompletions from "../../completions/kesha.bash" with { type: "text" };
+import zshCompletions from "../../completions/kesha.zsh" with { type: "text" };
+import fishCompletions from "../../completions/kesha.fish" with { type: "text" };
 
-const SHELL_FILES = {
-  bash: "kesha.bash",
-  zsh: "kesha.zsh",
-  fish: "kesha.fish",
+const SHELL_SCRIPTS = {
+  bash: bashCompletions,
+  zsh: zshCompletions,
+  fish: fishCompletions,
 } as const;
 
-type Shell = keyof typeof SHELL_FILES;
+type Shell = keyof typeof SHELL_SCRIPTS;
 
 interface CompletionsCommandArgs {
   shell?: string;
@@ -35,7 +39,6 @@ export const completionsCommand = defineCommand({
       log.error("usage: kesha completions <bash|zsh|fish>");
       process.exit(2);
     }
-    const file = new URL(`../../completions/${SHELL_FILES[shell]}`, import.meta.url);
-    process.stdout.write(await Bun.file(file).text());
+    process.stdout.write(SHELL_SCRIPTS[shell]);
   },
 });