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

Nach dem Bearbeiten: Dienste neu starten

Die Kommandozeile liest das Wörterbuch bei jedem Aufruf neu — dort wirkt eine Änderung sofort. Die Dienste halten es dagegen im Speicher und müssen neu gestartet werden:

systemctl --user restart chatterbox-tts        # HTTP-Service / MCP (Port 9999)
systemctl --user restart open-notebook-tts     # Open Notebook (Port 8901), falls genutzt

Vergisst du das, sprechen die Dienste weiter die alte Aussprache — ohne Fehlermeldung.

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.