chatterbox-tts-cli/README.md

# chatterbox-tts-cli

Ein kommandozeilenbasierter TTS-Assistent (Text-to-Speech) auf Basis von
[Chatterbox TTS](https://github.com/resemble-ai/chatterbox) (Resemble AI).
Optimiert für deutsche Sprache und den Einsatz als Audio-Vorlesehilfe, z. B.
für Senioren oder Accessibility-Anwendungen.

## Features

- **Satz-für-Satz-Streaming** — gibt den ersten Satz aus, während die nächsten
  bereits generiert werden; minimale Latenz
- **Lückenlose Audiowiedergabe** — Callback-basierter OutputStream mit
  vorgefertigten Blöcken; keine Unterbrechungen zwischen Sätzen
- **Geschwindigkeitsanpassung** — pitch-erhaltende Zeitstreckung via
  pyrubberband (R3-Engine); konfigurierbar per `--speed`
- **Voice Cloning** — optionale WAV-Referenz für Akzent und Klang
- **Mehrsprachig** — Deutsch, Englisch und 20+ weitere Sprachen via
  `ChatterboxMultilingualTTS` (erfordert Multilingual-Setup, s. u.)
- **Deutsche Textnormalisierung**
  - Abkürzungen: ARD → "Ah Er De", YMCA → "Ypsilon Em Tse Ah"
  - Komposita: US-Präsident → "U Es Präsident"
  - Uhrzeiten: 14:58 → "vierzehn Uhr achtundfünfzig"
  - Jahreszahlen: 2026 → "zweitausendsechsundzwanzig"
  - Einheiten: 120 km/h → "120 Kilometer pro Stunde"
- **Konfigurierbares Aussprache-Wörterbuch** — Eigennamen und Fremdwörter
  per JSON-Datei phonetisch überschreiben
- **Automatische Satz-Erkennung** — intelligentes Splitting inkl.
  Ordinalzahlen, Paragraphen und Trennzeilen

## Systemvoraussetzungen

- Python 3.11+
- CUDA-GPU empfohlen (RTX 3070 oder besser; CPU möglich aber langsam)
- Linux mit PipeWire oder PulseAudio (für `--audio-device pulse`)
- `rubberband-cli` (nur wenn `--speed` != 1.0 genutzt wird):
  ```bash
  sudo apt install rubberband-cli
  ```

## Installation

```bash
# 1. Conda-Umgebung erstellen (empfohlen)
conda create -n chatterbox python=3.11
conda activate chatterbox

# 2. PyTorch mit CUDA installieren (Beispiel für CUDA 12.4)
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu124

# 3. Chatterbox und weitere Abhängigkeiten
pip install chatterbox-tts sounddevice pyrubberband

# 4. Skript herunterladen
# chatterbox_cli_v4.py in das Arbeitsverzeichnis legen
```

### Multilingual-Setup (für Deutsch und andere Nicht-Englisch-Sprachen)

Das Standard-Paket `chatterbox-tts` enthält die Multilingual-Unterstützung
noch nicht vollständig. Notwendige Schritte:

```bash
# Multilingual-Modell herunterladen (beim ersten Start automatisch)
# Modell-Auswahl: v3 (Standard, besser) oder v2
# Wird in ~/.cache/huggingface/ gespeichert
```

Beim ersten Start mit `--lang de` werden die Modelle automatisch heruntergeladen
(ca. 2–3 GB).

## Schnellstart

```bash
# Deutschen Text vorlesen (aus Datei)
python chatterbox_cli_v4.py --lang de --input mein_text.txt

# Mit eigener Stimme (Voice Cloning)
python chatterbox_cli_v4.py --lang de \
  --voice meine_stimme.wav \
  --input mein_text.txt

# Etwas langsamer sprechen
python chatterbox_cli_v4.py --lang de --speed 0.85 --input mein_text.txt

# Englisch
python chatterbox_cli_v4.py --lang en --text "Hello, how are you today?"
```

## Optionen

| Option | Standard | Beschreibung |
|--------|----------|--------------|
| `--text TEXT` | — | Text direkt als Argument |
| `--input DATEI` | — | UTF-8-Textdatei als Eingabe |
| `--lang CODE` | `de` | Sprachcode (de, en, fr, es, …) |
| `--voice DATEI.wav` | — | Referenz-WAV für Voice Cloning |
| `--speed 0.85` | `1.0` | Geschwindigkeit (0.7–1.3); pitch bleibt gleich |
| `--audio-device` | `pulse` | Ausgabegerät (z. B. `pulse`, `default`) |
| `--t3-model` | `v3` | Multilingual-Modell: `v3` oder `v2` |
| `--acronym-mode` | `german` | Akronym-Modus: `german`, `space`, `period_space` |
| `--pronunciation-dict` | — | JSON-Datei mit Aussprache-Substitutionen |
| `--save` | nein | WAV-Datei speichern |
| `--output DATEI.wav` | — | Ausgabepfad (impliziert `--save`) |
| `--no-play` | — | Nur speichern, nicht abspielen |
| `--no-sentence-mode` | — | Text als Ganzes statt satzweise verarbeiten |
| `--debug-delay N` | `0` | Pause in Sekunden vor jedem Satz (zum Testen) |
| `--speed` | `1.0` | Sprechgeschwindigkeit |

## Aussprache-Wörterbuch

Für Eigennamen und Fremdwörter, die das Modell falsch ausspricht:

```json
{
  "Xi Jinping": "Schi Dschinping",
  "Putin": "Pjutin",
  "Seoul": "Söul"
}
```

```bash
python chatterbox_cli_v4.py --lang de \
  --pronunciation-dict aussprache.json \
  --input nachricht.txt
```

## Bekannte Einschränkungen

- **Wortbetonung** lässt sich nicht steuern — das Modell kennt kein SSML.
  Abhilfe: Voice-Referenz mit gewünschter Betonung aufnehmen.
- **Chinesische/japanische Namen** werden phonetisch angenähert; das Modell
  ist nicht für asiatische Phonetik optimiert.
- **Sehr lange Texte** werden satzweise verarbeitet; zwischen Absätzen können
  kurze Pausen entstehen (Generierungszeit für den nächsten Satz).

## Lizenz

MIT — dieses Skript. Das Chatterbox-Modell unterliegt der MIT-Lizenz von
Resemble AI. Die Modellgewichte sind nicht-kommerziell (CC BY-NC 4.0).