Nota editorial de Ehrigite
Este artículo documenta una decisión de diseño propia: convertir la conversión de voz local en una experiencia parecida a Ollama, con modelos descargables, WebUI y API. No es una lista general de herramientas; parte de problemas concretos observados al comparar RVC, seed-vc, vcclient y GPT-SoVITS.
- Valor propio: explica por qué se diseñó koelab y qué fricciones intenta resolver.
- Uso previsto: orientar a lectores que quieren probar voz local sin montar una cadena compleja desde cero.
- Límite: los proyectos de voz cambian rápido; conviene revisar el repositorio y dependencias antes de instalar.
Hay muchas herramientas para cambiar la voz. Ninguna es realmente fácil de usar.
RVC acumula más de 700 issues abiertos sin señales de vida. seed-vc está archivado. vcclient no corre en Mac y no tiene API. GPT-SoVITS tarda dos horas en configurarse. Todas son herramientas — no plataformas.
Por eso creé koelab.
El concepto: Ollama para voz
Ollama estableció un nuevo estándar en el mundo de los LLM: descargás un modelo y lo ejecutás. Eso es exactamente lo que koelab hace, pero con modelos de voz.
koelab pull seed-vc
koelab run seed-vc -i source.wav -r reference.wav -o output.wav
Eso es todo. Si hay una GPU disponible, koelab la usa automáticamente. Si no, recurre a la CPU. Las descargas, el caché y el almacenamiento de modelos — koelab lo gestiona todo.
Qué podés hacer
1. Conversión de voz desde archivos
El caso de uso más simple. Convierte source.wav para que suene como la voz de reference.wav.
koelab run seed-vc \
--input source.wav \
--reference target_voice.wav \
--output converted.wav \
--steps 25 \
--similarity 0.7
--steps controla la cantidad de pasos de difusión — más pasos significa mayor calidad pero procesamiento más lento. --similarity define qué tan parecida es la salida a la voz de referencia (0.0–1.0).
2. Conversión de voz en tiempo real
Convierte la entrada del micrófono a otra voz en tiempo real. Se recomienda fuertemente usar auriculares.
koelab live seed-vc -r reference_voice.wav
Técnicamente funciona con el micrófono y los parlantes integrados de una laptop, pero el audio de los parlantes se cuela al micrófono y genera retroalimentación acústica. Para un uso práctico, los auriculares son prácticamente indispensables.
Para ver los dispositivos disponibles y seleccionar los que necesitás:
koelab audio-devices
koelab live seed-vc \
--reference voice.wav \
--input-device 1 \
--output-device 3 \
--block-time 0.25 \
--silence-threshold 0.003 \
--save-output live.wav # Guarda la salida convertida en un archivo WAV (opcional)
En Windows, al seleccionar dispositivos, asegurate de que la entrada y la salida pertenezcan a la misma API de host — koelab audio-devices muestra el nombre de la API (MME, DirectSound, WASAPI o WDM-KS).
3. Texto a voz (TTS)
koelab soporta irodori-tts para TTS en japonés y xtts-v2 para TTS multilingüe.
koelab pull irodori-tts
koelab speak irodori-tts --text "Hola desde koelab." -o hola.wav
koelab pull xtts-v2
koelab speak xtts-v2 --text "Hola desde koelab." --language es -o hola_es.wav
xtts-v2 requiere --reference (el flag --no-ref no está soportado).
xtts-v2 soporta 17 idiomas, incluyendo español, inglés, francés, alemán, japonés y coreano.
4. WebUI + REST API
pip install "koelab[api]"
koelab serve
Abrí http://localhost:11435 en tu navegador para acceder a la WebUI.
Lo que podés hacer en la WebUI:
- Grabar directamente desde el micrófono y usar la grabación como audio fuente — con indicador de nivel en tiempo real
- Guardar voces de referencia en una biblioteca, con nombre personalizado para reutilizarlas fácilmente
- Marcar hasta tres voces de referencia como favoritas para acceso rápido
- Explorar el historial de conversiones, reproducir resultados, descargar archivos y reutilizar configuraciones
- Cambiar entre presets: rápido / balanceado / calidad
- Usar la página
/ttspara texto a voz con irodori-tts y xtts-v2
La API está construida sobre FastAPI. La interfaz Swagger está disponible en http://localhost:11435/docs.
5. Registro de modelos
koelab obtiene la lista de modelos disponibles desde un registro remoto (guardado en caché local por una hora).
koelab models # Lista todos los modelos disponibles (desde el registro remoto)
koelab info seed-vc # Muestra detalles: autor, licencia, VRAM, idiomas soportados, etc.
koelab search tts # Busca modelos por palabra clave
koelab list # Lista los modelos instalados
koelab remove seed-vc # Elimina un modelo instalado
Modelos actualmente en el registro:
| Modelo | Tipo | Descripción |
|---|---|---|
seed-vc | Conversión de voz | Pipeline AR+CFM, alta calidad |
seed-vc-v1 | Conversión de voz | Basado en DiT, rápido |
openvoice | Clonación de timbre | Por MyShell, liviano (0.3 GB) |
irodori-tts | TTS en japonés | Flow Matching, soporta clonación de voz |
xtts-v2 | TTS multilingüe | 17 idiomas, por Coqui |
Instalación
Se recomienda Python 3.11 o 3.12 (se requiere 3.11+). Evitá instalar directamente en tu entorno global de Python — usá un entorno virtual.
# Con venv (Windows)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install --upgrade pip
# Con uv
uv venv
uv pip install koelab
Instalación base
pip install koelab
Nota: pip install koelab por sí solo no instala las dependencias necesarias para ejecutar modelos de voz o TTS. Tenés que instalar los extras correspondientes al modelo que quieras usar.
pip install "koelab[seed-vc]" # para seed-vc y seed-vc-v1
pip install "koelab[openvoice]" # para openvoice
pip install "koelab[irodori]" # para irodori-tts
pip install "koelab[xtts]" # para xtts-v2
Con API + WebUI
pip install "koelab[api]"
[api] solo agrega FastAPI y uvicorn. Para ejecutar modelos, también necesitás los extras específicos indicados arriba.
FFmpeg
No es estrictamente necesario, pero se recomienda fuertemente. FFmpeg es necesario para formatos como .m4a, .aac y .ogg. En Windows, autoffmpeg puede encargarse de la instalación automáticamente.
Docker
git clone https://github.com/superdoccimo/koelab.git
cd koelab
docker compose build
docker compose run koelab pull seed-vc
docker compose run koelab run seed-vc \
-i /app/audio/source.wav \
-r /app/audio/reference.wav \
-o /app/audio/output.wav
Cómo funciona por dentro
Abstracción de motores
Cada modelo implementa la clase base abstracta BaseEngine.
BaseEngine
├── SeedVCEngine (seed-vc, seed-vc-v1)
├── OpenVoiceEngine (openvoice)
└── BaseTTSEngine
├── IrodoriTTSEngine (irodori-tts)
└── XTTSv2Engine (xtts-v2)
Para agregar un nuevo motor, heredás de BaseEngine, implementás load(), convert() y unload(), y añadís una entrada en registry/models.json. Eso es todo.
Registro remoto
Los metadatos de los modelos se obtienen desde registry/models.json en GitHub y se guardan en caché local por una hora, por lo que no hay una solicitud de red en cada comando. También funciona sin conexión usando el último caché disponible.
El comando doctor
Diagnosticá problemas del entorno antes de que se conviertan en un dolor de cabeza.
koelab doctor # Verifica Python, FFmpeg, Git y las dependencias de TTS
koelab doctor irodori-tts # Diagnostica irodori-tts específicamente
koelab doctor xtts-v2 # Diagnostica xtts-v2 específicamente
Cuando algo no funciona en la configuración, este es el primer comando que hay que ejecutar.
Preguntas frecuentes
¿Funciona sin GPU? Sí. Pasá --device cpu, o dejalo en auto y recurrirá a la CPU automáticamente. El procesamiento será significativamente más lento.
¿Funciona en Windows? Sí. El pipeline de CI ejecuta pruebas básicas en Windows con Python 3.11 y 3.12.
¿Cuánta latencia agrega la conversión en tiempo real? Con --block-time 0.1 (bloques de 100ms) en GPU, esperá aproximadamente 200–400ms. En CPU, puede superar el segundo.
¿Cómo puedo hacer que agreguen un nuevo modelo? Abrí un PR que añada una entrada en registry/models.json. Si el motor en sí necesita implementarse, primero abrí un issue para discutirlo.
Enlaces
koelab tiene licencia MIT. El modelo xtts-v2 está sujeto a la licencia Coqui CPML, que restringe el uso comercial. Ejecutá koelab info xtts-v2 para más detalles.
