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 verwenden

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

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

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

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

```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
- **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:**
```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.