kesha-voice-kit

Kesha Voice Kit

Dê voz às suas ferramentas locais e agentes de LLM.
Conversão rápida de fala em texto, texto em fala, detecção de atividade de voz e detecção de idioma em um único CLI local-first — CoreML no Apple Silicon, ONNX no Linux e Windows.

• Transcreva localmente — 25 idiomas, até ~19x mais rápido que Whisper no Apple Silicon, ~2.5x na CPU
• Responda em voz — texto em fala em 9 idiomas
• Integre a agentes — envie fluxos de voz como comandos CLI, um servidor MCP, uma skill do OpenClaw ou um agente Hermes
• Motor Rust compacto — um único binário de ~65MB, sem ffmpeg, sem Python, sem addons nativos de Node

Início Rápido

Runtime: Bun >= 1.3.0.

# 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
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 baixa ~2.5 GB no Linux/Windows e ~0.6 GB no Apple Silicon, cujo motor CoreML lê um conjunto menor de modelos. É sempre explícito — nada é baixado sem seu conhecimento — e relata o progresso do download no stderr. Se bun --version falhar logo após o passo 1, recarregue seu PATH: exec $SHELL -l.

Prefere Homebrew ou Docker? Veja Outros métodos de instalação. Em ambiente isolado ou atrás de um mirror corporativo? Veja docs/model-mirror.md.

Suporte de plataforma

Todos os três alvos transcrevem, detectam o idioma falado, executam VAD e falam. As linhas exclusivas do macOS precisam de frameworks da Apple — não são uma porta ausente. O Windows é um caminho testado, não um binário publicado que ninguém executou: o CI faz um kesha install limpo no windows-latest, transcreve um fixture e faz um round-trip de síntese (#216, #667).

	macOS arm64	Linux x64	Windows x64
Transcrever · ID de idioma de áudio · VAD	CoreML / ANE	ONNX CPU	ONNX CPU
TTS — en ru es fr it pt	✅	✅	✅
TTS — hi ja zh e vozes do sistema macOS	✅	—	—
Captura de microfone e ditado ao vivo (kesha record)	✅	—	—
Diarização de falantes (--speakers)	✅	—	—
Timestamps em nível de palavra (words em --json)	✅	✅	✅
Roteamento automático de voz pelo idioma do texto	✅	passe --lang	passe --lang

Macs Intel não recebem binário de motor publicado. Matriz completa com rótulos de maturidade: docs/product-positioning.md.

Fala em texto

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
kesha status --json                        # machine-readable, for scripts

Vários arquivos recebem cabeçalhos estilo head; stdout é a transcrição, stderr são erros — amigável para pipes:

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

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

• Grave do microfone (macOS): kesha record --out hello.wav grava áudio do microfone em um arquivo WAV (kesha hello.wav o transcreve). O macOS solicita acesso ao microfone no primeiro uso — conceda em Ajustes do Sistema → Privacidade e Segurança → Microfone se foi negado. No Linux/Windows ou em máquinas headless, passe qualquer arquivo de áudio existente diretamente para kesha.
• Dite direto para texto (darwin-arm64): kesha record --live transcreve o microfone enquanto captura e imprime a transcrição no stdout — sem WAV no meio, então faz pipe (kesha record --live | pbcopy). Para encerrar após silêncio final, instale explicitamente o VAD e opte por: kesha install --vad && kesha record --live --auto-stop. Os padrões são 1.000 ms de silêncio após 250 ms de fala; ajuste com --auto-stop-silence-ms, --auto-stop-min-speech-ms e --auto-stop-threshold. O progresso vai para o stderr. Linux e Windows não capturam o microfone; passe um arquivo de áudio existente para kesha transcrevê-lo. Uma interrupção é recuperável: Ctrl-C (ou SIGTERM) interrompe a sessão, ainda imprime o que você ditou e sai com 130/143, e o áudio é despejado em um WAV de recuperação em ~/.cache/kesha/recordings/ — nomeado no stderr quando a sessão começa, excluído quando a transcrição foi realmente entregue, mantido se algo — um sinal, uma falha, um terminal fechado, um pipe morto — atrapalhou primeiro (#962).
• Áudio longo / com muito silêncio: instale o VAD (kesha install --vad); Kesha o usa automaticamente após 120 s. Sem VAD, áudio longo cai em chunks fixos de ASR. Veja docs/vad.md.
• Diarização de falantes (darwin-arm64): kesha install --diarize (que também instala o VAD), depois kesha --json --speakers meeting.m4a carimba cada segmento com um ID speaker. --speakers engaja o janelamento VAD por conta própria em qualquer duração, então não pode ser combinado com --no-vad. Linux/Windows retornam um erro claro "apenas darwin-arm64" (#199).
• Timestamps em nível de palavra (todas as plataformas): kesha --json --timestamps audio.ogg adiciona um array words a cada segmento — { "word": "email", "start": 0.72, "end": 1.12 } — no mesmo relógio relativo ao arquivo do segmento, então uma palavra sempre está dentro do segmento que a carrega. Leia-os da própria grade de frames do decodificador, então: os tempos são quantizados a 0,08 s, spans consecutivos podem se sobrepor (cada end é uma previsão de duração por palavra, não o start da próxima palavra), end >= start em vez de estritamente maior, e pontuação permanece anexada à sua palavra. A chave está simplesmente ausente onde um segmento não tem nenhuma — qualquer segmento que --itn reescreveu, por exemplo — então verifique a capacidade transcribe.words em vez de esperar um array vazio (#720).
• Detecção de idioma do texto: resultados JSON e TOON incluem textLanguage com um código de idioma, confiança e seu source. No macOS, Kesha usa o NLLanguageRecognizer da Apple; em outros lugares, usa o fallback tinyld incluído, cuja escala de confiança é diferente. Isso é separado de audioLanguage, que identifica o áudio falado quando disponível.
• Números em forma escrita: --itn reescreve o que o modelo soletra — "two hundred thirty two" → "232", "five dollars and fifty cents" → "$5.50". Opt-in, todas as plataformas, timestamps intactos. Apenas inglês na prática; russo e o resto passam inalterados. Nomes de pontuação falados permanecem palavras ("dot", "comma", "the period of growth") porque Kesha transcreve fala em vez de ditado — então "example dot com" também mantém suas palavras (#822). Uma frase "and" sobrevive ao número que a segue ("cats and three dogs" → "cats and 3 dogs"), enquanto um "and" que o número possui ainda se junta a ele ("three hundred and five" → "305") (#1000) — e não divide mais o número ao redor dele ("two hundred and thirty two" → "232", não "230 2") (#1006). Um número hifenizado lê igual à forma espaçada ("twenty-five apples" → "25 apples"), enquanto um hífen entre palavras comuns é deixado em paz ("well-known", "state-of-the-art", "twenty-something") (#1004).

Texto em fala

Kesha responde em voz em 9 idiomas. Kokoro roda nativamente via FluidAudio CoreML/ANE no Apple Silicon e via ONNX no Linux e Windows; russo usa Vosk-TTS, enquanto vozes do sistema macos-* não precisam de download de modelo. No macOS, Kesha escolhe a voz do próprio idioma do texto; no Linux e Windows, declare o idioma com --lang <code> (ou a voz com --voice <id>) — caso contrário, o padrão do motor fala.

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 (macOS)
kesha say --lang ru "Привет, мир" > privet.wav   # explicit — the Linux/Windows path
kesha say --voice ru-vosk-m02 "Голос в текст." > ru.wav

Formatos de saída (--format, ou inferidos da extensão --out):

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 lista o que está instalado. Vozes, o catálogo completo, vozes do sistema macOS, SSML, taxa de fala (--rate, <prosody>), acento tônico em russo e tratamento de abreviações em russo/inglês estão todos em docs/tts.md.

Idiomas

Fala em texto abrange 25 idiomas e texto em fala 9 — tabelas completas com códigos, bandeiras e disponibilidade por plataforma em docs/languages.md. A detecção de idioma de áudio identifica 107 idiomas.

Desempenho

Até ~19x mais rápido que Whisper no Apple Silicon (M2), ~2.5x mais rápido na CPU

Comparado ao Whisper large-v3-turbo, todos os motores com detecção automática de idioma:

Detalhamento completo por arquivo (russo + inglês): BENCHMARK.md. O número de CPU é o motor ONNX nos núcleos de CPU de um M2; nenhum número x86 foi publicado ainda.

Outros métodos de instalação

Todos instalam o wrapper CLI do Bun; motor + modelos ainda baixam explicitamente via kesha install. (Nix é a exceção — atualmente compila apenas o motor a partir do código-fonte; veja abaixo.)

• Homebrew — brew install drakulavich/tap/kesha-voice-kit · docs/homebrew.md
• Pacotes Linux (.deb/.rpm, x64) — publicados nos lançamentos do CLI, veja docs/linux-packages.md
• Docker (imagem GHCR) — docs/docker.md
• Nix (aarch64-darwin / x86_64-linux) — compila o motor a partir do código-fonte (nix build github:drakulavich/kesha-voice-kit#kesha-engine). O CLI completo kesha via nix run / nix profile install ainda não está disponível — precisa de um mantenedor com Nix para popular um hash de build (#946). · docs/nix-install.md
• Completions de shell + manpage — kesha completions bash|zsh|fish e kesha manpage imprimem os arquivos empacotados para instalar onde seu shell espera.

Integrações

• Servidor MCP — kesha mcp expõe ferramentas de transcrever/sintetizar/listar para qualquer cliente MCP (Claude, Cursor, Codex, Gemini). Configuração: docs/mcp.md.
• OpenClaw — dê ouvidos ao seu agente LLM. Instalação e configuração: docs/openclaw.md.
• Hermes Agent — STT/TTS local através de provedores de comando Hermes. Configuração: docs/hermes.md.
• Raycast (macOS) — ditado offline por microfone a partir do launcher: Dictate to Clipboard grava com um medidor de sinal ao vivo, para automaticamente no silêncio, transcreve localmente e copia o texto. Instale da Raycast Store · fonte: raycast/.
• API programática — @drakulavich/kesha-voice-kit/core para uso dentro de um programa Bun. Veja docs/api.md.

Mais

• Arquitetura — fluxo de dados em runtime, os modelos incluídos, a fronteira CLI ↔ motor Rust, fixação de modelos e onde os testes vivem.
• Casos de uso — receitas de copiar e colar (transcreva uma reunião, fale do OpenClaw, rode offline, mova o cache).
• Posicionamento do produto — fluxos suportados, não-objetivos, rótulos de maturidade, matriz de plataformas.
• Changelog — cada lançamento, com as mudanças de comportamento detalhadas.
• Diagnósticos: kesha doctor, kesha support-bundle (.tar.gz redigido para issues) e kesha logs produzem diagnósticos locais, sem conteúdo — veja docs/diagnostic-logs.md. Cada falha imprime uma linha error [CODE]: … estável e um código de saída de processo documentado.
• Scripting & CI: --json (ou --toon) para saída legível por máquina, --include-errors (com qualquer um) para obter falhas por arquivo no stdout junto com os resultados, --quiet/-q para silenciar o progresso e --no-color (ou NO_COLOR=1) para logs simples. As cores desligam automaticamente quando CI=true.
• Privacidade / Estatísticas locais: As estatísticas estão desativadas por padrão e são totalmente locais. Opte com kesha stats enable para registrar métricas operacionais sem conteúdo em um banco de dados SQLite local — nunca conectado à rede, nunca armazenando áudio, transcrições, texto ou caminhos. Comandos completos e ciclo de vida: docs/local-stats.md.

Contribuindo

Veja CONTRIBUTING.md, o Roteiro (Agora / Próximo / Depois) e o Registro de decisões (por que as escolhas de plataforma/modelo foram feitas — e revertidas). Configuração de desenvolvimento: just dev-setup (Bun, Rust, nextest, platform libs).

Licença

Feito com 💛🩵 e 🥤 energia sob a licença MIT