docs: ausführliche BEDIENUNGSANLEITUNG.md, README auf aktuellem Stand

Die Bedienungsanleitung führt von der Einrichtung über Rohtext, Glossar, Korrektur und Prüfung des Berichts („Zu prüfen“) bis zum Nachbessern; dazu Zeitauswahl, englische Beiträge, Dateien, Fortsetzen, Fehlermeldungen mit Lösungen und eine Kurzreferenz aller Programme. README: Verweis auf die Anleitung, zerrissene Optionstabelle von abschrift_korrigieren.py repariert, Ablauf mit Vorprüfung und Blöcken, Hinweis „05:00 = 5 Stunden“, Tests und Einstellungen ergänzt. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-11 21:44:40 +02:00 · 2026-10-11 21:44:40 +02:00 · 1e3c813137
commit 1e3c813137
parent 3da372a941
2 changed files with 862 additions and 14 deletions
--- a/BEDIENUNGSANLEITUNG.md
+++ b/BEDIENUNGSANLEITUNG.md
@ -0,0 +1,811 @@
+# Bedienungsanleitung
+
+Diese Anleitung führt Schritt für Schritt von einem YouTube-Video (oder einer
+Untertiteldatei) zu einer sauberen, lesbaren Abschrift. Sie erklärt, was die
+Programme tun, wie man ihre Ergebnisse prüft und was bei Fehlermeldungen zu tun
+ist. Eine knappe technische Übersicht steht in der [README](README.md).
+
+## Inhalt
+
+1. [Wozu die Programme dienen](#1-wozu-die-programme-dienen)
+2. [Einrichtung (einmalig)](#2-einrichtung-einmalig)
+3. [Schnellstart](#3-schnellstart)
+4. [Der Arbeitsablauf im Überblick](#4-der-arbeitsablauf-im-überblick)
+5. [Schritt 1: Rohtext holen](#5-schritt-1-rohtext-holen)
+6. [Schritt 2: Glossar anlegen](#6-schritt-2-glossar-anlegen)
+7. [Schritt 3: Korrigieren](#7-schritt-3-korrigieren)
+8. [Schritt 4: Ergebnis prüfen](#8-schritt-4-ergebnis-prüfen)
+9. [Schritt 5: Nachbessern und erneut laufen lassen](#9-schritt-5-nachbessern-und-erneut-laufen-lassen)
+10. [Nur Ausschnitte bearbeiten (Zeitauswahl)](#10-nur-ausschnitte-bearbeiten-zeitauswahl)
+11. [Englische Beiträge](#11-englische-beiträge)
+12. [Dateien, die entstehen](#12-dateien-die-entstehen)
+13. [Zwischenstände, Abbruch und Fortsetzen](#13-zwischenstände-abbruch-und-fortsetzen)
+14. [Ein anderes Sprachmodell verwenden](#14-ein-anderes-sprachmodell-verwenden)
+15. [Fehlermeldungen und Lösungen](#15-fehlermeldungen-und-lösungen)
+16. [Tipps und häufige Fragen](#16-tipps-und-häufige-fragen)
+17. [Kurzreferenz aller Befehle](#17-kurzreferenz-aller-befehle)
+
+---
+
+## 1. Wozu die Programme dienen
+
+YouTube erzeugt für viele Videos automatische Untertitel. Diese enthalten den
+gesprochenen Text, aber:
+
+- ohne oder mit falschen Satzzeichen und ohne Groß-/Kleinschreibung nach Regeln,
+- mit Hörfehlern der Spracherkennung, besonders bei Namen („Willly Brand“ statt
+  „Willy Brandt“, „Kremmel“ statt „Kreml“),
+- ohne Absätze, in kurzen Zeilen und mit vielen Wiederholungen (rollendes Fenster).
+
+Die Programme machen daraus eine **möglichst wortgetreue, gut lesbare Abschrift**.
+Die Arbeit übernimmt ein Sprachmodell, das **lokal auf dem eigenen Rechner** läuft
+(über Ollama); es werden keine Texte an fremde Dienste geschickt. Ausnahme: Der
+Download der Untertitel von YouTube.
+
+Das Modell soll **nicht zusammenfassen und nicht umformulieren**. Es korrigiert nur
+Rechtschreibung, Satzzeichen und erkennbare Hörfehler und gliedert in Absätze. Weil
+Sprachmodelle trotzdem gelegentlich eigenmächtig Wörter ändern, schreibt jeder Lauf
+einen **Änderungsbericht**, der solche Stellen gezielt zur Prüfung vorlegt.
+
+Die Werkzeuge im Überblick:
+
+| Programm | Wofür |
+|---|---|
+| `abschrift_korrigieren.py` | **Hauptprogramm:** Abschrift korrigieren, auf Wunsch direkt von der YouTube-URL |
+| `extract_text.py` | YouTube-URL → Rohtext (Textdatei), ohne Korrektur |
+| `yt_untertitel.py` | YouTube-URL → Untertiteldatei (`.vtt`) |
+| `vtt2txt.py` | Untertiteldatei (`.vtt`) → Rohtext |
+| `glossar_vorschlag.py` | Entwurf für ein Glossar (vermutete Hörfehler bei Namen und Begriffen) |
+| `aenderungen.py` | Änderungsbericht für vorhandene Dateien erstellen |
+
+Für den Normalfall braucht man nur `abschrift_korrigieren.py`, für bessere
+Ergebnisse zusätzlich ein Glossar.
+
+---
+
+## 2. Einrichtung (einmalig)
+
+### 2.1 Was benötigt wird
+
+| Bestandteil | Wozu | Installation (Debian/Ubuntu) |
+|---|---|---|
+| Python 3.9 oder neuer | führt die Programme aus | meist vorhanden; `python3 --version` |
+| yt-dlp | lädt Untertitel von YouTube | `pip install yt-dlp` (oder `pipx install yt-dlp`) |
+| Ollama | führt das Sprachmodell aus | siehe <https://ollama.com/download> |
+| Modell `qwen3:32b` | das Sprachmodell | `ollama pull qwen3:32b` |
+| Wortliste `wngerman` | für den Änderungsbericht (erkennt ersetzte echte Wörter) | `sudo apt install wngerman` |
+| Wortliste `wamerican` | dasselbe für englische Beiträge | `sudo apt install wamerican` |
+
+Weitere Python-Pakete sind nicht nötig. Ohne yt-dlp lassen sich nur vorhandene
+`.vtt`- oder `.txt`-Dateien bearbeiten. Ohne Wortliste läuft alles, nur der
+Änderungsbericht erkennt dann ersetzte gültige Wörter nicht (es erscheint ein
+Hinweis).
+
+### 2.2 Grafikkarte
+
+Für eine brauchbare Geschwindigkeit muss das Modell vollständig in den
+Grafikspeicher passen. `qwen3:32b` braucht dafür rund **24 GB** (z. B. eine
+RTX 3090), wenn Ollama nur eine Anfrage gleichzeitig bearbeitet:
+
+```bash
+# in der Ollama-Dienstkonfiguration (sudo systemctl edit ollama):
+[Service]
+Environment="OLLAMA_NUM_PARALLEL=1"
+```
+
+Mit `OLLAMA_NUM_PARALLEL=4` landet ein Drittel des Modells auf der CPU, und ein
+Lauf dauert etwa zwölfmal so lange. Mit weniger Grafikspeicher hilft ein kleineres
+Modell (siehe [Abschnitt 14](#14-ein-anderes-sprachmodell-verwenden)), auf Kosten
+der Qualität.
+
+### 2.3 Prüfen, ob alles bereit ist
+
+Im Programmordner:
+
+```bash
+cd youtube_abschrift_korrigieren
+ollama list | grep qwen3:32b        # Modell vorhanden?
+yt-dlp --version                    # yt-dlp vorhanden?
+./abschrift_korrigieren.py --help   # Programm startet?
+```
+
+`abschrift_korrigieren.py` und `glossar_vorschlag.py` prüfen beim Start selbst, ob
+Ollama läuft und das Modell installiert ist, und brechen sonst mit einem Hinweis
+ab, bevor irgendetwas heruntergeladen wird.
+
+Lassen sich die Programme nicht mit `./…` starten („Keine Berechtigung“), einmalig
+ausführbar machen: `chmod +x *.py`. Alternativ immer `python3 programm.py …`
+aufrufen.
+
+---
+
+## 3. Schnellstart
+
+Ein YouTube-Video in einem Befehl korrigieren:
+
+```bash
+./abschrift_korrigieren.py -u 'https://www.youtube.com/watch?v=rm6lADgf6GQ'
+```
+
+Die URL in **einfache Anführungszeichen** setzen, sonst stört das `&` in manchen
+URLs die Shell.
+
+Das Programm
+
+1. lädt die Untertitel in der Originalsprache des Videos,
+2. speichert den Rohtext, z. B. `GGBLahnstein_Prof_Gabriele_Krone-Schmalz_Respekt_geht_anders_2026-07-30.txt`,
+3. korrigiert ihn abschnittsweise und gliedert ihn in Absätze,
+4. schreibt das Ergebnis nach `…_2026-07-30.korrigiert.txt`
+5. und den Änderungsbericht nach `…_2026-07-30.aenderungen.html`.
+
+Eine einstündige Rede braucht mit `qwen3:32b` auf einer RTX 3090 etwa 6–8
+Minuten. Danach den Bericht im Browser öffnen und die Liste **„Zu prüfen“**
+durchgehen (siehe [Abschnitt 8](#8-schritt-4-ergebnis-prüfen)).
+
+Mit eigenem Dateinamen:
+
+```bash
+./abschrift_korrigieren.py -u 'https://www.youtube.com/watch?v=rm6lADgf6GQ' -o lahnstein.korrigiert.txt
+# → lahnstein.korrigiert.txt, lahnstein.txt (Rohtext), lahnstein.aenderungen.html
+```
+
+---
+
+## 4. Der Arbeitsablauf im Überblick
+
+Für einen einzelnen Beitrag genügt der Schnellstart. Für gute Ergebnisse,
+besonders bei vielen Namen, lohnt dieser Ablauf:
+
+```text
+YouTube-URL
+   │  Schritt 1: extract_text.py            → rede.txt (Rohtext)
+   ▼
+Rohtext ansehen
+   │  Schritt 2: glossar_vorschlag.py       → rede.glossar.entwurf.txt
+   │             prüfen, übernehmen          → rede.glossar.txt
+   ▼
+   │  Schritt 3: abschrift_korrigieren.py   → rede.korrigiert.txt
+   │                                          rede.aenderungen.html
+   ▼
+   │  Schritt 4: Bericht prüfen („Zu prüfen“)
+   ▼
+   │  Schritt 5: Glossar ergänzen, erneut laufen lassen
+   ▼                (nur Geändertes wird neu berechnet)
+fertige Abschrift
+```
+
+---
+
+## 5. Schritt 1: Rohtext holen
+
+### 5.1 Von YouTube: `extract_text.py`
+
+```bash
+./extract_text.py -u 'https://www.youtube.com/watch?v=rm6lADgf6GQ' -o rede.txt
+```
+
+Das Programm zeigt Titel, gewählte Untertitelspur und Ziel an:
+
+```text
+Video: Prof. Gabriele Krone-Schmalz – Respekt geht anders – …
+Lade automatische Untertitel „de-orig“ …
+```
+
+Ohne `-o` entsteht ein Name aus Kanal, Titel und Datum (siehe
+[Abschnitt 12.2](#122-standard-dateinamen)).
+
+**Welche Untertitel werden genommen?**
+
+1. Manuell erstellte Untertitel in der gewünschten Sprache, sonst
+2. automatische Untertitel in der **Originalsprache** des Videos (`de-orig`).
+
+Ohne `-l` gilt die Sprache des Original-Audios. Automatisch *übersetzte*
+Untertitel werden nie genommen, ebenso wenig die Spuren KI-synchronisierter
+Tonspuren. Gibt es keine passende Spur, nennt das Programm die vorhandenen
+Sprachen.
+
+**Lesbarer Fließtext:** Mit `-f` wird der Rohtext auf 80 Zeichen umbrochen statt
+in kurzen Untertitelzeilen gespeichert. Das ist angenehmer zum Lesen; beides
+versteht `abschrift_korrigieren.py`.
+
+### 5.2 Mit Untertiteldatei: `yt_untertitel.py` und `vtt2txt.py`
+
+Soll die Original-Untertiteldatei (`.vtt`, mit Zeitstempeln) erhalten bleiben:
+
+```bash
+./yt_untertitel.py -u 'https://www.youtube.com/watch?v=rm6lADgf6GQ' -n Lahnstein -d testdaten
+# → testdaten/Lahnstein.de-orig.vtt
+./vtt2txt.py -i testdaten/Lahnstein.de-orig.vtt
+# → testdaten/Lahnstein.de-orig.txt
+```
+
+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
+  (`Willly Brands => Willy Brandts` vor `Willly Brand => Willy Brandt`).
+- Das Programm meldet, wie oft jede Ersetzung gegriffen hat, und listet am Ende
+  die Ersetzungen ohne Treffer. Bei einem Glossar für genau diesen Beitrag deutet
+  „ohne Treffer“ auf einen Tippfehler.
+
+### 6.2 Mehrere Glossare kombinieren
+
+Bewährt hat sich ein **gemeinsames Glossar** pro Redner oder Kanal (wiederkehrende
+Namen und Hörfehler) plus eines **je Beitrag**:
+
+```bash
+./abschrift_korrigieren.py -i rede.txt -g krone-schmalz.glossar.txt -g rede.glossar.txt
+```
+
+Das gemeinsame Glossar zuerst angeben, damit seine Ersetzungen zuerst greifen.
+Im Programmordner liegen Beispiele: `krone-schmalz.glossar.txt` (gemeinsam),
+`ramstein.glossar.txt`, `magdeburg.glossar.txt`, `lahnstein.glossar.txt`
+(je eine Rede) und `iamfabian.glossar.txt` (Kanal über KI-Coding-Tools).
+
+### 6.3 Entwurf vom Modell: `glossar_vorschlag.py`
+
+Statt den ganzen Rohtext zu lesen, kann das Modell einen ersten Entwurf liefern:
+
+```bash
+./glossar_vorschlag.py -i rede.txt -g krone-schmalz.glossar.txt
+# → rede.glossar.entwurf.txt
+```
+
+Das Modell sucht abschnittsweise vermutete Hörfehler: Namen, Orte, Fremdwörter,
+Fachbegriffe, falsch zusammen- oder getrennt geschriebene Wörter. Behalten werden
+nur Funde, die wörtlich im Rohtext stehen. Einträge der mit `-g` angegebenen
+Glossare werden nicht erneut vorgeschlagen.
+
+Der Entwurf sieht so aus:
+
+```text
+# Glossar-ENTWURF für rede.txt (glossar_vorschlag.py, Modell qwen3:32b)
+# Alle Einträge sind auskommentiert. …
+
+# --- Vom Modell vermutete Hörfehler, laut Modell sicher ---
+# ? Hostelchick => Horst Teltschik
+# ? Kremmel => Kreml
+
+# --- Vom Modell vermutete Hörfehler, laut Modell unsicher ---
+# ? Deckmäntelchen => Deckmäntel
+```
+
+**Alle Einträge sind auskommentiert** (`# ? `), auch die „sicheren“: Das Modell
+irrt sich oft (im Beispiel ist „Deckmäntelchen“ richtig). Eine falsche feste
+Ersetzung verdirbt den Text unbemerkt. Deshalb:
+
+1. Jeden Eintrag prüfen, im Zweifel im Rohtext oder Video nachsehen.
+2. Brauchbare Zeilen ohne `# ? ` ins Glossar des Beitrags (oder ins gemeinsame)
+   kopieren.
+3. Unsichere Namen lieber als **Begriff** (ohne `=>`) aufnehmen.
+
+Nach einem Korrekturlauf kann der Entwurf zusätzlich die Wörter auflisten, die das
+Modell geändert hat. Das zeigt Hörfehler, die man als feste Ersetzung absichern
+möchte, und Fehlgriffe des Modells:
+
+```bash
+./glossar_vorschlag.py -i rede.txt -k rede.korrigiert.txt -g krone-schmalz.glossar.txt -g rede.glossar.txt
+```
+
+Diese Einträge stehen in einem eigenen Abschnitt mit ihrer Anzahl, z. B.
+`# ? vorne herein => vornherein   (2×)`; die Anzahl in Klammern beim Übernehmen
+entfernen.
+
+---
+
+## 7. Schritt 3: Korrigieren
+
+```bash
+./abschrift_korrigieren.py -i rede.txt -g krone-schmalz.glossar.txt -g rede.glossar.txt
+```
+
+Statt `-i rede.txt` geht auch `-i rede.de.vtt` (Untertiteldatei) oder
+`-u URL` (direkt von YouTube).
+
+### 7.1 Was das Programm tut
+
+1. **Prüfen:** Läuft Ollama, ist das Modell installiert?
+2. **Fließtext:** Die Zeilenumbrüche der Untertitel werden entfernt.
+3. **Feste Ersetzungen** aus den Glossaren werden angewendet.
+4. **Korrektur:** Der Text wird in Abschnitte von etwa 1200 Wörtern geteilt, immer
+   am Satzende, und Abschnitt für Abschnitt korrigiert. Abkürzungen wie „z. B.“,
+   „Dr.“, „bzw.“ und Ordnungszahlen wie „2. Weltkrieg“ gelten dabei nicht als
+   Satzende.
+5. **Wortzahl-Prüfung:** Weicht die Wortzahl eines Abschnitts um mehr als 5 % ab,
+   warnt das Programm (das Modell könnte etwas ausgelassen oder ergänzt haben).
+6. **Absätze:** Das Modell nennt die Sätze, mit denen ein neuer Absatz beginnt; der
+   Text selbst bleibt dabei unverändert. Absätze über 10 Sätze werden nochmals
+   geteilt. Absätze unter 3 Sätzen werden mit einem Nachbarn verbunden; passen
+   beide, entscheidet das Modell nach dem Inhalt, ob der kurze Absatz den
+   vorherigen Gedanken abschließt oder den folgenden einleitet.
+7. **Änderungsbericht:** Rohtext und Ergebnis werden Wort für Wort verglichen.
+
+### 7.2 Die Ausgabe im Terminal
+
+Ein gekürztes Beispiel mit Erläuterungen:
+
+```text
+Modell: qwen3:32b
+Sprache des Beitrags: de
+Glossar krone-schmalz.glossar.txt: 7 Begriffe, 36 feste Ersetzungen
+Glossar ramstein.glossar.txt: 2 Begriffe, 15 feste Ersetzungen
+  Ersetzt 2× „Willly Brand“ → „Willy Brandt“          ← feste Ersetzungen mit Treffern
+  Ersetzt 6× „Rammstein“ → „Ramstein“
+  13 Ersetzung(en) ohne Treffer: „Hostelchik“, …      ← bei gemeinsamen Glossaren normal
+Bearbeite Abschnitt 1/5 …
+  812/1203 Wörter, 61 s                               ← Fortschritt (läuft live mit)
+  fertig nach 88 s (25.2 Tokens/s)
+…
+Gliedere Absätze 1/3 …
+  Teile langen Absatz (Sätze 18–34) …
+  39 kurze Absätze verbunden (30 mit dem vorherigen, 9 mit dem folgenden)
+  310 Sätze in 56 Absätzen (kürzester: 3, längster: 10 Sätze)
+Fertig: rede.korrigiert.txt
+Änderungen gegenüber dem Rohtext: 82
+  5× „Rammstein“ → „Ramstein“
+  …
+Zu prüfen: 19 Stellen                                 ← diese Stellen ansehen!
+  gültiges Wort ersetzt: „in“ → „dass“
+  stark verändert: „OSola“ → „Ursula“
+  …
+Bericht: rede.aenderungen.html
+
+19 Stelle(n) zu prüfen, siehe rede.aenderungen.html
+```
+
+Eine Warnung zur Wortzahl sieht so aus und wird am Ende wiederholt:
+
+```text
+WARNUNG: Abschnitt 3: 1180 → 1090 Wörter (8% Abweichung), auf Auslassungen/Ergänzungen prüfen: rede.korrigiert.parts/part003-….txt
+```
+
+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
+Kriminalität“ → „Clankriminalität“) und Wörter, die im Glossar stehen.
+
+**So arbeitet man die Liste ab:**
+
+1. Für jede Zeile den Zusammenhang lesen.
+2. Ist die Änderung richtig (oft bei Grammatik: „das“ → „dass“, „sehe“ → „sähe“),
+   nichts tun.
+3. Ist sie falsch, im korrigierten Text zurückändern. Tritt der Fehler öfter auf
+   oder geht es um einen Namen, besser das Glossar ergänzen (nächster Schritt).
+4. Bei „gestrichen“ prüfen, ob wirklich etwas fehlt: Oft entfernt das Modell
+   versprochene Wortanfänge oder Dopplungen, manchmal aber einen ganzen Satzteil.
+
+Die Liste findet die meisten eigenmächtigen Änderungen, aber nicht alle: Ersetzt
+das Modell ein falsch erkanntes Wort durch ein *ähnliches, aber falsches*, fällt
+das nicht auf. Stichproben im Text bleiben sinnvoll.
+
+### 8.3 Bericht für vorhandene Dateien: `aenderungen.py`
+
+Wurde der korrigierte Text von Hand nachbearbeitet oder mit `--kein-bericht`
+erstellt, lässt sich der Bericht jederzeit neu erzeugen. Mit denselben Glossaren
+wie bei der Korrektur, damit deren Ersetzungen nicht als verdächtig gelten:
+
+```bash
+./aenderungen.py -a rede.txt -b rede.korrigiert.txt -g krone-schmalz.glossar.txt -g rede.glossar.txt
+# → rede.aenderungen.html
+./aenderungen.py -a talk.txt -b talk.korrigiert.txt -l en      # englischer Beitrag
+```
+
+---
+
+## 9. Schritt 5: Nachbessern und erneut laufen lassen
+
+Funde aus dem Bericht ins Glossar übernehmen und dieselbe Befehlszeile noch einmal
+ausführen. Das Programm hat alle Zwischenergebnisse gespeichert und berechnet nur
+neu, was sich geändert hat:
+
+- **Neue feste Ersetzung:** Neu korrigiert wird der Abschnitt mit dem ersten
+  Treffer. Ändert die Ersetzung die Zahl der Wörter (z. B. „Horstelt“ → „Horst
+  Teltschik“), verschieben sich die folgenden Abschnittsgrenzen, und auch die
+  späteren Abschnitte werden neu korrigiert.
+- **Neuer Begriff** (ohne `=>`): Begriffe stehen in der Anweisung an das Modell,
+  deshalb wird der ganze Text neu korrigiert.
+- Die Absatzgliederung wird für geänderte Textstellen ebenfalls neu bestimmt; das
+  geht schnell.
+
+Von Hand nachbearbeitete `*.korrigiert.txt` werden bei einem erneuten Lauf
+**überschrieben**. Handarbeit deshalb erst ganz am Ende machen oder die Datei vorher
+unter anderem Namen sichern.
+
+---
+
+## 10. Nur Ausschnitte bearbeiten (Zeitauswahl)
+
+Mit `-z` wird nur ein Teil des Videos bearbeitet. Das geht mit `-u` (YouTube) und
+mit `.vtt`-Dateien, nicht mit reinem Text (der hat keine Zeitstempel). Dieselbe
+Option kennen `extract_text.py` und `vtt2txt.py`.
+
+### 10.1 Zeitangaben
+
+| Angabe | Bedeutung |
+|---|---|
+| `00:05:10` | Stunden:Minuten:Sekunden (auch `0:5:10`) |
+| `00:20` | **Stunden:Minuten**, also Minute 20 |
+| `25` | Minute 25 |
+
+> **Vorsicht:** `05:00` bedeutet 5 Stunden, nicht 5 Minuten. Für „5 Minuten“
+> `00:05` oder `5` schreiben, für 5 Minuten 30 Sekunden `00:05:30`.
+
+### 10.2 Bereiche
+
+| Aufruf | Bearbeitet |
+|---|---|
+| `-z 00:05-00:06` | Minute 5 bis Minute 6 |
+| `-z 0:03:17-0:05:25` | 3:17 bis 5:25 |
+| `-z 00:05:10` | ab 5:10 bis zum Ende |
+| `-z 0-00:20` oder `-z -00:20` | vom Anfang bis Minute 20 |
+| `-z 00:05-00:06 00:10-00:12 00:25` | Minute 5–6, Minute 10–12 und alles ab Minute 25 |
+
+Mehrere Bereiche durch Leerzeichen trennen. Sie dürfen sich nicht überschneiden
+und werden nach der Zeit sortiert. Beispiel:
+
+```bash
+./abschrift_korrigieren.py -u 'https://www.youtube.com/watch?v=…' -z 00:05-00:06 00:25
+```
+
+### 10.3 Was dabei herauskommt
+
+Alle Bereiche landen in **einer** Datei, jeder mit einer Überschrift, die seine
+tatsächlichen Zeiten nennt:
+
+```text
+[00:04:57 - 00:06:04]
+Ihr seht, es gibt keinen einzigen Dialog …
+
+[00:09:58 - 00:12:03]
+Also, wenn ihr Programme baut mit Claude Code, …
+```
+
+- Angeschnittene Sätze werden an beiden Enden vollständig aufgenommen, höchstens
+  30 Sekunden über den Bereich hinaus. Mit `--exakt` wird genau an den Zeiten
+  geschnitten, auch mitten im Satz.
+- Jeder Bereich wird für sich korrigiert und gegliedert. Die Überschriften sieht
+  das Modell nicht; es wird angewiesen, an den Rändern nichts zu ergänzen.
+- Der Dateiname enthält die Bereiche, z. B.
+  `…_2026-10-10_00-05-00_bis_00-06-00+ab_00-25-00.korrigiert.txt`.
+- Bereiche ohne Untertitel werden mit einem Hinweis übersprungen.
+
+---
+
+## 11. Englische Beiträge
+
+Mit `-u` erkennt das Programm die Sprache des Videos selbst. Bei Dateien die
+Sprache angeben:
+
+```bash
+./abschrift_korrigieren.py -i talk.txt -l en
+./abschrift_korrigieren.py -u 'https://www.youtube.com/watch?v=0LmCveTM788'   # Sprache automatisch
+```
+
+Für Englisch gibt es eigene Anweisungen an das Modell. Unterschiede:
+
+- Prüfmarken heißen `[check: …]` statt `[prüfen: …]`.
+- Die Sprecherwechsel-Marken `>>` der YouTube-Untertitel werden entfernt.
+- Der Änderungsbericht nutzt die englische Wortliste (`wamerican`).
+
+Unterstützt sind Deutsch (`de`) und Englisch (`en`), auch mit Region (`en-US`).
+Andere Sprachen lehnt das Programm mit einer Meldung ab.
+
+---
+
+## 12. Dateien, die entstehen
+
+### 12.1 Übersicht
+
+Beispiel für `-i rede.txt` bzw. `-o rede.korrigiert.txt`:
+
+| Datei | Inhalt | Wird überschrieben? |
+|---|---|---|
+| `rede.txt` | Rohtext (bei `-u` automatisch gespeichert) | nie, wenn sie schon mit anderem Inhalt existiert (dann Warnung) |
+| `rede.korrigiert.txt` | korrigierte Abschrift | ja, bei jedem Lauf |
+| `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
+  berechnet.
+
+---
+
+## 14. Ein anderes Sprachmodell verwenden
+
+```bash
+ollama pull qwen3:14b
+./abschrift_korrigieren.py -i rede.txt -m qwen3:14b
+```
+
+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. |
+| `-z/--zeitraeume: …` | Zeitangabe ungültig oder Bereiche überschneiden sich, siehe [Abschnitt 10](#10-nur-ausschnitte-bearbeiten-zeitauswahl). |
+| `Die Eingabedatei enthält im gewählten Zeitraum keinen Text.` | Im Bereich gibt es keine Untertitel. Zeiten prüfen (`05:00` = 5 Stunden!). |
+| `Die Eingabedatei ist leer.` | Datei prüfen. |
+| `Ausgabedatei darf nicht die Eingabedatei sein.` | Mit `-o` einen anderen Namen wählen. |
+| `Glossar nicht gefunden: …` | Pfad bei `-g` prüfen. |
+| `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
+    ./abschrift_korrigieren.py -u "$url" -g krone-schmalz.glossar.txt
+done
+```
+
+**Wo sind die Absätze?**
+In `*.korrigiert.txt` trennt eine Leerzeile die Absätze. Viele Textprogramme
+übernehmen das beim Einfügen direkt.
+
+**Kann ich das Ergebnis weiterverarbeiten (Word, LibreOffice)?**
+Die `.korrigiert.txt` ist reiner UTF-8-Text und lässt sich überall öffnen oder
+einfügen.
+
+---
+
+## 17. Kurzreferenz aller Befehle
+
+### `abschrift_korrigieren.py`
+
+| Option | Bedeutung |
+|---|---|
+| `-i DATEI` | Eingabe: Rohtext (`.txt`) oder Untertitel (`.vtt`) |
+| `-u URL` | statt `-i`: YouTube-Video laden und korrigieren |
+| `-o DATEI` | Ausgabedatei (Standard: `<Eingabe>.korrigiert.txt` bzw. `<Kanal>_<Titel>_<Datum>.korrigiert.txt`) |
+| `-g DATEI` | Glossar, mehrfach möglich (Reihenfolge zählt) |
+| `-l SPRACHE` | `de` oder `en` (Standard: `de`, mit `-u` die Originalsprache) |
+| `-m MODELL` | Ollama-Modell (Standard: `qwen3:32b`) |
+| `-z BEREICH …` | nur diese Zeitbereiche (mit `.vtt` oder `-u`) |
+| `--exakt` | genau an den Zeiten schneiden |
+| `--kein-bericht` | keinen Änderungsbericht schreiben |
+
+### `extract_text.py`
+
+| Option | Bedeutung |
+|---|---|
+| `-u URL` | YouTube-URL (Pflicht) |
+| `-o DATEI` | Ausgabedatei (Standard: `<Kanal>_<Titel>_<Datum>.txt`) |
+| `-l SPRACHE` | Sprache der Untertitel (Standard: Originalsprache) |
+| `-f` | Fließtext mit 80 Zeichen pro Zeile |
+| `-z BEREICH …`, `--exakt` | Zeitauswahl wie oben |
+
+### `yt_untertitel.py`
+
+| Option | Bedeutung |
+|---|---|
+| `-u URL` | YouTube-URL (Pflicht) |
+| `-n NAME` | Dateiname ohne Endung (Standard: `<Kanal>_<Titel>_<Datum>`) |
+| `-l SPRACHE` | Sprache (Standard: `de`) |
+| `-d VERZEICHNIS` | Zielverzeichnis (Standard: aktuelles) |
+
+### `vtt2txt.py`
+
+| Option | Bedeutung |
+|---|---|
+| `-i DATEI …` | eine oder mehrere `.vtt`-Dateien oder Muster (`"*.vtt"`) |
+| `-o ZIEL` | Ausgabedatei (bei einer Eingabe) oder Verzeichnis |
+| `-z BEREICH …`, `--exakt` | Zeitauswahl wie oben |
+
+### `glossar_vorschlag.py`
+
+| Option | Bedeutung |
+|---|---|
+| `-i DATEI` | Rohtext (`.txt` oder `.vtt`, Pflicht) |
+| `-k DATEI` | korrigierter Text eines Laufs (optional) |
+| `-g DATEI` | vorhandene Glossare, mehrfach möglich |
+| `-o DATEI` | Entwurf (Standard: `<Eingabe>.glossar.entwurf.txt`) |
+| `-m MODELL` | Ollama-Modell |
+
+### `aenderungen.py`
+
+| Option | Bedeutung |
+|---|---|
+| `-a DATEI` | Rohtext (`.txt` oder `.vtt`, Pflicht) |
+| `-b DATEI` | korrigierter Text (Pflicht) |
+| `-o DATEI` | HTML-Bericht (Standard: `<Name>.aenderungen.html`) |
+| `-g DATEI` | Glossare der Korrektur, mehrfach möglich |
+| `-l SPRACHE` | Sprache für die Wortliste (Standard: `de`) |
+
+Jedes Programm zeigt mit `--help` seine Optionen.
--- a/README.md
+++ b/README.md
@ -6,6 +6,11 @@ mit einem lokalen Sprachmodell über Ollama: Rechtschreibung, Satzzeichen,
 Hörfehler, Absätze – möglichst wortgetreu, ohne Zusammenfassung oder Glättung.
 Das Hauptprogramm ist `abschrift_korrigieren.py`.

+Eine ausführliche Anleitung für die Benutzung Schritt für Schritt, mit
+Arbeitsablauf, Glossar-Pflege, Prüfung der Ergebnisse und Fehlerbehebung, steht in
+der [BEDIENUNGSANLEITUNG.md](BEDIENUNGSANLEITUNG.md). Diese README ist die knappe
+technische Übersicht.
+
 Die Werkzeuge sind einzeln oder hintereinander nutzbar:

 | Skript | Aufgabe |
@ -176,6 +181,9 @@ Gilt gleich für `vtt2txt.py`, `extract_text.py` und `abschrift_korrigieren.py`.
 | `00:20` | Stunden:Minuten, also Minute 20 |
 | `25` | Minute 25 |

+Achtung: Zwei Zahlen sind Stunden:Minuten, `05:00` ist also Stunde 5, nicht
+Minute 5 (dafür `00:05` oder `5`).
+
 | Aufruf | Text |
 |---|---|
 | `-z 00:05:10` | ab 5:10 bis zum Ende des Videos |
@ -236,6 +244,9 @@ werden trotzdem umgewandelt; der Exit-Code ist dann 1.
 | `-o`, `--output` | Ausgabedatei; Standard: `<Eingabe ohne Endung>.korrigiert.txt` neben der Eingabe, mit `-u` `<Kanal>_<Titel>_<Datum>.korrigiert.txt`; mit `-z` zusätzlich die Bereiche im Namen |
 | `-z`, `--zeitraeume` | nur diese Bereiche korrigieren, siehe [Zeitauswahl](#zeitauswahl--z); nur mit `.vtt`-Eingabe oder `-u`, da reiner Text keine Zeitstempel hat |
 | `--exakt` | genau an den Zeiten schneiden statt an Satzgrenzen |
+| `-g`, `--glossar` | Glossar mit festen Ersetzungen und Schreibweisen; mehrfach angeben zum Kombinieren (Ersetzungen in Reihenfolge der Angabe) |
+| `-m`, `--model` | Ollama-Modell; Standard: `qwen3:32b` (Konstante `MODEL`) |
+| `--kein-bericht` | keinen Änderungsbericht schreiben |

 Mit Zeitauswahl wird jeder Bereich als eigener Block korrigiert und gegliedert;
 die Überschriften `[00:04:57 - 00:06:04]` bekommt das Modell nicht zu sehen, sie
@ -243,13 +254,13 @@ stehen unverändert als eigene Zeilen im Ergebnis. Zusätzlich weist der Prompt
 Modell an, an den Rändern der Ausschnitte nichts zu ergänzen. Eine Rohabschrift
 (`.txt`) mit solchen Überschriften, etwa von `vtt2txt.py -z`, wird ebenso in
 Blöcken korrigiert.
-| `-g`, `--glossar` | Glossar mit festen Ersetzungen und Schreibweisen; mehrfach angeben zum Kombinieren (Ersetzungen in Reihenfolge der Angabe) |
-| `-m`, `--model` | Ollama-Modell; Standard: `qwen3:32b` (Konstante `MODEL`) |
-| `--kein-bericht` | keinen Änderungsbericht schreiben |

 ## Ablauf

-1. **Fließtext:** Untertitel-Zeilenumbrüche werden entfernt.
+0. **Vorprüfung:** Läuft Ollama, ist das Modell installiert? Sonst Abbruch mit
+   Hinweis, noch vor jedem Download.
+1. **Fließtext:** Untertitel-Zeilenumbrüche werden entfernt. Zeit-Überschriften
+   (`-z`) teilen den Text in Blöcke, die einzeln bearbeitet werden.
 2. **Feste Ersetzungen** aus dem Glossar (`falsch => richtig`) werden im Rohtext
   angewendet, bevor das Modell ihn sieht.
 3. **Korrektur:** Der Text wird in Abschnitte von ca. 1200 Wörtern geteilt (immer
@ -263,9 +274,9 @@ Blöcken korrigiert.
   geteilt, Absätze unter 3 Sätzen mit einem Nachbarn verbunden. Passt der kurze
   Absatz an beide Nachbarn, entscheidet das Modell nach dem Inhalt, ob er den
   vorherigen Gedanken abschließt oder den folgenden einleitet.
-
 6. **Änderungsbericht:** Rohtext (vor dem Glossar) und Ergebnis werden Wort für Wort
-   verglichen, siehe unten.
+   verglichen; eigenmächtige Änderungen des Modells kommen in die Liste
+   „Zu prüfen“, siehe unten.

 Zweifelhafte Stellen markiert das Modell als `Lesart [prüfen: Originalwortlaut]`,
 in englischen Reden als `reading [check: original wording]`.
@ -412,10 +423,14 @@ Ein Lauf dauert mit `qwen3:32b` vollständig auf einer RTX 3090 etwa 6 Minuten.
 python3 -m pytest
 ```

-Die Tests brauchen kein Ollama: Modellaufrufe werden durch Fakes ersetzt. Geprüft
-werden Abschnittsbildung, Glossar (inkl. „jede Ersetzung im Glossar einer Rede trifft
-diese Rede, jede im gemeinsamen Glossar trifft mindestens eine“), Streaming-Auswertung, Absatzgliederung (Text bleibt
-unverändert, 3–10 Sätze), Zwischenspeicher/Fortsetzen und die Kommandozeile.
+Die Tests (291) brauchen weder Ollama noch Netz: Modellaufrufe und `yt-dlp` werden
+durch Fakes ersetzt. `tests/test_abschrift_korrigieren.py` prüft Abschnittsbildung,
+Satzgrenzen (Abkürzungen und Ordnungszahlen sind kein Satzende), Glossar (inkl.
+„jede Ersetzung im Glossar einer Rede trifft diese Rede, jede im gemeinsamen Glossar
+trifft mindestens eine“), Streaming-Auswertung, Absatzgliederung (Text bleibt
+unverändert, 3–10 Sätze), Verbinden kurzer Absätze (Modell wird nur gefragt, wenn
+beide Nachbarn passen), Zwischenspeicher/Fortsetzen, Zeitauswahl, Sprachen und die
+Kommandozeile.
 `tests/test_glossar_vorschlag.py` prüft Filter (nur Funde im Text, keine bekannten),
 Ausgabeformat (gültiges Glossar, Unsicheres auskommentiert) und Zwischenspeicher.
 `tests/test_aenderungen.py` prüft den Wortvergleich (Satzzeichen, Groß-/Kleinschreibung
@ -427,16 +442,20 @@ Die Tests nutzen eine kleine eigene Wortliste statt der des Systems.
 `tests/test_yt_untertitel.py` prüft Spurauswahl, Aufruf von `yt-dlp` und
 Fehlerfälle (ohne Netz, `yt-dlp` wird durch Fakes ersetzt).
 `tests/test_vtt2txt.py` prüft die VTT-Umwandlung: jede `.vtt` in `testdaten/`
-ergibt genau die zugehörige `.txt`, echte Wiederholungen bleiben erhalten,
-dazu Muster, Ausgabeverzeichnis und Fehlerfälle.
+ergibt genau die zugehörige `.txt`, echte Wiederholungen bleiben erhalten, auch bei
+Untertiteln ohne rollendes Fenster, dazu Zeitauswahl, Muster, Ausgabeverzeichnis und
+Fehlerfälle.

 ## Zwischenstände

 Jeder fertige Abschnitt, jede Absatzgliederung und jede Entscheidung beim
 Verbinden kurzer Absätze wird in `<Ausgabe>.parts/` gespeichert. Ein erneuter
 Lauf überspringt alles, was schon berechnet ist.
-Ändern sich Modell (auch per `-m`), Prompt, Glossar oder Text eines Abschnitts, wird genau dieser
-Teil neu berechnet. Den Ordner kann man jederzeit löschen.
+Ändern sich Modell (auch per `-m`), Prompt, Glossar oder Text eines Abschnitts, wird
+genau dieser Teil neu berechnet. Glossar-Begriffe stehen im Prompt; ein neuer Begriff
+lässt deshalb alle Abschnitte neu korrigieren. Den Ordner kann man jederzeit löschen.
+`glossar_vorschlag.py` speichert seine Modellantworten ebenso in
+`<Entwurf>.parts/`.

 ## Einstellungen

@ -446,9 +465,27 @@ Oben in `abschrift_korrigieren.py`:
 |---|---|---|
 | `MODEL` | `qwen3:32b` | Ollama-Modell (Standard für `-m`) |
 | `CHUNK_SIZE` | 1200 | Wörter pro Korrekturabschnitt |
+| `MAX_EXTRA_WORDS` | 300 | so weit darf ein Abschnitt bis zum nächsten Satzende wachsen |
 | `MAX_WORD_DEVIATION` | 0.05 | Warnschwelle Wortzahl |
+| `PARAGRAPH_WINDOW` | 150 | Sätze pro Anfrage bei der Absatzgliederung |
 | `MAX_PARAGRAPH_SENTENCES` | 10 | längster erlaubter Absatz |
 | `MIN_PARAGRAPH_SENTENCES` | 3 | kürzester gewünschter Absatz |
+| `NO_SENTENCE_END` | Muster | Abkürzungen, die kein Satzende sind |
+
+In `aenderungen.py`:
+
+| Konstante | Standard | Bedeutung |
+|---|---|---|
+| `WORDLISTS` | `/usr/share/dict/ngerman`, `…/american-english` | Wortlisten je Sprache |
+| `MIN_SIMILARITY` | 0.6 | darunter gilt eine Ersetzung als „stark verändert“ |
+| `FILLERS` | äh, ähm, … | Füllwörter, deren Streichung nicht gemeldet wird |
+
+In `vtt2txt.py`:
+
+| Konstante | Standard | Bedeutung |
+|---|---|---|
+| `MAX_SNAP_SECONDS` | 30 | so weit darf ein Zeitbereich bis zur nächsten Satzgrenze wachsen |
+| `ROLLING_SHARE` | 0.5 | ab diesem Anteil sich überlappender Blöcke gilt eine Datei als rollend |

 ## Bekannte Grenzen