Achtung: `yt_untertitel.py` nimmt ohne `-l` Deutsch (`de`), nicht die
Originalsprache. Für englische Videos `-l en` angeben.
Die `.vtt`-Datei braucht man für die [Zeitauswahl](#10-nur-ausschnitte-bearbeiten-zeitauswahl)
mit vorhandenen Dateien. `abschrift_korrigieren.py` nimmt sie auch direkt, der
Zwischenschritt über `vtt2txt.py` ist dann nur nötig, um den Rohtext anzusehen
oder ein Glossar daraus zu erstellen.
`vtt2txt.py` entfernt Zeitstempel, Formatierungen und die Wiederholungen des
rollenden Fensters der YouTube-Auto-Untertitel. Manuell erstellte Untertitel ohne
rollendes Fenster erkennt es selbst und übernimmt sie vollständig.
### 5.3 Andere Quellen
Jede Textdatei (UTF-8) mit einer Abschrift kann direkt korrigiert werden, ebenso
jede WebVTT-Datei (`.vtt`), z. B. aus anderen Videoportalen oder
Transkriptionsprogrammen.
### 5.4 Den Rohtext ansehen
Ein kurzer Blick in den Rohtext lohnt sich: Welche Namen kommen vor, wie sind sie
falsch erkannt? Diese Funde kommen ins Glossar (nächster Schritt).
---
## 6. Schritt 2: Glossar anlegen
Ein Glossar ist eine Textdatei mit bekannten Hörfehlern und korrekten
Schreibweisen. Es ist **der wirksamste Hebel für gute Ergebnisse**: Das Modell
erkennt viele Hörfehler, besonders bei Namen, nicht von allein.
### 6.1 Aufbau
```text
# Kommentare beginnen mit #, leere Zeilen werden ignoriert.
# --- Feste Ersetzungen: falsch => richtig ---
Willly Brand => Willy Brandt
Kremmel => Kreml
Egon Bar => Egon Bahr
# --- Begriffe: korrekte Schreibweisen als Hinweis fürs Modell ---
Multi-Domain Task Force
Michail Gorbatschow
```
Es gibt zwei Arten von Einträgen:
| Eintrag | Wirkung |
|---|---|
| `falsch => richtig` | **Feste Ersetzung.** Wird im Rohtext ersetzt, *bevor* das Modell ihn sieht. Nur ganze Wörter, Groß-/Kleinschreibung zählt, Reihenfolge wie in der Datei. Zuverlässig, aber nur für eindeutige Fälle. |
| `Begriff` | **Hinweis.** Wird dem Modell als korrekte Schreibweise mitgegeben; das Modell korrigiert ähnlich klingende Varianten selbst. Für Namen, die in vielen Varianten falsch erkannt werden. |
Regeln für feste Ersetzungen:
- **Nur eindeutige Fälle.** „das => dass“ wäre fatal, weil es jedes „das“ ersetzt.
Mehrdeutige Wörter mit einem Nachbarwort eindeutig machen:
`über einen Kampf zu scheren => über einen Kamm zu scheren`.
- **Längere Einträge vor kürzeren**, wenn sie sich überschneiden
Dann diesen Abschnitt im Bericht genauer ansehen (Streichungen sind rot
durchgestrichen).
### 7.3 Das Ergebnis
`rede.korrigiert.txt` enthält den Fließtext mit einer Leerzeile zwischen den
Absätzen. Zweifelhafte Stellen markiert das Modell so:
```text
… die Lesart des Modells [prüfen: Originalwortlaut der Abschrift] …
```
Diese Marken vor der Weitergabe auflösen: nachsehen (z. B. im Video), richtige
Fassung stehen lassen, Marke löschen.
---
## 8. Schritt 4: Ergebnis prüfen
Den Bericht `rede.aenderungen.html` im Browser öffnen:
```bash
xdg-open rede.aenderungen.html
```
### 8.1 Aufbau des Berichts
1.**Kopfzeile:** Wortzahlen, Anzahl der Ersetzungen, Einfügungen, Streichungen,
Prüfmarken und Stellen „zu prüfen“.
2.**Zu prüfen:** Tabelle der verdächtigen Änderungen mit Grund, Text vorher,
korrigiertem Text und Zusammenhang. **Hier beginnen.**
3.**Alle Änderungen nach Häufigkeit:** jede Wortänderung mit Anzahl, z. B.
`5 Rammstein → Ramstein`. Gut, um wiederkehrende Hörfehler fürs Glossar zu
finden.
4.**Korrigierter Text** mit farbigen Markierungen:
| Darstellung | Bedeutung |
|---|---|
| gelb hinterlegt, dahinter grau „(Original)“ | ersetztes Wort; beim Darüberfahren mit der Maus erscheint das Original |
| grün | eingefügtes Wort |
| rot durchgestrichen | gestrichenes Wort |
| orange `[prüfen: …]` | Prüfmarke des Modells |
| rot umrahmt | Stelle „zu prüfen“; beim Darüberfahren erscheint der Grund |
| rot umrahmtes ⚠ | hier hat das Modell eigenmächtig etwas gestrichen |
Groß-/Kleinschreibung, Satzzeichen und Schreibweisen wie „z.B.“ → „z. B.“ werden
nicht markiert, damit die eigentlichen Wortänderungen sichtbar bleiben.
### 8.2 Die Liste „Zu prüfen“
Hier stehen Änderungen, die das Modell **von sich aus** gemacht hat und die den
Sinn verändern können. Was die Glossare ersetzt haben, erscheint hier nie.
| Grund | Bedeutung | Beispiel |
|---|---|---|
| gültiges Wort ersetzt | Das alte Wort ist ein echtes Wort (steht in der Wortliste), also vermutlich kein Hörfehler. | „Professor“ → „Professorin“, „unterschreiben“ → „unterscheiden“ |
| stark verändert | Das neue Wort ähnelt dem alten kaum (unter 60 %). | „CT1“ → „ZDF“ |
| eingefügt | Das Modell hat ein Wort ergänzt. | „∅“ → „ist“ |
| gestrichen | Das Modell hat ein Wort weggelassen (Füllwörter wie „äh“ zählen nicht). | „Sicherungskonzepte geht“ → „∅“ |
Nicht gemeldet werden ähnlich bleibende Hörfehler-Korrekturen („Gradwanderung“ →
„Gratwanderung“), reine Zusammen-, Getrennt- und Bindestrich-Schreibung („Clan
**Handarbeit bleibt erhalten.** Wurde `rede.korrigiert.txt` seit dem letzten Lauf
von Hand geändert, überschreibt ein erneuter Lauf sie nicht. Das neue Ergebnis kommt
dann nach `rede.neu.korrigiert.txt` (Bericht: `rede.neu.aenderungen.html`), mit
einer Warnung:
```text
WARNUNG: rede.korrigiert.txt wurde seit dem letzten Lauf geändert (von Hand?) und bleibt erhalten. Neues Ergebnis: rede.neu.korrigiert.txt (mit --ueberschreiben wird die Datei ersetzt)
```
Die eigenen Änderungen lassen sich dann mit einem Vergleichsprogramm übertragen,
z. B. `meld rede.korrigiert.txt rede.neu.korrigiert.txt`. Soll die Handarbeit
verworfen werden: `--ueberschreiben` angeben.
Das Programm erkennt Handarbeit an einer Prüfsumme in `rede.korrigiert.parts/`.
Fehlt sie (erster Lauf mit dieser Version, Ordner gelöscht), gilt jede abweichende
| `rede.korrigiert.txt` | korrigierte Abschrift | ja, außer sie wurde von Hand geändert (dann `rede.neu.korrigiert.txt`, siehe [Abschnitt 9](#9-schritt-5-nachbessern-und-erneut-laufen-lassen)) |
| `rede.aenderungen.html` | Änderungsbericht | ja, bei jedem Lauf |
| `rede.korrigiert.parts/` | Zwischenstände | wird ergänzt; darf jederzeit gelöscht werden |
| `rede.glossar.entwurf.txt` | Glossar-Entwurf von `glossar_vorschlag.py` | ja |
| `rede.glossar.entwurf.parts/` | Zwischenstände des Entwurfs | wird ergänzt |
Ohne `-o` liegt das Ergebnis neben der Eingabedatei. Bei `-u` ohne `-o` im
aktuellen Verzeichnis. Fehlende Verzeichnisse in `-o` werden angelegt.
### 12.2 Standard-Dateinamen
Ohne `-o` (bzw. `-n` bei `yt_untertitel.py`) entsteht der Name aus **Kanal, Titel
und Hochladedatum**:
| Video | Name |
|---|---|
| Kanal „John Mearsheimer“, „Episode 1: Origins of the War In Ukraine“ | `John_Mearsheimer_Offensive_Realism_Episode_1_Origins_of_the_War_In_Ukraine_2026-07-30` |
| Kanal „GGBLahnstein“, „Prof. Gabriele Krone-Schmalz – Respekt geht anders – …“ | `GGBLahnstein_Prof_Gabriele_Krone-Schmalz_Respekt_geht_anders_2026-07-30` |
Wörter werden mit `_` verbunden, Sonderzeichen entfallen, Bindestriche bleiben.
Kanal und Titel werden gekürzt (40 bzw. 60 Zeichen). Dasselbe Video ergibt immer
denselben Namen.
---
## 13. Zwischenstände, Abbruch und Fortsetzen
Jeder fertig korrigierte Abschnitt, jede Absatzgliederung und jede Entscheidung
beim Verbinden kurzer Absätze wird sofort in `<Ausgabe>.parts/` gespeichert.
- **Abbrechen** ist jederzeit mit `Strg+C` möglich.
- **Fortsetzen:** denselben Befehl erneut aufrufen. Fertige Abschnitte werden
übersprungen („Abschnitt 2/5 bereits vorhanden, übersprungen.“).
- Ändern sich Modell, Anweisung, Glossar oder der Text eines Abschnitts, wird genau
dieser Teil neu berechnet; alte Zwischenstände stören nicht.
- Der Ordner `*.parts/` darf jederzeit gelöscht werden; dann wird alles neu
Jedes in Ollama installierte Modell lässt sich mit `-m` wählen (auch bei
`glossar_vorschlag.py`). Zwischenstände verschiedener Modelle vermischen sich
nicht. Kleinere Modelle sind schneller, ändern aber öfter eigenmächtig Wörter;
die Liste „Zu prüfen“ wird dann länger. Das Standardmodell steht als `MODEL` oben in
`abschrift_korrigieren.py`.
Weitere Einstellungen (Abschnittsgröße, Absatzlängen, Schwellen) sind in der
[README](README.md#einstellungen) beschrieben.
---
## 15. Fehlermeldungen und Lösungen
| Meldung | Ursache und Lösung |
|---|---|
| `Ollama nicht erreichbar (…). Läuft der Dienst?` | Ollama läuft nicht: `sudo systemctl start ollama` oder in einem eigenen Terminal `ollama serve`. |
| `Modell „qwen3:32b“ ist in Ollama nicht installiert.` | `ollama pull qwen3:32b` oder mit `-m` ein installiertes Modell wählen (`ollama list`). |
| `yt-dlp nicht gefunden (Installation: pip install yt-dlp).` | yt-dlp installieren; danach prüfen, ob `yt-dlp --version` im Terminal funktioniert. |
| `yt-dlp konnte das Video nicht abrufen: …` | URL falsch, Video privat/gelöscht, kein Netz, oder yt-dlp veraltet: `pip install -U yt-dlp`. |
| `Download fehlgeschlagen: … HTTP Error 429` | YouTube drosselt; einige Minuten warten und erneut versuchen. |
| `Keine Untertitel in „de“ (weder manuell noch automatisch in Originalsprache).` | Das Video hat keine passende Spur. Die Meldung listet die vorhandenen Sprachen; ggf. mit `-l` eine davon wählen. Ist das Video z. B. englisch, `-l en` angeben. |
| `Der Beitrag ist auf „fr“; unterstützt: de, en (-l).` | Nur Deutsch und Englisch werden korrigiert. |
| `-z braucht Zeitstempel: nur mit .vtt-Eingabe oder -u.` | Zeitauswahl geht nicht mit `.txt`. Die `.vtt`-Datei oder `-u URL` verwenden. |
| `WARNUNG: rede.korrigiert.txt wurde seit dem letzten Lauf geändert (von Hand?) …` | Die Datei wurde nachbearbeitet und bleibt erhalten; das neue Ergebnis steht in `rede.neu.korrigiert.txt`. Änderungen übertragen oder mit `--ueberschreiben` ersetzen, siehe [Abschnitt 9](#9-schritt-5-nachbessern-und-erneut-laufen-lassen). |
| `WARNUNG: rede.txt existiert mit anderem Inhalt und bleibt unverändert.` | Bei `-u` wird ein vorhandener, z. B. von Hand bearbeiteter Rohtext nie überschrieben. Korrigiert wird trotzdem der frisch geladene Text. Wer den neuen Rohtext braucht, die alte Datei umbenennen. |
| `WARNUNG: Abschnitt 3: 1180 → 1090 Wörter (8% Abweichung) …` | Das Modell hat möglicherweise etwas ausgelassen oder ergänzt. Abschnitt im Bericht prüfen. Bei Bedarf die genannte Datei in `.parts/` löschen und erneut laufen lassen. |
| `Abschnitt 3 wurde abgeschnitten. CHUNK_SIZE verkleinern und erneut starten.` | Die Antwort des Modells war zu lang. `CHUNK_SIZE` oben in `abschrift_korrigieren.py` verkleinern (z. B. 900). |
| `Absatzgliederung: unbrauchbare Antwort: …` / `Absätze verbinden: unbrauchbare Antwort: …` | Das Modell hat kein gültiges JSON geliefert; selten. Erneut starten, die Korrektur selbst ist zwischengespeichert. Tritt es wiederholt auf, ein anderes Modell versuchen. |
| `Hinweis: keine Wortliste für „de“ (Paket wngerman); …` | `sudo apt install wngerman` (für Englisch `wamerican`). Ohne Wortliste fehlt im Bericht nur der Grund „gültiges Wort ersetzt“. |
| `Hinweis: keine Untertitel im Bereich …` | Einer von mehreren Bereichen ist leer und wird übersprungen. |
| `Keine Berechtigung` beim Start mit `./…` | `chmod +x *.py` oder `python3 programm.py …` aufrufen. |
| Lauf ist extrem langsam | Das Modell passt nicht in den Grafikspeicher. `OLLAMA_NUM_PARALLEL=1` setzen (siehe [Abschnitt 2.2](#22-grafikkarte)), andere Programme mit Grafikspeicherbedarf schließen oder ein kleineres Modell wählen. Prüfen mit `ollama ps` (Spalte PROCESSOR sollte „100% GPU“ zeigen). |
---
## 16. Tipps und häufige Fragen
**Wie bekomme ich die besten Ergebnisse?**
Mit einem guten Glossar. Das Modell kennt viele Namen nicht oder schreibt sie
falsch; feste Ersetzungen für die häufigsten Hörfehler und Begriffe für die
wichtigsten Namen bringen mehr als jede andere Einstellung.
**Ändert das Modell den Inhalt?**
Es soll nicht, tut es aber gelegentlich (z. B. „Professor“ → „Professorin“).
Deshalb gibt es die Liste „Zu prüfen“. Für eine Veröffentlichung sollte sie immer
durchgesehen werden.
**Warum setzt das Modell kaum `[prüfen: …]`-Marken?**
`qwen3:32b` läuft hier ohne „Denkmodus“, um schnell zu sein, und ist sich dabei oft
zu sicher. Verlässlicher sind Glossar und Änderungsbericht.
**Kann ich den Rohtext vor der Korrektur von Hand verbessern?**
Ja. Rohtext mit `extract_text.py` oder `vtt2txt.py` erzeugen, bearbeiten, dann mit
`-i` korrigieren. Für die Zeitauswahl braucht es aber die `.vtt`-Datei.
**Wie lange dauert ein Lauf?**
Mit `qwen3:32b` auf einer RTX 3090 etwa 6–8 Minuten pro Stunde Rede. Ein zweiter
Lauf ohne Änderungen dauert Sekunden; nach Glossar-Änderungen werden nur die
betroffenen Teile neu berechnet (siehe [Abschnitt 9](#9-schritt-5-nachbessern-und-erneut-laufen-lassen)).
**Kann ich mehrere Videos nacheinander bearbeiten?**
Ja, z. B. in einer Schleife:
```bash
for url in 'https://www.youtube.com/watch?v=AAA' 'https://www.youtube.com/watch?v=BBB'; do
