YouTube-Untertitel-Übersetzer
Lade YouTube-Videos herunter, extrahiere und verarbeite Untertitel (Korrekturlesen + Interpunktion + Übersetzung) und brenne sie dann zurück in das Video. Verarbeitet sowohl automatisch generierte als auch manuell hochgeladene Untertitel, mit Fallback auf ASR, wenn keine Untertitel vorhanden sind.
Harte Regeln
- Verwende maximal 3 gleichzeitige Unter-Agenten für die Untertitel-Blockverarbeitung. Wenn es mehr als 3 Blöcke gibt, führe sie in Wellen aus und starte den nächsten Block erst, nachdem ein Unter-Agent fertig ist.
- Die Anzahl der Blöcke ist nicht die Gleichzeitigkeit. Du darfst in 10 Blöcke aufteilen, aber du darfst nicht 10 Codex-Prozesse/Unter-Agenten gleichzeitig starten; führe maximal 3 aktive Arbeiter zu jeder Zeit aus.
- Lade immer nur die Quell-Untertitelspur herunter: Englisch, wenn verfügbar, ansonsten die Originalsprache des Videos. Lade keine automatisch übersetzten Zielsprachen-Untertitel von YouTube herunter; übersetze stattdessen aus den Quell-Untertiteln.
- Verwende niemals eine von YouTube bereitgestellte Zielsprachen-Untertitelspur als Abkürzung, selbst für lange Videos und selbst wenn
zh-Hansoder eine andere Zielsprache inautomatic_captionsaufgeführt ist. - Video-Download standardmäßig in 1080p. Wenn 1080p nicht verfügbar ist, lade die beste verfügbare Version unter 1080p herunter.
- Die Übersetzung muss von Unter-Agenten über Blockdateien durchgeführt werden. Verwende keine lokalen Modellhelfer für die Übersetzung.
- Entferne vor dem Schreiben von SRT/ASS illegale Untertitelzeichen aus dem Text, insbesondere einzelne Backslashes (
\), die im Video sichtbar dargestellt werden.
Arbeitsablauf-Übersicht
Phase 1: Download → Videoinfo abrufen, Video herunterladen, Untertitel extrahieren
Phase 2: Vorbereiten → Wenn keine Untertitel: Audio extrahieren → ASR ausführen
Phase 3: Verarbeiten → In Blöcke aufteilen → paralleles Agenten-Korrekturlesen + Übersetzen
Phase 4: Zusammenführen → Blöcke kombinieren → SRT/ASS-Dateien erstellen
Phase 5: Rendern → Untertitel mit ffmpeg auf Video brennen
Phase 1: Download
1.1 Videoinfo abrufen
Verwende das YouTube-MCP-Tool, um Metadaten abzurufen:
youtube_get_video_info(videoId="...", detail="standard")
Notiere: Titel, Dauer, Kanal, ob Untertitel verfügbar sind.
1.2 Ausgabeverzeichnis erstellen
Benenne das Verzeichnis nach dem Videotitel. Bereinige für das Dateisystem:
mkdir -p "/output/path/<Video Title>"
1.3 Video herunterladen
youtube_download(videoId="...", outputPath="<dir>/video.mp4", quality="1080p", force=true)
Wenn du yt-dlp verwendest, bevorzuge 1080p und falle auf das beste Format unter 1080p zurück:
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]/best" --merge-output-format mp4 \
-o "<dir>/video.%(ext)s" "<url>"
1.4 Nur Quell-Untertitel extrahieren
youtube_get_transcript(videoId="...", language="<source-language>")
Wenn das Ergebnis die Token-Limits überschreitet, wird es in einer Tool-Ergebnis-Datei gespeichert — lies es in Blöcken.
Dies ist eine unverhandelbare Quell-Untertitel-Richtlinie:
- Bevorzuge englische Untertitel/Beschriftungen, wenn verfügbar.
- Wenn Englisch nicht verfügbar ist, verwende die Originalsprache des Videos.
- Ignoriere
zh-Hans,zh-Hantund jede andere vom YouTube angezeigte Zielsprachenspur, einschließlich automatisch übersetzter Spuren. - Fordere keine von YouTube bereitgestellte Zielsprachen-Untertitelspur an, wiederhole sie nicht, führe sie nicht zusammen und rendere sie nicht.
- Zielsprachen-Untertitel müssen nur durch Unter-Agenten-Übersetzung aus dem Quell-Untertitel erzeugt werden.
Wenn ein Tool eine Liste wie en-orig, zh-Hans zurückgibt, wähle nur en-orig. Füge zh-Hans in keinen Download-Befehl ein.
Wenn du yt-dlp verwendest, schreibe nur den Quell-Untertitel:
yt-dlp --skip-download --write-auto-subs --write-subs \
--sub-langs "en.*" --sub-format srt --convert-subs srt \
-o "<dir>/video.%(ext)s" "<url>"
Falsch, nicht ausführen:
yt-dlp --write-auto-subs --sub-langs "en-orig,zh-Hans" ...
Wenn der englische/originale Untertitel-Download erfolgreich ist, aber eine Zielsprachen-Anfrage mit HTTP 429 fehlschlägt, wiederhole die Zielsprachen-Anfrage nicht. Diese Anfrage hätte nicht gestellt werden dürfen; fahre mit dem Quell-Untertitel fort und übersetze ihn durch Phase 3.
Wenn Untertitel existieren: Speichere rohe Segmente als JSON, fahre mit Phase 3 fort. Wenn KEINE Untertitel (404/Fehler): Fahre mit Phase 2 (ASR-Fallback) fort.
Speichere Rohdaten:
raw_segments.json— alle Segmente mit Text/Offset/Dauerraw_subtitles.srt— anfängliche SRT-Konvertierung
Phase 2: ASR-Fallback (Keine Untertitel verfügbar)
Wenn das Video keine Untertitel/Transkripte hat:
-
Audio extrahieren aus Video mit ffmpeg:
ffmpeg -i video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav -
ASR ausführen — Benutzer hat qwen3-asr angegeben, aber jedes Whisper-kompatible Modell funktioniert:
qwen3-asr audio.wav --output-format srt > raw_subtitles.srtOder verwende den integrierten Ansatz über den transcribe-Befehl des hyperframes-media-Skills.
-
Analysiere die SRT-Ausgabe zurück in das von Phase 3 erwartete Segment-JSON-Format.
Phase 3: Paralleles Korrekturlesen & Übersetzen
Dies ist der zeitaufwändigste Schritt für lange Videos. Die Strategie: In Blöcke aufteilen und mit Unter-Agenten verarbeiten, mit einer harten Grenze von 3 gleichzeitigen Unter-Agenten.
Führe diese Phase auch für sehr lange Videos durch. Die Länge ist kein Grund, die automatischen Zielsprachen-Untertitel von YouTube herunterzuladen oder zu verwenden. Die richtige Abkürzung für lange Videos ist die Aufteilung in Blöcke plus 3-Wege-Unter-Agenten-Gleichzeitigkeit, nicht die Wiederverwendung von Ziel-Untertiteln.
3.1 Segmente in Blöcke aufteilen
Verwende die umgekehrte Logik von scripts/merge-chunks.py — teile raw_segments.json in N-Blockdateien auf:
# Aufteilen in Blöcke mit einer Größe, die für die Überprüfung/Übersetzung geeignet ist.
n = len(segments)
chunk_count = min(10, max(1, (n + 75) // 76))
chunk_size = n // chunk_count + 1
for i in range(0, n, chunk_size):
save_chunk(i, segs[i:i+chunk_size])
Speichere als chunk_00.json, chunk_01.json, usw. Jedes enthält {"chunk_id", "start_idx", "end_idx", "segments": [...]}.
3.2 Parallele Agenten starten
Erzeuge für jeden Block einen Hintergrund-Unter-Agenten. Starte nicht mehr als 3 Unter-Agenten gleichzeitig. Wenn es 10 Blöcke gibt, starte zuerst die Blöcke 00, 01 und 02; wenn einer fertig ist, starte den nächsten anstehenden Block. Starte niemals alle 10 Blöcke auf einmal. Gib jedem Agenten:
- Den Pfad zu seiner
chunk_XX.json - Anweisungen, references/subtitle-proofreading.md für die vollständige Spezifikation zu lesen
- Ausgabepfad:
result_XX.jsonim selben Verzeichnis
Der Agent muss:
- Jedes Segment in seinem Block lesen
- Englisch korrekturlesen (ASR-Fehler beheben, Interpunktion hinzufügen)
- In natürliches vereinfachtes Chinesisch übersetzen (technische Begriffe auf Englisch lassen)
- Als JSON-Array mit
{index, start, end, en, zh}pro Segment speichern - Illegale Untertitelzeichen aus
enundzhentfernen, insbesondere einzelne Backslashes (\), Steuerzeichen und rohe ASS-Override-Klammern.
Wichtig: Die maximale Gleichzeitigkeit beträgt 3 Unter-Agenten/Prozesse. Wenn es mehr als 3 Blöcke gibt, führe sie in Wellen aus. Starte keine 10 Codex-Kindprozesse für 10 Blöcke.
3.3 Auf Abschluss warten
Überwache, welche result_XX.json-Dateien erscheinen. Fahre erst fort, wenn alle Blöcke abgeschlossen sind.
Phase 4: Zusammenführen & Ausgabedateien erstellen
Führe das Zusammenführungsskript aus:
python3 scripts/merge-chunks.py <output_dir>
Dieses erkennt automatisch alle result_*.json-Dateien und erzeugt:
| Datei | Inhalt |
|---|---|
final_subtitles.json | Zusammengeführtes JSON, sortiert nach Zeitstempel |
subtitles_bilingual.srt | Englische + chinesische Zeilen |
subtitles_zh.srt | Nur Chinesisch |
subtitles_en.srt | Nur Englisch |
4.2 Datenqualität validieren
Validiere vor dem Rendern immer die zusammengeführten Daten. Die parallele Agentenverarbeitung kann zu Zeitstempel-Korruption führen:
# Nach ungewöhnlichen Dauern suchen (>120s = fast sicher korrupt)
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
print(f'Ungewöhnliche Dauern: {len(bad)} / {len(segs)}')
for s in bad: print(f' [{s[\"index\"]}] {s[\"start\"]:.1f}->{s[\"end\"]:.1f} ({s[\"end\"]-s[\"start\"]:.0f}s)')
"
Wenn welche gefunden werden, behebe sie (begrenze end auf start + 6) und generiere SRT/ASS neu. Sowohl merge-chunks.py als auch srt-to-ass.py enthalten eine automatische Erkennung und Korrektur für dieses Problem.
Überprüfe die Ausgabe: Überprüfe, ob die ersten und letzten Einträge korrekte Zeitstempel und lesbaren Text haben.
Überprüfe auch die Textbereinigung:
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if '\\\\' in s.get('en','') or '\\\\' in s.get('zh','')]
print(f'Backslash-Artefakte: {len(bad)}')
for s in bad[:10]: print(s['index'], s.get('en',''), s.get('zh',''))
"
Phase 5: Untertitel auf Video rendern
Hier wird es knifflig. Verwende NICHT direkt das System-ffmpeg — siehe Fallstricke unten.
5.1 Das Rendern-Skript ausführen
bash scripts/render-subtitles.sh <video.mp4> <subtitles_bilingual.srt> [output.mp4]
Das Skript erledigt alles:
- Erkennt/erstellt ARM64-natives ffmpeg mit libass-Unterstützung
- Konvertiert SRT → ASS mit korrekter CJK-Schriftartkonfiguration
- Kopiert Dateien nach /tmp, um Probleme mit Pfaden mit Sonderzeichen zu vermeiden
- Rendert mit ffmpegs ass-Filter
- Validiert die Ausgabe
5.2 Ausgabe überprüfen
Überprüfe, ob:
- Die Ausgabedatei existiert und größer als 10 MB ist (nicht nur Audio)
- Die Dauer mit dem Originalvideo übereinstimmt (ffprobe verwenden)
- Spiele die erste und letzte Minute ab, um zu bestätigen, dass Untertitel erscheinen
Fallstricke & Gelernte Lektionen
Dies sind hart erarbeitete Lektionen aus der tatsächlichen Nutzung. Befolge sie, um stundenlange Verschwendung zu vermeiden.
ffmpeg-Architektur-Konflikt (KRITISCH)
Problem: macOS Homebrew's ffmpeg ist OHNE libass, libfreetype und fontconfig kompiliert. Die Filter ass, subtitles und drawtext existieren einfach nicht.
Schlimmer: Statische ffmpeg-Builds von evermeet.cx sind x86_64 (Intel)-Binärdateien. Auf Apple Silicon Macs laufen sie über Rosetta 2 Emulation mit etwa 8-10x langsamerer Geschwindigkeit. Ein 1,5-Stunden-Video dauerte 2+ Stunden.
Lösung: Verwende scripts/ensure-ffmpeg.sh. Es erkennt diese Probleme und kompiliert ARM64-natives ffmpeg aus dem Quellcode mit allen benötigten Bibliotheken. Der erste Build dauert ~5 Minuten; nachfolgende Neubuilds sind sofort (zwischengespeicherte Objektdateien).
Erforderliche Konfigurations-Flags für vollständige Untertitelunterstützung:
--enable-libass --enable-libfreetype --enable-fontconfig --enable-libdav1d
AV1-Decodierung fehlt
Problem: Viele moderne YouTube-Videos sind in AV1 codiert (codec_name: av1). Ein ohne --enable-libdav1d erstelltes ffmpeg schlägt während der Decodierung mit "Function not implemented"-Fehlern fehl und erzeugt eine 68 MB große, nur-Audio-Datei.
Lösung: Füge beim Erstellen von ffmpeg immer --enable-libdav1d hinzu.
Pfad-Sonderzeichen unterbrechen ffmpeg-Filter
Problem: Wenn der Video- oder Untertitelpfad Zeichen wie Gedankenstriche (—), intelligente Anführungszeichen oder Nicht-ASCII-Zeichen enthält, kommt der Filter-Parser von ffmpeg mit "No option name near..."-Fehlern ins Straucheln. Dies passiert auch bei korrektem Shell-Quoting.
Lösung: Kopiere Untertiteldateien nach /tmp/subs_<pid>.ass, bevor du sie an ffmpeg übergibst. Das Rendern-Skript erledigt dies automatisch.
moviepy TextClip-API-Konflikte (VERMEIDEN)
Problem: Der TextClip von moviepy 2.x hat Parameterkonflikte zwischen Positions- und Schlüsselwortargumenten (font erscheint intern zweimal). Mehrere Fehlervarianten, keine offensichtlich aus der Fehlermeldung.
Empfehlung: Verwende moviepy nicht für die produktive Untertitelwiedergabe. Verwende stattdessen den ass-Filter von ffmpeg — er ist schneller, zuverlässiger und verarbeitet CJK-Schriftarten ordnungsgemäß über libass/fontconfig.
SRT vs. ASS für ffmpeg
Problem: Der subtitles-Filter von ffmpeg (der SRT direkt liest) leidet bei einigen Builds ebenfalls unter Pfad-Parsing-Problemen. Der ass-Filter ist zuverlässiger.
Lösung: Konvertiere zuerst SRT → ASS mit scripts/srt-to-ass.py und verwende dann den ass-Filter. Das ASS-Format gibt dir auch eine feine Kontrolle über Schriftart, Größe, Positionierung und Stil.
Illegale Untertitelzeichen
Problem: Roh- oder übersetzter Untertiteltext kann einzelne Backslashes (\) oder ASS-Override-Zeichen enthalten. Bei der ASS-Wiedergabe kann ein wörtlicher Backslash auf dem Bildschirm erscheinen oder versehentlich mit der ASS-Escape-Syntax interagieren.
Lösung: Bereinige den Untertiteltext vor dem Schreiben von SRT/ASS:
- Entferne Backslashes aus dem für den Benutzer sichtbaren Untertiteltext
- Entferne Steuerzeichen mit Ausnahme von normalen Leerzeichen
- Entferne rohe
{- und}-Klammern aus dem Untertiteltext - Lasse
srt-to-ass.pynur die ASS-Steuersequenzen hinzufügen, die es besitzt, wie\Nzwischen zweisprachigen Zeilen
Ungewöhnliche Untertitel-Dauern durch parallele Agentenverarbeitung
Problem: Bei der Verarbeitung von Untertiteln in parallelen Blöcken (Phase 3) können einzelne Agenten Einträge mit korrupten Zeitstempeln erzeugen — insbesondere end-Werte, die weit größer als start sind (z. B. Dauer von 2600s oder 4800s statt ~6s). Dies führt dazu, dass diese Untertitelzeilen für den größten Teil des Videos auf dem Bildschirm sichtbar bleiben und sich mit allen anderen Inhalten überschneiden.
Ursache: Agenten weisen manchmal Endzeiten falsch zu, wenn fragmentierte ASR-Segmente über Blockgrenzen hinweg konsolidiert werden. Das Problem liegt auf Datenebene, nicht bei der Wiedergabe — es wird daher nicht von ffmpeg-Fehlern abgefangen.
Lösung: Drei Verteidigungsebenen:
scripts/srt-to-ass.pyerkennt automatisch Einträge mit einer Dauer > 120s und begrenzt sie auf 6s mit einer Warnung- Phase 4-Validierung: Suche nach dem Zusammenführen von Blöcken immer nach Einträgen, bei denen
(end - start) > 120Sekunden beträgt - Vor-Rendering-Prüfung: Durchsuche vor dem Ausführen von ffmpeg die ASS-Datei auf verdächtig lange Dialogue-Zeilen
# Kurze Vor-Rendering-Prüfung: Finde Untertitel, die länger als 2 Minuten dauern
python3 -c "
import json, sys
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
if bad: print(f'WARNUNG: {len(bad)} ungewöhnliche Dauern gefunden!'); sys.exit(1)
else: print('Dauerprüfung bestanden')
"
Schriftgrößenanpassung
Problem: Standard-Schriftgrößen (16-20px) können auf hochauflösenden 1080p+-Videos zu klein sein, insbesondere bei Betrachtung auf kleineren Bildschirmen oder aus der Entfernung.
Lösung: Verwende das Flag --font-size zur Anpassung. Empfohlene Basisgrößen:
- 1080p-Video:
--font-size 24(zweisprachig) oder--font-size 28(einsprachig) - 4K-Video:
--font-size 36oder größer - Das Skript
render-subtitles.shübergibt dies ansrt-to-ass.py
Abhängigkeiten
- YouTube-MCP-Tools:
mcp__plugin_youtube_youtube__*(Video-Download, Transkript, Info) - ffmpeg: Automatisch erstellt durch
scripts/ensure-ffmpeg.sh
...