kesha-voice-kit

Kesha Voice Kit

Dale voz a tus herramientas locales y agentes LLM.
Reconocimiento de voz rápido, síntesis de voz, detección de actividad de voz y detección de idioma en una sola CLI local-first: CoreML en Apple Silicon, ONNX en Linux y Windows.

• Transcribe localmente — 25 idiomas, hasta ~19x más rápido que Whisper en Apple Silicon, ~2.5x en CPU
• Responde hablando — síntesis de voz en 9 idiomas
• Conéctalo a agentes — implementa flujos de voz como comandos CLI, un servidor MCP, una habilidad de OpenClaw o un agente Hermes
• Motor Rust pequeño — un solo binario de ~65MB, sin ffmpeg, sin Python, sin complementos nativos de Node

Inicio 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 descarga ~2.5 GB en Linux/Windows y ~0.6 GB en Apple Silicon, cuyo motor CoreML lee un conjunto de modelos más pequeño. Siempre es explícito — nada se descarga a tus espaldas — e informa el progreso de la descarga en stderr. Si bun --version falla justo después del paso 1, recarga tu PATH: exec $SHELL -l.

¿Prefieres Homebrew o Docker? Consulta Otros métodos de instalación. ¿Aislado de la red o detrás de un mirror corporativo? Consulta docs/model-mirror.md.

Soporte de plataformas

Los tres objetivos transcriben, detectan el idioma hablado, ejecutan VAD y hablan. Las filas exclusivas de macOS necesitan frameworks de Apple — no son un puerto faltante. Windows es una ruta probada, no un binario publicado que nadie ejecutó: CI hace un kesha install en frío en windows-latest, transcribe un fixture y hace un round-trip de síntesis (#216, #667).

	macOS arm64	Linux x64	Windows x64
Transcribir · ID de idioma de audio · VAD	CoreML / ANE	ONNX CPU	ONNX CPU
TTS — en ru es fr it pt	✅	✅	✅
TTS — hi ja zh y voces del sistema macOS	✅	—	—
Captura de micrófono y dictado en vivo (kesha record)	✅	—	—
Diarización de hablantes (--speakers)	✅	—	—
Marcas de tiempo a nivel de palabra (words en --json)	✅	✅	✅
Enrutamiento automático de voz según el idioma del texto	✅	pasa --lang	pasa --lang

Los Mac con Intel no reciben un binario de motor publicado. Matriz completa con etiquetas de madurez: docs/product-positioning.md.

Reconocimiento de voz

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

Los archivos múltiples reciben encabezados estilo head; stdout es la transcripción, stderr son errores — apto para tuberías:

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

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

• Graba desde el micrófono (macOS): kesha record --out hello.wav escribe audio del micrófono a un archivo WAV (kesha hello.wav lo transcribe). macOS solicita acceso al micrófono en el primer uso — concédelo en Configuración del Sistema → Privacidad y Seguridad → Micrófono si fue denegado. En Linux/Windows o máquinas sin cabeza, pasa cualquier archivo de audio existente directamente a kesha.
• Dicta directamente a texto (darwin-arm64): kesha record --live transcribe el micrófono mientras captura e imprime la transcripción en stdout — sin WAV intermedio, por lo que se puede canalizar (kesha record --live | pbcopy). Para terminar tras silencio final, instala VAD explícitamente y luego actívalo: kesha install --vad && kesha record --live --auto-stop. Los valores predeterminados son 1,000 ms de silencio después de 250 ms de habla; ajústalos con --auto-stop-silence-ms, --auto-stop-min-speech-ms y --auto-stop-threshold. El progreso va a stderr. Linux y Windows no capturan el micrófono; pasa un archivo de audio existente a kesha para transcribirlo. Una interrupción es recuperable: Ctrl-C (o SIGTERM) detiene la sesión, aún imprime lo que dictaste y sale con 130/143, y el audio se vuelca a un WAV de recuperación en ~/.cache/kesha/recordings/ — nombrado en stderr cuando comienza la sesión, eliminado una vez que la transcripción se ha entregado realmente, conservado si algo — una señal, un bloqueo, una terminal cerrada, una tubería rota — se interpuso primero (#962).
• Audio largo / con mucho silencio: instala VAD (kesha install --vad); Kesha lo usa automáticamente después de 120 s. Sin VAD, el audio largo recurre a fragmentos ASR fijos. Consulta docs/vad.md.
• Diarización de hablantes (darwin-arm64): kesha install --diarize (que también instala VAD), luego kesha --json --speakers meeting.m4a sella cada segmento con un ID de speaker. --speakers activa el ventaneo VAD por sí mismo en cualquier duración, por lo que no se puede combinar con --no-vad. Linux/Windows devuelven un error claro de "solo darwin-arm64" (#199).
• Marcas de tiempo a nivel de palabra (todas las plataformas): kesha --json --timestamps audio.ogg agrega un array de words a cada segmento — { "word": "email", "start": 0.72, "end": 1.12 } — en el mismo reloj relativo al archivo que el segmento, por lo que una palabra siempre está dentro del segmento que la contiene. Se leen de la propia cuadrícula de fotogramas del decodificador, por lo que: los tiempos están cuantificados a 0.08 s, los tramos consecutivos pueden superponerse (cada end es una predicción de duración por palabra, no el start de la siguiente palabra), end >= start en lugar de estrictamente mayor, y la puntuación permanece unida a su palabra. La clave simplemente está ausente donde un segmento no tiene ninguna — cualquier segmento que --itn reescribió, por ejemplo — así que verifica la capacidad de transcribe.words en lugar de esperar un array vacío (#720).
• Detección de idioma del texto: los resultados JSON y TOON incluyen textLanguage con un código de idioma, confianza y su source. En macOS Kesha usa Apple NLLanguageRecognizer; en otros lugares usa el respaldo incluido de tinyld, cuya escala de confianza es diferente. Esto es separado de audioLanguage, que identifica el audio hablado cuando está disponible.
• Números en forma escrita: --itn reescribe lo que el modelo deletrea — "two hundred thirty two" → "232", "five dollars and fifty cents" → "$5.50". Opt-in, en todas las plataformas, marcas de tiempo intactas. Solo en inglés en la práctica; el ruso y el resto pasan sin cambios. Los nombres de puntuación hablada siguen siendo palabras ("dot", "comma", "the period of growth") porque Kesha transcribe habla en lugar de dictado — así que "example dot com" también conserva sus palabras (#822). Una oración "and" sobrevive al número que la sigue ("cats and three dogs" → "cats and 3 dogs"), mientras que un "and" que el número posee aún se une a él ("three hundred and five" → "305") (#1000) — y ya no divide el número a su alrededor ("two hundred and thirty two" → "232", no "230 2") (#1006). Un número con guion se lee igual que la forma espaciada ("twenty-five apples" → "25 apples"), mientras que un guion entre palabras ordinarias se deja solo ("well-known", "state-of-the-art", "twenty-something") (#1004).

Síntesis de voz

Kesha responde hablando en 9 idiomas. Kokoro se ejecuta de forma nativa a través de FluidAudio CoreML/ANE en Apple Silicon y a través de ONNX en Linux y Windows; el ruso usa Vosk-TTS, mientras que las voces del sistema macos-* no necesitan descarga de modelos. En macOS Kesha elige la voz según el idioma del propio texto; en Linux y Windows, indica el idioma con --lang <code> (o la voz con --voice <id>) — de lo contrario, el valor predeterminado del motor habla.

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 salida (--format, o inferidos de la extensión --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 lo que está instalado. Voces, el catálogo completo, voces del sistema macOS, SSML, velocidad de habla (--rate, <prosody>), acentuación de palabras en ruso y manejo de abreviaturas en ruso/inglés están todos en docs/tts.md.

Idiomas

Reconocimiento de voz abarca 25 idiomas y síntesis de voz 9 — tablas completas con códigos, banderas y disponibilidad por plataforma en docs/languages.md. La detección de idioma de audio identifica 107 idiomas.

Rendimiento

Hasta ~19x más rápido que Whisper en Apple Silicon (M2), ~2.5x más rápido en CPU

Comparado con Whisper large-v3-turbo, todos los motores detectando idioma automáticamente:

Desglose completo por archivo (ruso + inglés): BENCHMARK.md. La cifra de CPU es el motor ONNX en los núcleos de CPU de un M2; aún no se publican números x86.

Otros métodos de instalación

Todos estos instalan el envoltorio CLI de Bun; el motor + modelos aún se descargan explícitamente vía kesha install. (Nix es la excepción — actualmente solo compila el motor desde el código fuente; ver abajo.)

• Homebrew — brew install drakulavich/tap/kesha-voice-kit · docs/homebrew.md
• Paquetes Linux (.deb/.rpm, x64) — publicados en los lanzamientos de CLI, ver docs/linux-packages.md
• Docker (imagen GHCR) — docs/docker.md
• Nix (aarch64-darwin / x86_64-linux) — compila el motor desde el código fuente (nix build github:drakulavich/kesha-voice-kit#kesha-engine). La CLI completa de kesha vía nix run / nix profile install aún no está disponible — necesita un mantenedor con Nix para poblar un hash de compilación (#946). · docs/nix-install.md
• Completado de shell + manpage — kesha completions bash|zsh|fish y kesha manpage imprimen los archivos empaquetados para instalarlos donde tu shell los espere.

Integraciones

• Servidor MCP — kesha mcp expone herramientas de transcribir/sintetizar/listar a cualquier cliente MCP (Claude, Cursor, Codex, Gemini). Configuración: docs/mcp.md.
• OpenClaw — dale oídos a tu agente LLM. Instalación y configuración: docs/openclaw.md.
• Hermes Agent — STT/TTS local a través de proveedores de comandos de Hermes. Configuración: docs/hermes.md.
• Raycast (macOS) — dictado de micrófono sin conexión desde el lanzador: Dictate to Clipboard graba con un medidor de señal en vivo, se detiene automáticamente en silencio, transcribe localmente y copia el texto. Instalar desde Raycast Store · fuente: raycast/.
• API programática — @drakulavich/kesha-voice-kit/core para usar dentro de un programa Bun. Ver docs/api.md.

Más

• Arquitectura — flujo de datos en tiempo de ejecución, los modelos incluidos, el límite CLI ↔ motor Rust, fijación de modelos y dónde viven las pruebas.
• Casos de uso — recetas de copiar y pegar (transcribir una reunión, hablar desde OpenClaw, ejecutar sin conexión, mover la caché).
• Posicionamiento del producto — flujos de trabajo compatibles, no objetivos, etiquetas de madurez, matriz de plataformas.
• Registro de cambios — cada lanzamiento, con los cambios de comportamiento detallados.
• Diagnósticos: kesha doctor, kesha support-bundle (.tar.gz redactado para problemas) y kesha logs producen diagnósticos locales, sin contenido — ver docs/diagnostic-logs.md. Cada fallo imprime una línea estable de error [CODE]: … y un código de salida de proceso documentado.
• Scripting y CI: --json (o --toon) para salida legible por máquina, --include-errors (con cualquiera) para obtener fallos por archivo en stdout junto con los resultados, --quiet/-q para silenciar el progreso y --no-color (o NO_COLOR=1) para registros simples. Los colores se desactivan automáticamente cuando CI=true.
• Privacidad / Estadísticas locales: Las estadísticas están desactivadas por defecto y son completamente locales. Actívalas con kesha stats enable para registrar métricas operativas sin contenido en una base de datos SQLite local — nunca conectada a la red, nunca almacena audio, transcripciones, texto o rutas. Comandos completos y ciclo de vida: docs/local-stats.md.

Contribuir

Consulta CONTRIBUTING.md, la Hoja de ruta (Ahora / Siguiente / Después) y el Registro de decisiones (por qué se tomaron — y revirtieron — las decisiones de plataforma/modelo). Configuración de desarrollo: just dev-setup (Bun, Rust, nextest, librerías de plataforma).

Licencia

Hecho con 💛🩵 y energía 🥤 bajo MIT License