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 aufnehmen und verwenden

Das Programm kann deine Stimme nachahmen — dafür braucht es eine Aufnahme von dir, 30–60 Sekunden lang.

Schritt 1: Stimme aufnehmen

Öffne ein Terminal und gib folgendes ein:

arecord -D pulse -f S16_LE -r 48000 -c 1 --duration=60 \
  ~/chatterbox-tts-cli/my_voice_deutsch_60s.wav

Das Programm nimmt 60 Sekunden auf und stoppt dann automatisch. Lies dabei den Trainingstext laut und deutlich vor.

Aufnahme abhören (zur Kontrolle):

aplay ~/chatterbox-tts-cli/my_voice_deutsch_60s.wav

Schritt 2: Stimme nutzen

conda activate chatterbox
python chatterbox_cli_v4.py --lang de \
  --voice my_voice_deutsch_60s.wav \
  --input mein_text.txt

Tipps für eine gute Aufnahme

• Ruhiger Raum, kein Hintergrundlärm, Fenster schließen
• Normaler Abstand zum Mikrofon (ca. 20–40 cm)
• Gleichmäßig und in normalem Tempo sprechen — nicht zu schnell, nicht zu langsam
• Mindestens 30 Sekunden, besser 60 Sekunden

Welches Mikrofon wird verwendet?

Das Programm nutzt automatisch das Standard-Mikrofon von PipeWire/PulseAudio. Um zu sehen, welches Gerät aktiv ist:

pactl list sources short | grep -v monitor

Das aktive Gerät (RUNNING) wird für die Aufnahme verwendet.

---

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

Das mitgelieferte Wörterbuch

Rund 200 Begriffe sind schon eingebaut und werden automatisch korrigiert — englische Fachbegriffe („Repository" → „Ripositori", „Deployment" → „Diploiment"), Eigennamen („Donald Trump" → „Donald Tramp"), Firmen („Nvidia" → „Enwidia") und Abkürzungen („GPU" → „Geh Peh Uh"). Nachsehen, was drinsteht:

python pronunciation.py de

Gepflegt wird die Liste in pronunciation/de.json. Eigene Begriffe kannst du auf drei Wegen ergänzen — jede Stufe überschreibt die vorherige:

Wo	Wofür
pronunciation/de.json	die gemeinsame Liste, gilt für alle Programme (CLI, Service, MCP)
~/.config/chatterbox/pronunciation/de.json	deine persönlichen Ergänzungen
CHATTERBOX_PRONUNCIATION_DICT=/pfad/zu.json	einmalig, z. B. für ein einzelnes Projekt
--pronunciation-dict datei.json	nur für diesen einen Aufruf

Neue Begriffe finden statt raten

Welche Wörter falsch klingen, muss man nicht erraten. Das Hilfsprogramm sucht in einem Text alles, was ein deutsches Wörterbuch nicht kennt — das sind fast immer genau die englischen Fachbegriffe und fremden Namen:

python pronunciation_candidates.py mein_text.txt          # Liste, häufigste zuerst
python pronunciation_candidates.py mein_text.txt --json   # Gerüst zum Ausfüllen

Die Umschrift schreibst du selbst — sie soll so aussehen, wie ein deutscher Sprecher das Wort vorlesen würde. Nicht komplett großschreiben („EIGEN" würde als „E I Ge E En" buchstabiert).

Warum Umschrift und nicht Lautschrift (IPA)? Chatterbox liest Buchstaben, keine Laute. Ein IPA-Eingang existiert nicht — getestet: aus ɹɪˈpɑzɪˌtɔɹi wird hörbar „Ripacitari". Deshalb schreibt man die Aussprache mit deutschen Buchstaben auf.

---

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

Audio-Datei herunterladen (statt auf dem Server abspielen):

# 1. Auftrag erteilen mit keep_audio=true
JOB=$(curl -s -X POST http://COMPUTER-IP:9999/speak \
  -H "Content-Type: application/json" \
  -d '{"text": "Hallo Welt", "lang": "de", "keep_audio": true}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['job_id'])")

# 2. Warten bis fertig, dann herunterladen
sleep 40
curl -o ausgabe.wav http://COMPUTER-IP:9999/audio/$JOB

Die Datei wird nach dem Herunterladen automatisch gelöscht.

---

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
• Datumsangaben vorlesen: „03.06.2026" wird zu „Dritter Sechster Zwanzigsechsundzwanzig"
• 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
• 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"
• 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.