OmniVoice
Descripción general
Genera audio localmente a través del servidor MCP OmniVoice Studio. Herramientas: generate_speech, list_voices, list_personalities, list_languages, check_health. Recursos: voice://{id}, history://recent.
Requisitos previos: el backend debe estar ejecutándose
Todas las herramientas MCP utilizan $OMNIVOICE_API_URL (por defecto http://localhost:3900). Si el backend no está activo, cada herramienta devolverá un error de conexión. Instalación e inicio:
git clone https://github.com/debpalash/OmniVoice-Studio.git "$OMNIVOICE_HOME"
cd "$OMNIVOICE_HOME"
uv sync
VIRTUAL_ENV="$(pwd)/.venv" uv pip install 'mcp[cli]'
Luego:
scripts/check-health.sh # exit 0 si está activo
scripts/start-backend.sh # inicia en segundo plano (detección automática MPS/CUDA)
La primera llamada de síntesis descargará el modelo k2-fsa/OmniVoice (~2.4 GB) de HuggingFace; quedará en caché para inicios posteriores.
Índice de tareas: selecciona la herramienta adecuada
| Tarea | Herramienta | Notas |
|---|---|---|
| Verificar que el backend esté activo | check_health | Devuelve `{"status":"ok","device":"mps |
| Texto → audio con una voz guardada | generate_speech(text, profile_id) | Devuelve WAV en base64. profile_id="demo0001" es la voz de demostración incluida |
| Texto → audio sin clonación (diseño de voz) | generate_speech(text, instruct="…") | Omitir profile_id; pasar un instruct como "voz femenina de mediana edad, cálida, ritmo pausado" |
| Narración multilingüe | generate_speech(text, language="es") | Cualquier código ISO 639 o "Auto" |
| Listar voces existentes | list_voices | Devuelve id, nombre, tipo, personalidad |
| Listar presets de personalidad | list_personalities | Devuelve narrador / casual / presentador-noticias / etc. con sus cadenas instruct |
| Listar idiomas compatibles | list_languages | 646 en total; devuelve 20 populares + el total |
Para decisiones complejas (qué motor usar, cuándo elegir OmniVoice sobre kokoro / Edge TTS / ElevenLabs), consulta references/engines-comparison.md.
Para detalles de configuración MCP, ciclo de vida del backend, solución de problemas y limpieza, consulta references/mcp-setup.md.
Flujos de trabajo comunes
1. Narración one-shot con la voz de demostración
# Tal como se llama a través del cliente MCP (tu agente lo hará por ti):
resultado = generate_speech(
text="Hola — esto es OmniVoice generando voz localmente.",
profile_id="demo0001",
language="Spanish",
steps=16, # 8 = rápido/borrador · 16 = equilibrado · 32 = calidad
)
# resultado es JSON con audio_id, generation_time_s, audio_duration_s, format, wav_base64
Benchmark: 4,2 s de audio en ~24 s del lado del servidor en Apple Silicon MPS con 16 pasos de difusión.
2. Guardar el WAV en disco y reproducirlo
La herramienta devuelve WAV PCM en base64 (16 bits, mono, 24 kHz). Decodificar y escribir:
import base64, json
payload = json.loads(texto_resultado) # parsear JSON devuelto por la herramienta
open("salida.wav","wb").write(base64.b64decode(payload["wav_base64"]))
En macOS: afplay salida.wav. Convertir a MP3 con ffmpeg -i salida.wav -codec:a libmp3lame -b:a 128k salida.mp3.
3. Clonación de voz: receta completa
La clonación necesita un clip de referencia de 3 a 10 segundos que el modelo usará como incrustación (embedding) del hablante. El servidor MCP NO expone la creación de perfiles — solo lee los existentes. Dos formas de crear uno:
Ruta A — script auxiliar incluido (macOS, recomendado para clones nuevos):
scripts/record-reference.sh ~/Downloads/mi-ref.wav 12 1
# args: ruta_salida duración_segundos_raw índice_micrófono
# mic_index=1 por defecto (MacBook integrado); lista dispositivos con:
# ffmpeg -f avfoundation -list_devices true -i ""
El script proporciona señales audibles de cuenta regresiva + inicio/parada mediante say de macOS + /System/Library/Sounds/Ping.aiff para que el usuario sepa cuándo hablar (la salida estándar del terminal tiene búfer — los mensajes de texto "habla ahora" llegan demasiado tarde). Graba una ventana raw más larga, la recorta a ~10 segundos de voz mediante silenceremove + atrim, reproduce para verificación e imprime el comando curl del siguiente paso.
Ruta B — manual:
# 1. Grabar (mono, 24 kHz nativo — coincide con la tasa interna del modelo)
ffmpeg -f avfoundation -i ":1" -t 12 -ac 1 -ar 24000 raw.wav
# 2. Recortar silencio inicial + tomar primeros 10 segundos de voz
ffmpeg -i raw.wav \
-af "silenceremove=start_periods=1:start_silence=0.05:start_threshold=-40dB,atrim=end=10" \
-ac 1 -ar 24000 ref.wav
# 3. Verificar
ffmpeg -i ref.wav -af volumedetect -f null - 2>&1 | grep volume # el máximo debe ser > -20 dB
afplay ref.wav
POST a /profiles (multipart/form-data — campos obligatorios: name, ref_audio):
curl -X POST http://127.0.0.1:3900/profiles \
-F "name=clon-carlos" \
-F "[email protected]" \
-F "ref_text=El texto exacto dicho en el clip" \
-F "language=Spanish" \
| python3 -m json.tool
# devuelve { "id": "abc12345", "name": "clon-carlos" }
Una vez creado, pasa profile_id a generate_speech (a través del MCP) o directamente mediante POST /generate. Los perfiles persisten en SQLite + archivos de audio de referencia en ~/Library/Application Support/OmniVoice/voices/<id>.<ext> (el backend conserva la extensión subida — .wav si subiste un WAV, .mp3 si MP3, etc.). El estado persiste entre reinicios del backend.
Consejos para el clip de referencia que afectan significativamente la calidad:
| Factor | Por qué importa |
|---|---|
| Un solo hablante | Varios hablantes mezclan la incrustación |
| Voz limpia, sin música/ruido | El modelo también incrusta el ruido |
| Prosodia natural (evitar trabalenguas) | Las muestras de difusión replican la prosodia, no solo el timbre |
| 3-10 segundos es el punto óptimo | < 3 s carece de información; > 10 s añade cómputo sin ganancia de calidad |
Coincidir ref_text con lo hablado | Mejora la alineación, especialmente en referencias ruidosas |
language correcto | Idioma incorrecto → artefactos de transferencia interlingüística |
| Pico de sonoridad ≥ -15 dB | Las referencias silenciosas funcionan pero se normalizan mal |
4. Diseño de voz (sin clip de referencia)
Omite profile_id; proporciona una cadena instruct que describa la voz deseada:
generate_speech(
text="Bienvenido al futuro de los sistemas agentivos.",
instruct="voz femenina de mediana edad, cálida, ritmo pausado y autoritario, estilo documental",
)
Obtén instrucciones predefinidas mediante list_personalities y copia la que coincida con el briefing (narrador, casual, presentador de noticias, etc.).
5. Doblaje de video (solo interfaz web)
El servidor MCP no expone el endpoint de doblaje. El pipeline completo de transcribir → traducir → volver a dar voz → multiplexar está detrás de la interfaz de escritorio (bun run desktop en $OMNIVOICE_HOME) y las rutas REST /dub/*. Cuando el usuario solicite doblar un video, dirígelo a la interfaz; usa este skill solo para las primitivas de síntesis anteriores.
Cuándo NO usar OmniVoice
- Narración rápida solo en inglés en hardware modesto →
kokoro-ttses ~10× más pequeño y 2× en tiempo real en CPU (consulta references/engines-comparison.md) - TTS puntual de mínima fricción → Edge TTS no necesita instalación ni backend
- Máxima calidad posible sin importar el costo → ElevenLabs sigue ganando en pulcritud de narración en inglés; OmniVoice empata o gana en multilingüe + clonación
- Dictado en tiempo real → usa el widget de escritorio de OmniVoice (
⌘+⇧+Space), no el servidor MCP
Recursos
- references/engines-comparison.md — Árbol de decisión entre OmniVoice / kokoro / Voicebox / Edge TTS / ElevenLabs / APIs en la nube
- references/mcp-setup.md — Configuración MCP, ciclo de vida del backend, variables de entorno, solución de problemas
- scripts/check-health.sh —
curl /health, exit 0/1 - scripts/start-backend.sh — Inicia uvicorn en 127.0.0.1:3900 con comprobación de salud
- scripts/stop-backend.sh — Apagado limpio mediante
kill -TERMsobre el PID vinculado - scripts/record-reference.sh — Solo macOS: graba, recorta y verifica un clip de referencia para clonación, con señales audibles (
say+ pitidos del sistema) que evitan el buffer de salida del terminal
Swagger / OpenAPI del backend: http://127.0.0.1:3900/docs (cuando el backend esté activo).
Upstream: github.com/debpalash/OmniVoice-Studio — FSL-1.1-ALv2 (gratuito para uso personal/interno/no comercial; se convierte automáticamente a Apache-2.0 dos años después de cada publicación).