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

---

## Das Programm starten

Öffne ein Terminal und gib folgende Befehle ein:

```bash
conda activate chatterbox
cd ~/Python_Programs/chatterbox
```

---

## 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 ältere Hörer
- `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
{
  "Xi Jinping": "Schi Dschinping",
  "Seoul": "Söul",
  "Macron": "Makron"
}
```

Dann so aufrufen:

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

---

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

- Abkürzungen buchstabieren: ARD wird zu „Ah Er De", YMCA zu „Ypsilon Em Tse Ah"
- 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"
- Trennzeilen wie „--- Ende ---" werden stillschweigend übersprungen

---

## Wenn etwas nicht klappt

**Kein Ton zu hören:**
```bash
# Ausgabegerät prüfen
python -c "import sounddevice; print(sounddevice.query_devices())"
```
Dann `--audio-device pulse` oder das passende Gerät angeben.

**„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** (z. B. chinesische oder arabische Namen) 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:".