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:

```bash
systemctl --user status chatterbox-tts
```

Bei Problemen neu starten:

```bash
systemctl --user restart chatterbox-tts
```

---

## Das Kommandozeilen-Programm starten

Für die direkte Nutzung über das Terminal:

```bash
conda activate chatterbox
cd ~/chatterbox-tts-cli
```

---

## Einen Text vorlesen lassen

### Text aus einer Datei vorlesen

```bash
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

```bash
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:

```bash
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):
```bash
aplay ~/chatterbox-tts-cli/my_voice_deutsch_60s.wav
```

### Schritt 2: Stimme nutzen

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
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:

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

---

## Nur speichern, nicht abspielen

```bash
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:

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

Dann so aufrufen:

```bash
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:

```bash
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:

```bash
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):

```bash
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:**
```bash
hostname -I
```

**Ausgabe pausieren und fortsetzen:**
```bash
curl -X POST http://COMPUTER-IP:9999/pause
curl -X POST http://COMPUTER-IP:9999/resume
```

**Ausgabe stoppen:**
```bash
curl -X POST http://COMPUTER-IP:9999/stop
```

**Audio-Datei herunterladen** (statt auf dem Server abspielen):
```bash
# 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:

```yaml
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:
```yaml
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:
   ```bash
   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:**
```bash
python -c "import sounddevice; print(sounddevice.query_devices())"
```
Dann `--audio-device pulse` oder das passende Gerät angeben.

**Service antwortet nicht:**
```bash
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.