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

**Ausprobieren ohne YouTube:** Im Ordner `tests/daten/` liegt eine frei erfundene
Beispielrede (Festrede zum Jubiläum der Gemeinde „Auental“) mit typischen Hörfehlern
und einem passenden Glossar. Ein Lauf dauert etwa zwei bis drei Minuten und zeigt alle
Ergebnisse, auch den Änderungsbericht:

```bash
./abschrift_korrigieren.py -i tests/daten/beispiel.de.txt -g tests/daten/beispiel.glossar.txt -o beispiel.korrigiert.txt
# → beispiel.korrigiert.txt, beispiel.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 untertitel
# → untertitel/Lahnstein.de-orig.vtt
./vtt2txt.py -i untertitel/Lahnstein.de-orig.vtt
# → untertitel/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). Ein kleines,
leicht nachvollziehbares Glossar zur Beispielrede steht in
`tests/daten/beispiel.glossar.txt`.

### 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. Das Modell ist angewiesen, nichts zu ergänzen, auch keine Vornamen oder
   Titel aus dem Glossar: Steht dort „Alexander Dobrindt“, bleibt ein gesagtes
   „Dobrindt“ trotzdem „Dobrindt“.
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: 20 Stellen (davon 2 Wortformen)           ← diese Stellen ansehen!
  gültiges Wort ersetzt: „in“ → „dass“
  stark verändert: „OSola“ → „Ursula“
  …
  Wortform geändert: „sehe“ → „sähe“                  ← Wortformen am Ende
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.** Darunter in einer eigenen
   Tabelle die bloßen Wortformen („Wortform geändert“).
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 gestrichelt umrahmt | geänderte Wortform (meist Grammatik) |
| 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“ |
| Wortform geändert | Ein echtes Wort hat nur eine andere Endung oder einen Umlaut bekommen. Meist eine richtige Grammatik-Korrektur; steht in einer eigenen Gruppe am Ende. | „Punkten“ → „Punkte“, „das“ → „dass“, „sehe“ → „sähe“ |
| 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 Schreibweisen aus dem Glossar („Bar“ →
„Bahr“, wenn „Egon Bahr“ im Glossar steht). Ergänzt das Modell dagegen Wörter, etwa
einen Vornamen („Dobrind“ → „Alexander Dobrindt“), erscheint das auch dann, wenn der
volle Name im Glossar steht: Gesagt wurde er so nicht.

**So arbeitet man die Liste ab:**

1. Für jede Zeile den Zusammenhang lesen.
2. Ist die Änderung richtig, nichts tun. Bei den Wortformen am Ende ist das der
   Normalfall; dort genügt ein kurzer Blick.
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.

**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
vorhandene Datei als von Hand geändert.

---

## 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`.
> Reicht ein Bereich über das Ende des Videos hinaus, weist das Programm darauf hin
> und nennt die Länge der Untertitel.

### 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, 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
  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.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. In Klammern steht, wo die Untertitel enden. |
| `Hinweis: Bereich Anfang – 05:00:00 reicht über das Ende der Untertitel hinaus (…)` | Der Bereich endet nach dem Video. Meist war Minute statt Stunde gemeint: `05:00` ist Stunde 5, Minute 5 ist `00:05`. Bearbeitet wird trotzdem, bis zum Ende des Videos. |
| `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 |
| `--ueberschreiben` | von Hand geänderte Ausgabedatei trotzdem ersetzen |

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