Initial commit: chatterbox TTS CLI v4

BEDIENUNGSANLEITUNG.md

@@ -0,0 +1,200 @@
+# 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:".