boyingliu01/bilingual-video-subtitles

Bilingual Video Subtitles – Zweisprachige Untertitel für Schulungsvideos

Die vollständige Pipeline befindet sich in scripts/pipeline.py (einheitlicher Einstiegspunkt, Phasen sind zwischengespeichert und können bei Unterbrechung fortgesetzt werden).

Hinweis zur Host-Umgebung: Dieses Skill ist umgebungsübergreifend angepasst; das Transkriptions-Backend wird automatisch ausgewählt (natives Omni-Gateway der Sandbox / OpenAI-kompatible API / Whisper-Brücke). Wenn weder ein Omni-Gateway noch ein API-Backend konfiguriert ist, wird der Agent-Modus verwendet – die Phasen Transcribe/Translate werden mit Exit-Code 3 angehalten und erstellen ein Manifest. Nach Abschluss der entsprechenden Transkription/Übersetzung wird build erneut ausgeführt, um fortzufahren. Betriebsprotokoll und Backend-Konfiguration unbedingt in references/host-adaptation.md lesen. Pipeline-Abbruch mit Exit-Code 3 ist kein Fehler. Führen Sie die im Manifest angegebene Arbeit aus und führen Sie die Pipeline erneut aus.

Standard-Workflow

1. Eingabe abrufen: Videodatei + zugehörige Richtlinien-/Referenzdokumente (.docx/.txt/.md).
2. Referenzdokumente lesen und ein Glossar glossary.txt erstellen (jede Zeile: Chinesisch = Englisch, 10–40 Einträge). Das Glossar bestimmt die Übersetzungskonsistenz des gesamten Videos. Stellen Sie sicher, dass Folgendes abgedeckt ist: Richtlinien-/Normnamen, Rollen und Abkürzungen (z. B. PM=Project Manager), Geschäftsdokumente oder Formularnamen, interne Systemnamen.
3. Build ausführen (Vordergrund, ausreichendes Timeout einplanen; für ein 50-minütiges Video ca. 15–25 Minuten Gesamtlaufzeit):

python3 scripts/pipeline.py build \
  --video <Videopfad> --doc <Pfad zum Richtliniendokument> \
  --work <Arbeitsverzeichnis> --out <Ausgabeverzeichnis> \
  --glossary <glossary.txt> \
  --hotwords "Sicherheitsrichtlinien,Anforderungsformular,Änderungsformular,PM,QA,SRE" \
  --preview 90

4. Generierungsreihenfolge (jeder Schritt ist zwischengespeichert; bei Fehlern wird derselbe Befehl erneut ausgeführt, um fortzufahren): setup (Audio extrahieren) → transcribe (Qwen3-Omni Wort-für-Wort-Transkript) → timing (Whisper-Zeitachse) → align (Pinyin-Abgleich) → clean (umgangssprachliche Elemente entfernen, Sätze segmentieren) → translate (Batch-Übersetzung Chinesisch → Englisch) → package (Projektdatei + SRT + ASS) → render (Vorschau + Vollversion).
5. Verwenden Sie zuerst die mit --preview ausgegebene Vorschau, um dem Anwender die Qualität zu bestätigen (über media-read Einzelbilder extrahieren, um die Untertitelwiedergabe zu prüfen), und liefern Sie dann die Vollversion des Videos, SRT und die Untertitel-Projektdatei aus.

Lieferumfang – Beschreibung

Datei	Zweck
<Name>_中英双语字幕_完整版.mp4	Video mit eingebrannten Untertiteln (Chinesisch oben in Weiß, Englisch unten in Hellblau, beide mit halbtransparentem schwarzem Hintergrundbalken – auf jedem Hintergrund lesbar)
<Name>_中英双语字幕.srt	Zweisprachige Untertiteldatei (in Player/Plattform importierbar)
<Name>_字幕工程.json	Hauptdatendatei: Enthält alle Zeitstempel + zweisprachigen Text. Nur diese Datei wird bei der jährlichen Feinabstimmung bearbeitet.
--work-Verzeichnis	Zwischencache (Transkription, Whisper-Zeitachse). Beibehalten vermeidet erneute Transkription.

Jährliche Feinabstimmung (Untertitel nach Richtlinienänderung aktualisieren)

Wenn die Richtlinienänderung nur wenige Sätze betrifft, keine erneute Transkription erforderlich:

1. Lassen Sie den Anwender die zu ändernden Zeitbereiche/Inhalte angeben oder bearbeiten Sie direkt den zh/en-Text in der <Name>_字幕工程.json des Vorjahres (bei unveränderten Zeitstempeln start/end nicht ändern).
2. Neu rendern:

python3 scripts/pipeline.py render --project <Projekt.json> [--video <Neues Video>] [--srt-only]

Wenn das neue Video hinzugefügte/gelöschte Sätze in den entsprechenden Kapiteln enthält: Führen Sie für das neue Video build --stage transcribe aus, um die neue Wort-für-Wort-Transkription zu erhalten, vergleichen Sie manuell, ersetzen Sie die entsprechenden Einträge in der Projektdatei mit dem neuen Text und rendern Sie dann.

Aufteilung in Kurzvideos nach Thema/Rolle (Microlearning)

Basiert auf dem vollständigen Video mit bereits eingebrannten Untertiteln (behält die zweisprachigen Untertitel bei).

1. Kapitelgrenzen aus den Untertiteldaten identifizieren: Verwenden Sie die Rollen-/Kapitelliste des Referenzdokuments als Schlüsselwörter und durchsuchen Sie zh_lines.json (im Arbeitsverzeichnis) nach Kapitelübergangssätzen. Typische Muster: „Die N-te Rolle ist X“, „Oben war die Verantwortung von X, die Anforderung ist“, „Die Verstoßsituation von X ist“ usw. Der Startzeitpunkt des Übergangssatzes dient als Trennpunkt (der Satz gehört zum nächsten Clip).
2. Einschränkungen: Einzelclip ≤ 10 Minuten (hartes Limit 15 Minuten); wenn ein Kapitel das Limit überschreitet, innerhalb des Kapitels an natürlichen Grenzen (z. B. zwischen „Verantwortung/Verstoßverhalten/Feststellungsmethode“) nachschneiden; verschiedene Rollen nicht zusammenführen.
3. Schnittplan-JSON schreiben und ausführen:

{"base": "Videoname", "lead_in": 0.35,
 "chapters": [{"start": 0, "end": 288.4,
               "title": "01_Einleitung_Zweck_Überblick", "note": "Inhaltsbeschreibung"}]}

python3 scripts/pipeline.py split --plan plan.json \
  --video <Video_mit_Untertiteln_voll.mp4> --out <Ausgabeverzeichnis>

4. Ausgabe nach <Ausgabeverzeichnis>/<Videoname>_拆分视频/: automatisch benannte Clips + 00_拆分目录.txt (Clipname, Zeitbereich, Dauer, Inhaltsbeschreibung).
5. Stichprobenprüfung: Einzelbild aus jedem Clip extrahieren (ffmpeg PNG), um zu bestätigen, dass der Schnittpunkt genau am thematischen Startsatz liegt.

Wichtige Implementierungsvorgaben (nicht abweichen)

• Das qwen-omni-Backend MUSS den vollständigen Text des Referenzdokuments als Terminologiekontext in den Prompt injizieren, mit --timeout 900 --max-tokens 8192 (im Skript fest codiert); beim API-Backend spezialisierte ASR (z. B. mimo-asr) akzeptiert keinen Text-Prompt, die Terminologiekorrektur erfolgt in der Clean-Phase durch Abgleich mit dem Dokument.
• Whisper wird NUR für die Zeitachse verwendet; der erkannte Text wird immer verworfen (chinesische Textqualität ist schlecht, aber die Zeitstempel sind präzise).
• Der Abgleich MUSS global über Pinyin-Strings erfolgen (Homophonenfehler werden auf Pinyin-Ebene automatisch aufgelöst); satzweiser gieriger Abgleich führt zu einer Gesamtverschiebung.
• Abgleichqualität: qual mean ≥ 0.75 im align-Output ist normal; < 0.6 zuerst die Whisper-Sprachabdeckung prüfen (siehe references/troubleshooting.md).
• Langlaufende CPU-Aufgaben (Whisper/Render) beachten die Bereinigungsstrategie des Hosts für Hintergrundaufgaben; ggf. im Vordergrund ausführen.
• Netzwerkbeschränkungen: HuggingFace erfordert einen Spiegel; das Skript enthält bereits HF_ENDPOINT=hf-mirror.com und HF_HUB_DISABLE_XET=1, nicht entfernen.

Fehlerbehebung

Siehe references/troubleshooting.md: Behandlung von Upload-Timeout, einzelnen langen Zeilen in der Transkription, niedriger Ausrichtungsqualität, Schriftartproblemen, Rendering-Fehlern usw.