renky1025/agent-skills

Screenshot der Verarbeitungsschritte

video-dubbing: Video-Übersetzung, Synchronisation und Untertitel-Synchronisation

Zweck

Ein vollständiges Video in eine andere Sprache lokalisieren: Die Originalsprache erkennen, übersetzen, mit TTS die Zielsprache generieren, unter Beibehaltung der ursprünglichen Zeitstempel die Tonspur mischen und die übersetzten Untertitel fest in das Bild einbrennen. Das Ergebnis ist eine direkt veröffentlichbare einzelne Videodatei, bei der Synchronisation und Untertitel natürlich synchron sind und keine sekundäre Nachbearbeitung erforderlich ist.

Wann verwenden

• Der Benutzer fordert die Übersetzung eines Videos in eine andere Sprache an, einschließlich Synchronisation (nicht nur Untertitel).
• Ein Video benötigt eine Zielsprachen-Synchronisation + synchronisierte Untertitel (zweisprachig oder nur Übersetzung).
• Schlüsselwörter: Video-Übersetzung, Video-Synchronisation, Übersetzte Untertitel, Fremdsprachige Vertonung, Zweisprachige Untertitel, dub a video, translate a video, foreign-language voiceover.
• Jeder Workflow, der ASR -> Übersetzung -> TTS -> Video-Zusammenführung umfasst.

Wann NICHT verwenden

• Nur eine Transkription ohne Übersetzung oder Synchronisation ist erforderlich -> an video-minutes oder direkt an Whisper übergeben.
• Nur Text soll in Audio umgewandelt werden, ohne Video -> an mlx-tts übergeben.
• Die ursprüngliche Hintergrundmusik / Toneffekte sollen beibehalten und professionell gemischt werden (Stimmenseparation) -> Diese Fähigkeit verwendet standardmäßig kein Demucs; dies muss separat behandelt werden.
• Das Video hat keine Tonspur oder die Audioqualität ist so schlecht, dass eine Erkennung unmöglich ist.

Workflow

Für den End-to-End-Prozess wird empfohlen, direkt das Orchestrierungsskript <skill>/scripts/dub.py zu verwenden (siehe ## Skripte). Es führt die folgenden Schritte nacheinander aus und pausiert bei der Übersetzung, um auf die KI-Übersetzung zu warten. Bei manueller Ausführung gehen Sie wie folgt vor:

1. Tonspur extrahieren (16 kHz, Mono): ffmpeg -y -i input.mp4 -ar 16000 -ac 1 -c:a pcm_s16le audio16k.wav

2. ASR-Transkription (mit präzisen Segment-Zeitstempeln): whisper audio16k.wav --model large-v3-turbo --language <Quellsprache> --output_format srt --output_dir . Erzeugt audio16k.srt, dessen Zeitstempel natürlich mit dem Originalvideo übereinstimmen. Für bessere Chinesisch-Erkennung kann Qwen3-ASR installiert werden (pip install qwen-asr) und <skill>/scripts/qwen3_asr.py verwendet werden.

3. Untertitel übersetzen (durch KI): SRT lesen, segmentweise übersetzen. Jedes SRT-Segment wird als eine Zeile Übersetzung ausgegeben, wobei die Reihenfolge streng eingehalten wird. Zuerst die Anzahl der Segmente zählen (z. B. 27 Segmente -> 27 Zeilen), als translated.txt speichern und vor dem Fortfahren die Zeilenanzahl überprüfen.

4. Synchronisation generieren: python3 <skill>/scripts/dub_segments.py audio16k.srt translated.txt dubbing.wav subtitle_synced.srt --lang <Zielsprache> Das Skript: Verwendet das erste Segment als Klangfarbe-Referenz, um Klangfarbe-Konsistenz zu gewährleisten; behält die ursprünglichen Zeitstempel bei, sodass Untertitel und Bild synchron sind; wendet nur bei Segmenten, die ihren Slot überlaufen, eine Geschwindigkeitsänderung an (atempo 0.88–1.20); verbindet benachbarte Intervalle von weniger als 1s, um einen natürlichen Höreindruck zu erzeugen.

5. Synchronisierte Tonspur in Video einfügen:

   ffmpeg -y -i input.mp4 -i dubbing.wav \
     -map 0:v:0 -map 1:a:0 \
     -c:v copy -c:a aac -b:a 192k -shortest output_temp.mp4
   

   Anschließend bestätigen, dass die Tonspur ersetzt wurde: ffprobe -v error -show_entries stream=codec_type -of csv=p=0 output_temp.mp4 (sollte video, audio anzeigen).

6. Harte Untertitel einbrennen: python3 <skill>/scripts/burn_subtitles.py output_temp.mp4 subtitle_synced.srt output_final.mp4 Rendert die übersetzten Untertitel dauerhaft in das Bild.

7. Aufräumen (optional): Zwischenprodukte wie audio16k.wav, audio16k.srt, translated.txt, dubbing.wav, subtitle_synced.srt, output_temp.mp4 löschen.

Entscheidungsregeln

• Für einen vollautomatischen Durchlauf -> dub.py verwenden; nur einen bestimmten Schritt wiederholen (z. B. wenn bereits SRT vorhanden) -> dub.py --srt existing.srt verwenden, um den Schritt zu überspringen.
• ASR-Engine: Standardmäßig --asr whisper (large-v3-turbo); bei hohen Anforderungen an die Chinesisch-Erkennung -> --asr qwen3.
• Keine harten Untertitel erforderlich -> dub.py --no-burn (nur bis zur Audiospur-Zusammenführung).
• Zielsprache wird durch --target-lang festgelegt (Standard zh); die TTS-Sprache von dub_segments.py wird durch --lang festgelegt.
• Die Übersetzung muss von der KI durchgeführt werden und streng 1:1 mit den SRT-Segmenten übereinstimmen; bei Zeilenanzahl-Unterschieden bricht das Skript mit einem Fehler ab und darf nicht umgangen werden.
• Wenn Untertitel nicht erscheinen oder Chinesisch als Kästchen angezeigt wird -> burn_subtitles.py (moviepy-Rendering, findet automatisch chinesische Schriftarten) verwenden, nicht auf ffmpegs subtitles= verlassen (schlägt bei fehlendem libass still fehl).
• Wenn die Synchronisationsdauer den Slot überläuft -> auf die segmentierte atempo-Funktion des Skripts vertrauen, keine globale Geschwindigkeitsänderung der gesamten Tonspur durchführen.

Einschränkungen

• Zeitstempel müssen die ursprünglichen ASR-Ergebnisse wiederverwenden; es ist verboten, für die Synchronisation erneut eine ASR durchzuführen, um Zeitstempel zu erhalten.
• Die Anzahl der Übersetzungszeilen muss gleich der Anzahl der SRT-Segmente sein (1:1), sonst wird abgebrochen.
• Beim Zusammenführen der Tonspur muss explizit -map 0:v:0 -map 1:a:0 verwendet werden, sonst bleibt die ursprüngliche Tonspur erhalten.
• ASR muss large-v3-turbo (oder turbo) verwenden, nicht auf base/tiny zurückfallen.
• Geschwindigkeitsänderungen erfolgen nur auf Segmentebene im Bereich 0.88–1.20x; globales atempo ist verboten.
• Standardmäßig erfolgt keine Hintergrundmusik-Stimmenseparation; wenn der Benutzer dies wünscht, muss explizit darauf hingewiesen werden, dass eine zusätzliche Verarbeitung erforderlich ist.

Überprüfung

Vor der Auslieferung Punkt für Punkt bestätigen:

• Die Zeilenanzahl von translated.txt stimmt exakt mit der Anzahl der SRT-Segmente überein.
• dubbing.wav und subtitle_synced.srt wurden beide erstellt.
• ffprobe zeigt, dass das endgültige Video sowohl video- als auch audio-Streams enthält und der Ton tatsächlich ersetzt wurde.
• Die Untertitel sind fest im Bild eingebrannt (keine externen weichen Untertitel), und Chinesisch wird nicht als Kästchen angezeigt.
• Synchronisation und Bild an mehreren zufälligen Prüfpunkten auf Zeitstempel-Synchronität überprüft.
• Die vom Benutzer bereitgestellten Quelldateien wurden nicht gelöscht.

Ausgabe

• Ergebnis: Eine lokalisierte Videodatei (standardmäßig output_final.mp4, bei dub.py als <Video-Name>_<Zielsprache>.mp4), mit Zielsprachen-Synchronisation und harten Untertiteln; optional kann subtitle_synced.srt beibehalten werden.
• Erledigt, wenn: Die Tonspur ersetzt wurde, die Untertitel eingebrannt sind, Bild und Ton an den Prüfpunkten synchron sind und die ffprobe-Überprüfung bestanden ist.
• Nachweis: Pfad der endgültigen Datei; Anzahl der SRT-Segmente und Übersetzungszeilen; Stream-Liste von ffprobe; überprüfte Synchronzeitpunkte.

Referenzen

Nur bei Bedarf laden, nicht vorab vollständig lesen:

• references/pipeline-design.md — Bei Erklärungs- oder Anpassungsbedarf des Pipeline-Verhaltens (warum Zeitstempel beibehalten werden, segmentierte Geschwindigkeitsänderung, keine Stimmenseparation standardmäßig, Produkt- und Abhängigkeitsliste) lesen.
• references/troubleshooting.md — Bei tatsächlichen Fehlern, Asynchronität von Bild und Ton, nicht erscheinenden Untertiteln oder Chinesisch in Kästchenform lesen.

Skripte

• <skill>/scripts/dub.py — End-to-End-Orchestrierung. Verwendung: python3 <skill>/scripts/dub.py input.mp4 --source-lang en --target-lang zh [--asr whisper|qwen3] [--srt existing.srt] [-o out.mp4] [--font-size 28] [--no-burn] [--keep-temp]. Läuft bis zum Übersetzungsschritt, erstellt to_translate.txt und fordert die KI auf, in translated.txt zu übersetzen, dann wird fortgefahren; gibt den endgültigen Videopfad und den Untertitelpfad zurück.
• <skill>/scripts/dub_segments.py — Segmentierte TTS-Synchronisation + Zeitstempel-Ausrichtung. Verwendung: python3 <skill>/scripts/dub_segments.py original.srt translated.txt out_dub.wav out_synced.srt [--lang zh] [--min-atempo 0.88] [--max-atempo 1.20] [--gap-bridge 1.0] [--keep-temp]. Gibt die ausgerichtete dubbing.wav und subtitle_synced.srt zurück; bei Nichtübereinstimmung der Übersetzungszeilen wird mit Exit-Code 1 abgebrochen.
• <skill>/scripts/burn_subtitles.py — Mit moviepy harte Untertitel einbrennen. Verwendung: python3 <skill>/scripts/burn_subtitles.py input.mp4 subtitles.srt output.mp4 [--font <Pfad>] [--font-size 28]. Gibt das Video mit eingebrannten Untertiteln zurück; wenn --font nicht angegeben ist, wird automatisch eine chinesische Schriftart erkannt.
• <skill>/scripts/qwen3_asr.py — Whisper-kompatibles Qwen3-ASR-CLI, besser für Chinesisch-Erkennung. Verwendung: python3 <skill>/scripts/qwen3_asr.py audio.wav [--model 0.6B|1.7B] [--language zh] [-f srt|vtt|txt|json|tsv|all] [-o Ausgabeverzeichnis] [--device cuda:0|mps|cpu] [--dtype float16|bfloat16|float32]. Gibt eine Untertitel-/Textdatei im angegebenen Format zurück. Modell-Alias: turbo/tiny/base/small -> Qwen3-ASR-0.6B, medium/large -> Qwen3-ASR-1.7B.

Fehlerbehebung

• Synchronisation wurde nicht ersetzt / Originalton ist noch vorhanden -> Beim Zusammenführen mit ffmpeg wurde -map 0:v:0 -map 1:a:0 vergessen.
• Untertitel erscheinen nicht oder Chinesisch wird als Kästchen angezeigt -> burn_subtitles.py verwenden und mit --font eine chinesische Schriftart angeben.
• Anzahl der Übersetzungszeilen stimmt nicht mit der Anzahl der SRT-Segmente überein -> Das Skript bricht mit einem Fehler ab; zuerst auf 1:1 ergänzen.
• Vollständige Fehlerliste siehe references/troubleshooting.md.

Verwandte Fähigkeiten

• mlx-tts — Bietet die zugrunde liegende mlx_audio.tts.generate-Funktion, von der diese Synchronisationsfähigkeit abhängt.
• video-minutes — Video in strukturierte Zusammenfassungen umwandeln; verwenden, wenn nur Transkription/Zusammenfassung erforderlich ist.