Metadata-Version: 2.4
Name: tts-sidecar
Version: 0.3.0
Summary: TTS Sidecar - 100% local voice cloning TTS (Chatterbox Multilingual)
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/CristianRojas-SoftwareEngineer/TTS-Sidecar
Project-URL: Repository, https://github.com/CristianRojas-SoftwareEngineer/TTS-Sidecar
Project-URL: Changelog, https://github.com/CristianRojas-SoftwareEngineer/TTS-Sidecar/blob/main/CHANGELOG.md
Keywords: tts,text-to-speech,voice-cloning,chatterbox,offline,español
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Environment :: Console
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: chatterbox-tts>=0.1.7
Requires-Dist: numpy<2.5
Requires-Dist: sounddevice>=0.4.0
Requires-Dist: requests>=2.28.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn[standard]>=0.29.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pycaw>=20240210; sys_platform == "win32"
Dynamic: license-file

# 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](https://huggingface.co/ResembleAI/Chatterbox-Multilingual-es-mx-latam), 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](https://github.com/CristianRojas-SoftwareEngineer/TTS-Sidecar/issues).

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](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 (Linux)

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/` y ejecuta
`setup` (integra el PATH y ofrece descargar el modelo):

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

El script aborta la instalación si el checksum descargado no coincide con
`SHA256SUMS.txt` (ver [SECURITY.md](SECURITY.md#nota-sobre-el-instalador-de-una-línea-de-linux)).
Para desinstalar: `tts-sidecar setup --remove-path` (revierte el symlink de
PATH), borra `~/.local/opt/tts-sidecar/` y `tts-sidecar cleanup --all` (borra
la caché del modelo y los datos de usuario).

### Opción 1: Descargar binario pre-compilado

Descarga el ejecutable para tu plataforma desde [Releases](https://github.com/CristianRojas-SoftwareEngineer/TTS-Sidecar/releases):

```bash
# Windows: ejecuta el instalador tts-sidecar-<versión>-x86_64-setup.exe.
# Requiere privilegios de administrador: instala en Program Files y escribe el
# PATH del sistema en HKLM (aparecerá el prompt de Control de cuentas de usuario).
# 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](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](SECURITY.md) y [docs/RELEASING.md](docs/RELEASING.md)).

### Primer arranque: SmartScreen / Gatekeeper

Al ejecutar el instalador por primera vez, **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.

- **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](#opción-2-instalar-desde-pypi-uv--pipx))
> 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](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](SECURITY.md)). Está previsto firmar los binarios vía
[SignPath Foundation](https://signpath.org/) (firma de código gratuita para
proyectos open source) en una versión futura. Detalle paso a paso en
[USAGE.md](USAGE.md#el-sistema-bloquea-el-primer-arranque-binarios-sin-firmar).

### 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:

```bash
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](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

```bash
# 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

```bash
# 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

```bash
# 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).

### 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

```bash
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
# 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](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**](https://huggingface.co/ResembleAI/Chatterbox-Multilingual-es-mx-latam) (verificada
en HuggingFace), al igual que el modelo base
[`ResembleAI/chatterbox`](https://huggingface.co/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](THIRD-PARTY-LICENSES.md).

## Documentación

- [docs/GOAL.md](docs/GOAL.md) - Meta del proyecto
- [docs/DESIGN.md](docs/DESIGN.md) - Diseño técnico
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - Arquitectura del sistema
- [docs/DAEMON-MODE.md](docs/DAEMON-MODE.md) - Daemon mode (servidor persistente)
- [docs/BUILD.md](docs/BUILD.md) - Guía de compilación PyInstaller
- [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md) - Canales de distribución (nativo + PyPI)

## Comunidad y soporte

- [CHANGELOG.md](CHANGELOG.md) - Historial de cambios por versión
- [CONTRIBUTING.md](CONTRIBUTING.md) - Cómo contribuir (setup, tests, estilo, flujo de PR)
- [SECURITY.md](SECURITY.md) - Política de seguridad y cómo reportar vulnerabilidades
- [Issues](https://github.com/CristianRojas-SoftwareEngineer/TTS-Sidecar/issues) - Reporte de bugs y solicitudes de función
