tts-sidecar 0.6.0

TTS Sidecar - 100% local voice cloning TTS (Chatterbox Multilingual)

TTS Sidecar

Sistema de síntesis de voz (TTS) 100% local con clonación de voz en español latinoamericano.

• Motor: Chatterbox Multilingual V3 (modelo MIT, 23+ idiomas)
• Clonación de voz: Usa tu propia voz como referencia
• Multiplataforma: Windows x64, Linux x64/ARM64, macOS ARM64 (Apple Silicon)
• Consumible via CLI: Invocable desde cualquier lenguaje de programación

Uso ético y responsable

TTS Sidecar clona voces arbitrarias y el audio que genera no lleva marca de agua (el watermark de PerthNet está desactivado), por lo que no es distinguible por medios técnicos de una grabación real. Esto exige un uso responsable:

• Consentimiento: clona únicamente voces para las que tengas permiso explícito de la persona titular. No clones la voz de nadie sin su autorización.
• No suplantación: no uses la herramienta para hacerte pasar por otra persona, cometer fraude, difamar, ni producir contenido engañoso.
• Divulgación: al publicar o compartir audio sintetizado, indícalo como tal. Recuerda que el audio no contiene marca de agua que lo identifique.
• Reporte: si detectas un uso indebido de este proyecto, repórtalo abriendo un Issue.

El proyecto no impone barreras técnicas (fácilmente sorteables en software libre): la responsabilidad del uso legítimo recae en quien lo emplea.

Características

• Clonación de voz: ~10 segundos de audio de referencia
• 100% offline: Sin APIs externas ni conexiones a internet
• Instalador por plataforma: Un instalador único por SO que despliega el bundle PyInstaller --onedir (carpeta de la aplicación)
• CLI universal: subprocess.run(["./tts-sidecar", "speak", "--text", "..."])
• Audio nativo: APIs nativas del sistema operativo

Instalación

TTS Sidecar se distribuye por dos canales (detalle completo y matriz de trade-offs en docs/DISTRIBUTION.md): el binario pre-compilado por SO (audiencia general, sin Python) y el paquete PyPI (audiencia técnica con Python 3.13+).

Instalación de una línea

En Linux, install.sh automatiza la Opción 1 completa: resuelve el último Release, descarga el .AppImage de tu arquitectura, verifica su checksum contra SHA256SUMS.txt, lo instala en ~/.local/opt/tts-sidecar/ (eliminando la versión anterior si existe) y ejecuta setup (integra el PATH y ofrece descargar el modelo):

curl -fsSL https://raw.githubusercontent.com/CristianRojas-SoftwareEngineer/TTS-Sidecar/main/install.sh | sh

En macOS (Apple Silicon), install-macos.sh hace lo análogo sin sudo ni Homebrew: descarga el .dmg de arm64, verifica su checksum, monta el volumen, copia el .app a ~/Applications, limpia la cuarentena de Gatekeeper, crea el symlink de PATH en ~/.local/bin y ejecuta setup:

curl -fsSL https://raw.githubusercontent.com/CristianRojas-SoftwareEngineer/TTS-Sidecar/main/install-macos.sh | sh

En Windows, install.ps1 hace lo análogo desde PowerShell: descarga el instalador del último Release, verifica su checksum, lo ejecuta en silencio (instalación per-user, sin UAC) y corre tts-sidecar setup:

irm https://raw.githubusercontent.com/CristianRojas-SoftwareEngineer/TTS-Sidecar/main/install.ps1 | iex

Los tres scripts abortan la instalación si el checksum descargado no coincide con SHA256SUMS.txt (ver SECURITY.md).

Alternativa para usuarios de Homebrew (macOS): el Cask del tap propio automatiza checksum, PATH y cuarentena (pero exige tener Homebrew y no provisiona el modelo: hay que correr tts-sidecar setup aparte):

brew tap CristianRojas-SoftwareEngineer/tts-sidecar
brew install --cask tts-sidecar

Desinstalación: tts-sidecar setup --uninstall lo hace en un comando en los tres SO (encadena cleanup --all, revierte la integración de PATH y borra el binario, en ese orden). Añade --yes para omitir la confirmación del cleanup.

• Linux: quita el symlink de PATH y borra ~/.local/opt/tts-sidecar/.
• macOS: quita el symlink de ~/.local/bin y borra el .app. Si instalaste con Homebrew, usa en su lugar brew uninstall --cask --zap tts-sidecar (el comando lo detecta y te remite ahí para no dejar el Caskroom inconsistente).
• Windows: borra los datos y delega el binario y el PATH al desinstalador de Inno Setup. La vía idiomática (Configuración → Aplicaciones, sin admin) sigue disponible como alternativa.

Opción 1: Descargar binario pre-compilado

Descarga el ejecutable para tu plataforma desde Releases:

# Windows: ejecuta el instalador tts-sidecar-<versión>-x86_64-setup.exe.
# Instala en tu perfil (%LOCALAPPDATA%\Programs\tts-sidecar) y escribe el PATH
# de usuario (HKCU), sin privilegios de administrador ni prompt de UAC.
# Agrega tts-sidecar al PATH, muestra una página informativa sobre el modelo y
# ofrece una casilla para descargarlo (ejecuta 'tts-sidecar setup') al terminar.

# Linux: descarga el AppImage de tu arquitectura, hazlo ejecutable y provisiona
chmod +x tts-sidecar-<versión>-x86_64.AppImage    # o -aarch64.AppImage en ARM64
./tts-sidecar-<versión>-x86_64.AppImage setup
# → setup también crea el symlink ~/.local/bin/tts-sidecar para invocarlo por nombre

# macOS (Apple Silicon): monta tts-sidecar-<versión>-arm64.dmg, arrastra el .app
# a Aplicaciones y ejecuta el script "Instalar (PATH + modelo).command" incluido
# en el volumen. El script pide tu contraseña de administrador (sudo) para crear
# el symlink en /usr/local/bin y luego ofrece ejecutar 'setup' como tu usuario.

Mac Intel (x86_64) no está soportado: el toolchain actual (torch≥2.3) no publica wheels macOS x86_64.

El AppImage de Linux requiere glibc ≥ 2.35 (Ubuntu 22.04+, Debian 12+, Fedora 36+ o equivalente): es la versión mínima que soportan los wheels manylinux de las dependencias empaquetadas (torch, onnxruntime). En una distro más antigua, tts-sidecar falla al arrancar con un error del tipo GLIBC_2.35 not found (ver solución de problemas en USAGE.md).

Cada Release publica un SHA256SUMS.txt con el hash de los 4 artefactos; verifica tu descarga contra él antes de ejecutar el instalador (ver SECURITY.md y docs/RELEASING.md).

Primer arranque: SmartScreen / Gatekeeper

Al ejecutar por primera vez el instalador descargado desde el navegador, es esperable que el sistema lo bloquee con una advertencia («Windows protegió tu PC» / «no se puede verificar el desarrollador»). No indica malware: los binarios distribuidos no están firmados con un certificado de código (los certificados son de pago y el proyecto aún no los financia), así que el sistema muestra «editor desconocido» y, al ser cada release un archivo nuevo sin historial de descargas, carece de reputación acumulada ante SmartScreen. La advertencia depende del Mark-of-the-Web, que solo aplica el navegador: el instalador de una línea (irm | iex) descarga por CLI, sin la marca, y no la dispara.

• Windows (SmartScreen): pulsa Más información → Ejecutar de todas formas.
• macOS (Gatekeeper): haz clic derecho sobre el .app/.dmg → Abrir y confirma (o quita la cuarentena con xattr).

El canal PyPI (uv tool install tts-sidecar, ver Opción 2) no dispara ninguno de los dos avisos: el launcher lo genera uv/pipx localmente, sin Mark-of-the-Web ni cuarentena. Detalle en docs/DISTRIBUTION.md.

Solo ocurre en el primer arranque. La forma objetiva de confiar en el artefacto es verificar su SHA-256 contra el SHA256SUMS.txt del Release (ver SECURITY.md). Está previsto firmar los binarios vía SignPath Foundation (firma de código gratuita para proyectos open source) en una versión futura. Detalle paso a paso en USAGE.md.

Provisión del modelo (setup)

El modelo de voz es-mx-latam (varios cientos de MB) no viene incluido en el ejecutable: se descarga una sola vez a la caché de HuggingFace de tu usuario (~/.cache/huggingface/hub). Esto es homólogo en los 3 SO:

• Windows: el instalador ofrece una casilla post-instalación que ejecuta setup por ti, en tu contexto de usuario.
• Linux / macOS: ejecuta tts-sidecar setup manualmente tras instalar.

setup corre los chequeos de entorno (igual que doctor) y descarga el modelo solo si falta; si ya está cacheado, termina al instante sin descargar. Hasta que el modelo esté provisionado, speak y daemon start fallan de inmediato y te remiten a tts-sidecar setup (nunca disparan una descarga silenciosa).

Opción 2: Instalar desde PyPI (uv / pipx)

Para audiencia técnica con Python 3.13+ ya instalado:

uv tool install tts-sidecar
# o: pipx install tts-sidecar

tts-sidecar setup     # provisiona el modelo, idéntico al canal nativo
tts-sidecar speak --text "Hola mundo"

Linux: sounddevice requiere la librería del sistema libportaudio2 para reproducir audio (sudo apt install libportaudio2 / sudo dnf install portaudio); no es necesaria si solo usas speak --output a archivo. Ver docs/DISTRIBUTION.md para la matriz completa de trade-offs entre canales y el flujo de actualización/desinstalación.

Opción 3: Compilar desde código

# Instalar dependencias de build
pip install -r requirements.txt

# Compilar
python scripts/build_windows.py    # Windows
python scripts/build_linux.py     # Linux
python scripts/build_macos.py     # macOS

Uso Rápido

Clonación de voz

# Agregar tu voz (requiere ~10 segundos de audio en español)
# Se necesitan DOS archivos: reference (timbre) y speech (conditioning)
tts-sidecar voice add --name mi_voz --reference timbre.wav --speech condicion.wav

# Sintetizar con tu voz clonada
tts-sidecar speak --text "Hola mundo" -v mi_voz

# Generar archivo WAV (speak con --output guarda en vez de reproducir)
tts-sidecar speak --text "Hola mundo" -v mi_voz --output audio.wav

Síntesis básica

# Sintetizar y reproducir con la voz de fábrica 'default' (no requiere audios)
tts-sidecar speak --text "Hola mundo"

# Sobrescribir la voz por defecto con una voz registrada
tts-sidecar speak --text "Hola mundo" --voice mi_voz

# Generar archivo WAV
tts-sidecar speak --text "Hola mundo" --output audio.wav

Sin --voice ni audios explícitos, speak usa la voz de fábrica default (empaquetada, de solo lectura). Ver Modelo de voces.

Modelo de voces

Las voces se resuelven en dos niveles, con precedencia usuario→fábrica:

• Fábrica: empaquetadas en el ejecutable (solo lectura), incluida la voz default. Idénticas en desarrollo y en cualquier instalación.
• Usuario: registradas con voice add, escribibles, guardadas en el directorio de datos de usuario por SO (estables entre ejecuciones).

Registrar una voz de usuario con el mismo nombre que una de fábrica la sobrescribe.

Comandos disponibles

tts-sidecar speak --text "..."          # Sintetizar y reproducir (--output guarda a WAV)
tts-sidecar voice add --name X --reference ref.wav --speech speech.wav  # Agregar voz clonada
tts-sidecar voice remove --name X       # Eliminar voz
tts-sidecar voice list                  # Listar voces (--json disponible)
tts-sidecar devices                     # Dispositivos de audio (--json disponible)
tts-sidecar doctor                      # Diagnóstico (--json disponible)
tts-sidecar setup                       # Provisionar: chequeos + descargar modelo si falta
tts-sidecar version                     # Versión (--json disponible)

Invocación desde cualquier lenguaje

# Bash/shell
./tts-sidecar speak --text "Hola mundo"

# Python
subprocess.run(["./tts-sidecar", "speak", "--text", "Hola mundo"])

# Node.js
child_process.spawn("./tts-sidecar", ["speak", "--text", "Hola mundo"])

# Rust
std::process::Command::new("./tts-sidecar")
    .args(["speak", "--text", "Hola"])
    .output()?;

# Go
exec.Command("./tts-sidecar", "speak", "--text", "Hola")

# Java
new ProcessBuilder("./tts-sidecar", "speak", "--text", "Hola").start()

Arquitectura

┌─────────────────────────────────────────────────────┐
│              tts-sidecar (binario CLI)              │
│   Compilado con PyInstaller --onedir (carpeta de app) │
└──────────────────────┬──────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│           Chatterbox Multilingual V3                 │
│   Modelo: es-mx-latam (caché de HuggingFace)        │
│   Licencia: MIT                                     │
│   Idiomas: 23+ (incl. español es)                    │
└─────────────────────────────────────────────────────┘

Licencia

GPL-3.0-or-later — el código de tts-sidecar se distribuye bajo la GNU General Public License v3 (ver LICENSE). Es software libre y de uso comercial permitido, con la condición copyleft de que los trabajos derivados que se distribuyan se liberen bajo la misma licencia.

El modelo de voz Chatterbox Multilingual V3 se distribuye bajo licencia MIT (verificada en HuggingFace), al igual que el modelo base ResembleAI/chatterbox. Las dependencias empaquetadas conservan sus propias licencias, en su mayoría permisivas (MIT/BSD/Apache 2.0), con algunas de copyleft compatible con GPLv3 (MPL-2.0, LGPL-2.1+, GPLv3+). Los runtimes propietarios de NVIDIA CUDA que lista el lockfile universal no se incluyen en ningún artefacto distribuido (todos los builds son CPU-only); solo aplican a instalaciones desde código fuente con ese lock. El detalle completo y verificado está en THIRD-PARTY-LICENSES.md.

Documentación

• docs/GOAL.md - Meta del proyecto
• docs/ROADMAP.md - Estado actual y roadmap al goal inmediato
• docs/DESIGN.md - Diseño técnico
• docs/ARCHITECTURE.md - Arquitectura del sistema
• docs/DAEMON-MODE.md - Daemon mode (servidor persistente)
• docs/BUILD.md - Guía de compilación PyInstaller
• docs/DISTRIBUTION.md - Canales de distribución (nativo + PyPI)
• docs/PARITY.md - Estado de paridad de experiencia entre Windows, Linux y macOS

Comunidad y soporte

• CHANGELOG.md - Historial de cambios por versión
• CONTRIBUTING.md - Cómo contribuir (setup, tests, estilo, flujo de PR)
• SECURITY.md - Política de seguridad y cómo reportar vulnerabilidades
• Issues - Reporte de bugs y solicitudes de función