chatterbox-tts-cli/BEDIENUNGSANLEITUNG.md

Bedienungsanleitung: Chatterbox TTS-Assistent

Dieses Programm liest Texte laut vor — ähnlich wie ein Vorlesedienst. Es wandelt geschriebenen Text in natürlich klingende Sprache um.

---

Was das Programm braucht

• Einen Computer mit Linux
• Eine installierte Conda-Umgebung namens chatterbox
• Eine Grafikkarte (GPU) — macht das Programm deutlich schneller

---

Automatischer Start im Hintergrund

Der Sprach-Service startet automatisch, sobald du dich am Computer anmeldest. Du musst nichts weiter tun — er läuft im Hintergrund und wartet auf Anfragen.

Ob der Service läuft, prüfst du so:

systemctl --user status chatterbox-tts

Bei Problemen neu starten:

systemctl --user restart chatterbox-tts

---

Das Kommandozeilen-Programm starten

Für die direkte Nutzung über das Terminal:

conda activate chatterbox
cd ~/chatterbox-tts-cli

---

Einen Text vorlesen lassen

Text aus einer Datei vorlesen

python chatterbox_cli_v4.py --lang de --input mein_text.txt

Ersetze mein_text.txt durch den Pfad zu deiner Textdatei. Die Datei muss im Format UTF-8 gespeichert sein (das ist der Standard bei modernen Texteditoren).

Einen kurzen Text direkt eingeben

python chatterbox_cli_v4.py --lang de --text "Guten Morgen! Wie geht es Ihnen heute?"

---

Die eigene Stimme verwenden

Wenn du eine Aufnahme deiner Stimme hast (eine WAV-Datei von ca. 10–30 Sekunden), kann das Programm diese Stimme nachahmen:

python chatterbox_cli_v4.py --lang de \
  --voice meine_stimme.wav \
  --input mein_text.txt

Tipp: Eine Aufnahme von 20 Sekunden reicht aus. Am besten in ruhiger Umgebung und deutlich sprechen.

---

Sprache wählen

Das Programm kann in vielen Sprachen vorlesen. Die Sprache wählt man mit --lang:

Befehl	Sprache
--lang de	Deutsch (Standard)
--lang en	Englisch
--lang fr	Französisch
--lang es	Spanisch
--lang it	Italienisch

Beispiel auf Englisch:

python chatterbox_cli_v4.py --lang en --text "Good morning, how are you?"

---

Sprechgeschwindigkeit anpassen

Mit --speed kann man einstellen, wie schnell der Text gesprochen wird.

• 1.0 = normale Geschwindigkeit (Standard)
• 0.85 = etwas langsamer — gut für entspanntes Zuhören
• 0.75 = deutlich langsamer
• 1.2 = etwas schneller

python chatterbox_cli_v4.py --lang de --speed 0.85 --input mein_text.txt

Hinweis: Die Stimmhöhe bleibt gleich — nur das Tempo ändert sich.

---

Audio als Datei speichern

Wenn du die Audiodatei behalten möchtest:

python chatterbox_cli_v4.py --lang de --save --input mein_text.txt

Die Datei wird automatisch als mein_text.de.wav gespeichert — im selben Ordner wie die Eingabedatei.

Oder mit eigenem Dateinamen:

python chatterbox_cli_v4.py --lang de --output ausgabe.wav --input mein_text.txt

---

Nur speichern, nicht abspielen

python chatterbox_cli_v4.py --lang de --no-play --output ausgabe.wav --input mein_text.txt

---

Aussprache von Eigennamen anpassen

Manche Namen — vor allem aus anderen Sprachen — werden falsch ausgesprochen. Du kannst das mit einer einfachen Textdatei im JSON-Format korrigieren.

Beispiel: Datei aussprache.json anlegen:

{
  "Seoul": "Söul",
  "Macron": "Makron",
  "Kubernetes": "Kubernetis"
}

Dann so aufrufen:

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

Häufige englische Begriffe wie „GitHub" (→ „Git Hab"), „YouTube" (→ „Jutjub") oder „Wi-Fi" (→ „Wai Fai") werden bereits automatisch korrekt ausgesprochen.

---

Den Service aus dem Netzwerk nutzen

Der Service ist im gesamten Heimnetzwerk erreichbar — zum Beispiel vom Handy, Tablet oder einem anderen Computer.

Text vorlesen lassen (aus jedem Gerät im Netzwerk):

curl -X POST http://COMPUTER-IP:9999/speak \
  -H "Content-Type: application/json" \
  -d '{"text": "Hallo aus dem Netzwerk", "lang": "de"}'

COMPUTER-IP ersetzen durch die IP-Adresse dieses Computers (z. B. 192.168.1.42).

Aktuelle IP-Adresse herausfinden:

hostname -I

Ausgabe pausieren und fortsetzen:

curl -X POST http://COMPUTER-IP:9999/pause
curl -X POST http://COMPUTER-IP:9999/resume

Ausgabe stoppen:

curl -X POST http://COMPUTER-IP:9999/stop

---

KI-Assistenten lassen vorlesen

Wenn du einen KI-Assistenten auf diesem oder einem anderen Gerät nutzt, kann er den TTS-Service direkt ansprechen:

Claude (Claude Code / Claude Desktop)

Claude ist bereits mit dem TTS-Service verbunden. Du kannst Claude einfach bitten, etwas vorzulesen, zu pausieren oder zu stoppen — er ruft den Service automatisch auf.

Beispiel-Anfragen an Claude:

„Lies mir bitte diesen Text vor: ..." „Pause bitte." „Weiter."

Home Assistant

In der configuration.yaml folgendes eintragen:

rest_command:
  tts_sprechen:
    url: "http://COMPUTER-IP:9999/speak"
    method: POST
    content_type: "application/json"
    payload: '{"text": "{{ text }}", "lang": "de"}'

  tts_pause:
    url: "http://COMPUTER-IP:9999/pause"
    method: POST

  tts_weiter:
    url: "http://COMPUTER-IP:9999/resume"
    method: POST

Danach in einer Automation verwendbar:

service: rest_command.tts_sprechen
data:
  text: "Die Waschmaschine ist fertig."

Ollama / LM Studio / Open WebUI

Lokale KI-Modelle (z. B. llama, qwen) können über eine kleine Hilfsklasse mit dem Service verbunden werden — Details in der README.md.

---

Typischer Arbeitsablauf

1. Text in einem Editor schreiben und als .txt-Datei speichern
2. Terminal öffnen, conda activate chatterbox
3. Programm aufrufen:

   python chatterbox_cli_v4.py --lang de --voice meine_stimme.wav --input text.txt
   

4. Das Programm beginnt sofort zu sprechen — Satz für Satz

---

Was das Programm automatisch macht

• Markdown-Formatierung bereinigen: **fett**, # Überschrift, - Listen und Links werden vor der Sprachausgabe entfernt
• Emojis entfernen: Smileys und Symbole (😊, 🎉) werden still übergangen
• Abkürzungen buchstabieren: ARD wird zu „Ah Er De", YMCA zu „Ypsilon Em Tse Ah"
• Tech-Abkürzungen richtig sprechen: CPU, GPU, USB, API, JSON u. a. werden lateinisch buchstabiert (nicht auf Deutsch)
• Zusammengesetzte Wörter mit Abkürzung: „US-Präsident" wird zu „U Es Präsident"
• Uhrzeiten vorlesen: „14:58" wird zu „vierzehn Uhr achtundfünfzig"
• Jahreszahlen aussprechen: „2026" wird zu „zweitausendsechsundzwanzig"
• Einheiten übersetzen: „25 °C", „100 kWh", „10 m²", „100 W" werden ausgeschrieben
• Trennzeilen überspringen: Linien wie „--- Ende ---" werden stillschweigend übersprungen

---

Wenn etwas nicht klappt

Kein Ton zu hören:

python -c "import sounddevice; print(sounddevice.query_devices())"

Dann --audio-device pulse oder das passende Gerät angeben.

Service antwortet nicht:

systemctl --user restart chatterbox-tts
# Warte 5 Sekunden, dann:
curl http://localhost:9999/health

„Modell nicht gefunden": Beim ersten Start wird das Modell heruntergeladen (~2 GB). Sicherstellen, dass eine Internetverbindung besteht.

Programm ist sehr langsam: Ohne GPU dauert die Generierung länger als die Wiedergabe — ein Satz kann 30–60 Sekunden brauchen. Mit GPU (CUDA) dauert es ca. 5–10 Sekunden.

---

Bekannte Grenzen

• Betonung einzelner Wörter lässt sich nicht direkt steuern. Eine Aufnahme der eigenen Stimme mit natürlicher Betonung kann helfen.
• Manche Fremdwörter klingen nicht immer perfekt — mit der Aussprache-Datei lässt sich das korrigieren.
• Das Programm liest alles vor, was in der Datei steht — also auch Überschriften und Metadaten wie „Schlagzeile:" oder „Stand:".
• Eine laufende Ausgabe kann erst am Ende des aktuellen Satzes unterbrochen werden, nicht sofort mitten im Wort.