Initial commit: chatterbox TTS CLI v4

2026-05-16 08:56:50 +02:00 · 2026-05-16 08:56:50 +02:00 · bed29fb1c8
commit bed29fb1c8
6 changed files with 1434 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,139 @@
+# 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).