kesha-voice-kit

Kesha Voice Kit

Kesha listens and talks back.
Your agent gets a voice message, Kesha turns it into text on your machine, and speaks the reply once you add kesha install --tts (voice replies). Fastest on Apple Silicon with CoreML, and it runs on Linux and Windows through ONNX.

• Transcribe locally — 25 languages, up to ~19x faster than Whisper on Apple Silicon, ~10x on an x86 CPU
• Speak back — text-to-speech in 9 languages
• Plug into agents — ship voice workflows as CLI commands, an MCP server, an OpenClaw skill, or a Hermes agent
• Small Rust engine — single ~74 MB binary, no ffmpeg, no Python, no native Node addons

Quick start

Runtime: Bun >= 1.4.0.

# 1. Install Bun (skip if you have it)
curl -fsSL https://bun.sh/install | bash        # macOS/Linux — or: brew install bun
powershell -c "irm bun.sh/install.ps1 | iex"    # Windows

# 2. Install Kesha
bun add -g @drakulavich/kesha-voice-kit
kesha --version                                 # confirms `kesha` resolved on PATH

# 3. Download the engine and models — pick one path
kesha init                                      # guided: TTS languages and optional VAD / diarization
kesha install --plan && kesha install           # manual: preview the sizes, then download

# 4. Transcribe
kesha audio.ogg                                 # transcript to stdout

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 reports download progress on stderr. If bun --version fails right after step 1, reload your PATH: exec $SHELL -l. To remove the engine, models and everything else Kesha wrote, run kesha uninstall.

Prefer Homebrew or Docker? See Other install methods. Air-gapped or behind a corporate mirror? See 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, #667).

	macOS arm64	Linux x64	Windows x64
Transcribe · audio language ID · VAD	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.

Plug into your agent

• MCP server — kesha mcp exposes transcribe/synthesize/list tools to any MCP client (Claude, Cursor, Codex, Gemini). Setup: docs/mcp.md.
• OpenClaw — give your LLM agent ears. Install & config: docs/openclaw.md.
• Hermes Agent — local STT/TTS through Hermes command providers. Setup: docs/hermes.md.
• Raycast (macOS) — offline microphone dictation from the launcher: Dictate to Clipboard records with a live signal meter, auto-stops on silence, transcribes locally, and copies the text. Install from the Raycast Store · source: raycast/.
• Programmatic API — @drakulavich/kesha-voice-kit/core for use inside a Bun program. See docs/api.md.

Speech-to-text

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

Multiple files get head-style headers; stdout is the transcript, stderr is errors — pipe-friendly:

$ kesha freedom.ogg tahiti.ogg
=== freedom.ogg ===
Свободу попугаям! Свободу!

=== tahiti.ogg ===
Таити, Таити! Не были мы ни в какой Таити! Нас и тут неплохо кормят.

• Record from the mic (macOS): kesha record --out hello.wav, then kesha hello.wav. Linux and Windows do not capture the microphone; pass an existing audio file instead. See docs/stt.md.
• Live dictation (darwin-arm64): kesha record --live | pbcopy prints the transcript as you speak; --auto-stop ends it after silence once VAD is installed. Ctrl-C still prints what you dictated. See docs/stt.md.
• 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.
• Speaker diarization (darwin-arm64): kesha install --diarize, then kesha --json --speakers meeting.m4a stamps each segment with a speaker id. See docs/stt.md.
• Word-level timestamps (every platform): kesha --json --timestamps audio.ogg adds a words array to each segment. See docs/stt.md.
• Text-language detection: JSON and TOON results include textLanguage, separate from the spoken audioLanguage. See docs/stt.md.
• Written-form numbers: --itn turns spelled-out English numbers into digits ("two hundred thirty two" → "232"). See docs/stt.md.
• A file name starting with -: write it as ./-file.wav. See docs/stt.md.

Text-to-speech

Kesha speaks back in 9 languages. Kokoro runs natively through FluidAudio CoreML/ANE on Apple Silicon and through ONNX on Linux and Windows; Russian uses Vosk-TTS, while macos-* system voices need no model download. On macOS Kesha picks the voice from the text's own language; on Linux and Windows, state the language with --lang <code> (or the voice with --voice <id>) — otherwise the engine default speaks.

kesha install --tts                              # English voices; sizes differ per platform — preview: kesha install --plan
kesha install --tts en ru                        # + Russian (+~937 MB, Vosk)
kesha say "Hello, world" > hello.wav
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

Output formats (--format, or inferred from the --out extension):

kesha say "Hello" --out hi.wav                    # WAV (default, uncompressed)
kesha say "Hello" --format ogg-opus --out hi.ogg  # OGG/Opus — messenger voice notes
kesha say "Hello" --format flac --out hi.flac     # FLAC — lossless, plays in every browser incl. Safari/iOS

kesha say --list-voices lists the voices kesha knows; some need kesha install --tts <lang> before they speak. Voices, the full catalogue, macOS system voices, SSML, speaking rate (--rate, <prosody>), Russian word stress, and Russian/English abbreviation handling are all in docs/tts.md.

Languages

Speech-to-text spans 25 languages and text-to-speech 9 — full tables with codes, flags, and per-platform availability in docs/languages.md. Audio language detection identifies 107 languages.

Performance

Up to ~19x faster than Whisper on Apple Silicon (M2), ~10x faster on an x86 Linux CPU (~2.5x faster than faster-whisper)

Compared against Whisper large-v3-turbo, all engines auto-detecting language:

Full per-file breakdown (Russian + English): BENCHMARK.md. The chart is from an M2. The x86 figure comes from a GitHub-hosted ubuntu-latest runner (AMD EPYC, ONNX on CPU), where openai-whisper runs in FP32.

Other install methods

Except Nix, these install the Bun CLI wrapper; engine + models still download explicitly via kesha install.

• Homebrew — brew install drakulavich/tap/kesha-voice-kit · docs/distribution.md
• Linux packages (.deb/.rpm, x64) — published on stable releases, see docs/distribution.md
• Docker (GHCR image) — docs/docker.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). · docs/distribution.md
• Shell completions + manpage — kesha completions bash|zsh|fish and kesha manpage print the packaged files to install wherever your shell expects them.

More

• Architecture — runtime data flow, the models that ship, the CLI ↔ Rust engine boundary, model pinning, and where tests live.
• Use cases — copy-paste recipes (transcribe a meeting, speak from OpenClaw, run offline, move the cache).
• Product positioning — supported workflows, non-goals, maturity labels, platform matrix.
• Changelog — every release, with the behaviour changes spelled out.
• Diagnostics: kesha status (--disk for cache usage, --json for scripts, --check exits 1 unless the engine and ASR model are installed), kesha doctor, kesha support-bundle (redacted .tar.gz for issues), and kesha logs produce local, content-free diagnostics — see docs/diagnostic-logs.md. Every failure prints a stable error [CODE]: … line and a documented process exit code.
• Moving the files: one variable, KESHA_HOME, moves everything Kesha writes (models, logs, stats) into a directory of your choice — see where Kesha keeps its files.
• Scripting & CI: --json (or --toon) for machine-readable output (each file's warnings repeats what stderr warned about it), --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.

Contributing

See CONTRIBUTING.md and the Decision log (why platform/model choices were made — and reversed). Dev setup: just dev-setup (Bun, Rust, nextest, platform libs).

License

Made with 💛🩵 and 🥤 energy under MIT License