Automatische Untertitel
Mache aus jeder Audio- oder Videodatei Untertitel. Standardmäßig werden zweisprachige Untertitel (Originalsprache + Chinesisch) ausgegeben. Die gesamte Verarbeitung erfolgt lokal auf diesem Rechner, kein API-Key erforderlich.
Auslösung
Zwei Fälle müssen abgedeckt werden:
- Null-Anweisung: Der Benutzer lädt nur eine Audio-/Videodatei hoch, ohne zu sagen, was er will → dann sollen Untertitel erstellt werden. Einfach starten, nicht nachfragen.
- Ein Satz: „Untertitel erstellen", „Untertitel generieren", „Untertitel hinzufügen", „Untertitel einbrennen", „Übersetze diesen Audioausschnitt" + Datei.
Nur in einem Fall sollte man zuerst nachfragen: Wenn der Benutzer ausdrücklich nur Chinesisch möchte (keine Originalzeile), dann --mono hinzufügen. In allen anderen Fällen wird standardmäßig der zweisprachige Modus verwendet.
Umgebung
Drei Abhängigkeiten müssen im PATH sein:
| Abhängigkeit | Zweck | Prüfbefehl |
|---|---|---|
| Python 3.10+ | Führt die Skripte dieser Fähigkeit aus | python --version |
| babelscribe | Transkriptions-Engine (Whisper.cpp-Wrapper) | babelscribe devices |
| ffmpeg | Audiotranskodierung, auch für das Einbrennen (--burn) | ffmpeg -version |
Installation der Engine: pip install babelscribe.
Modelle müssen nicht manuell heruntergeladen werden: Bei der ersten Transkription lädt babelscribe automatisch ggml-large-v3-turbo.bin (ca. 1,6 GB) in das Verzeichnis ~/.babelscribe/models/. Beim ersten Durchlauf für eine bestimmte Sprache oder bei Verwendung von --accurate werden weitere Modelle heruntergeladen – das ist normal und sollte nicht als Hängenbleiben interpretiert werden.
Wenn eine NVIDIA-GPU vorhanden ist, wird automatisch das Vulkan-Backend ausgewählt – keine manuelle CUDA-Kompilierung erforderlich. babelscribe devices listet alle verfügbaren Geräte auf und zeigt an, welches automatisch ausgewählt wird. Getestet: Auf einem RTX 3050 Ti Laptop (4 GB VRAM) dauert die Transkription von 48 Sekunden Audio etwa 20 Sekunden, eine 51-minütige Live-Aufzeichnung etwa 13 Minuten.
Die Skripte dieser Fähigkeit befinden sich im Verzeichnis scripts/ auf der gleichen Ebene wie SKILL.md.
Unter Windows muss $env:PYTHONIOENCODING='utf-8' gesetzt sein, da sonst chinesische Ausgaben in der Konsole verstümmelt werden.
Ablauf
Schritt 1 · Transkription + Neusegmentierung
$env:PYTHONIOENCODING='utf-8'
python scripts/make_subtitles.py "<Audio-/Video-Pfad oder URL>" --outdir "<Ausgabeverzeichnis>"
Lies die SCHLÜSSEL=WERT-Paare am Ende der Standardausgabe (stdout):
| Schlüssel | Bedeutung |
|---|---|
SOURCE_LANG | Automatisch erkannte Sprache, z.B. en, zh, ja |
STEM | Basisname der Ausgabedateien, wird in den folgenden Schritten verwendet |
CUES_JSON | Paket für die Übersetzung, Eingabe für Schritt 3 |
SOURCE_SRT | Untertitel in der Originalsprache (bereits segmentiert, nicht die rohe, zusammenhängende Version) |
NEEDS_TRANSLATION | yes = Übersetzung ins Chinesische erforderlich; no = Originalsprache ist bereits Chinesisch |
PUNCTUATION_LOST | yes = Satzqualität unzureichend, Schritt 2 erforderlich |
TRANSCRIPT_TXT | Nur vorhanden, wenn PUNCTUATION_LOST=yes; Eingabe für Schritt 2 |
Warum Neusegmentierung? Whispers natürliche Segmente sind oft 7–8 Sekunden lang mit über 100 Zeichen – als Untertitel würde der Bildschirm überfüllt. Das Skript verwendet wortgenaue Zeitstempel und segmentiert basierend auf Satzzeichen und Pausen neu in kurze Sätze mit maximal 20 chinesischen Zeichen oder 48 Zeichen für Englisch.
Schritt 2 · Satzzeichen für chinesische/japanische Originalaufnahmen hinzufügen (nur wenn PUNCTUATION_LOST=yes)
Whisper fügt bei Chinesisch und Japanisch nur sporadisch Satzzeichen hinzu, der Rest wird durch Pausen getrennt. Bei Chinesisch führt das zu Aufteilungen wie „übersetzen in / Schriftzeichen"; bei Japanisch – wo es keine Leerzeichen zwischen Wörtern gibt – sind Whispers Absätze aneinandergereiht, sodass selbst Pausen fehlen. Das Ergebnis sind Untertitel, die genau bei der 20-Zeichen-Grenze hart getrennt werden und Dinge wie „Shin / shi wake nai" oder „kuma / ru san" produzieren. Die Lösung: Untertitel auf echte Satzzeichen setzen:
- Lies
TRANSCRIPT_TXT(ein fortlaufender, satzzeichenloser Text). - Füge nur Satzzeichen hinzu, ändere kein einziges Zeichen. Selbst offensichtlich falsche Wörter – wenn die ASR „Maschinenübersetzung" als „Maschinenumschreibung" oder „Wortebene" als „Wortebnene" transkribiert hat – bleiben unverändert. Das Ändern von Wörtern führt dazu, dass die Neuausrichtung fehlschlägt und die Satzzeichen nicht angebracht werden können.
- Schreibe die Datei
<STEM>.punct.txt(UTF-8). - Führe Schritt 1 erneut aus mit der Option
--punct-file(die<STEM>.raw.jsonwird automatisch wiederverwendet, dauert Sekunden, keine erneute Transkription):
python scripts/make_subtitles.py "<Eingabe>" --outdir "<Ausgabeverzeichnis>" --punct-file "<STEM>.punct.txt"
Die Satzzeichendichte ist der einzig wirklich wichtige Indikator in diesem Schritt. Die maximale Länge eines Untertitels beträgt 20 Zeichen, daher müssen Satzzeichen häufiger gesetzt werden als in geschriebener Sprache: Alle 8–18 Zeichen sollte ein „、" oder „。" stehen. Bei unzureichender Dichte werden Untertitel trotzdem hart getrennt – anhand desselben 51-minütigen japanischen Audiobeispiels:
| Satzzeichendichte | Anzahl der Zeilen | Enden mit Satzzeichen |
|---|---|---|
| Keine Hinzugefügten | 821 | 25 % |
| ~32 Zeichen/Satzzeichen (zu niedrig) | 1005 | 76 % |
| 8–18 Zeichen/Satzzeichen | 1081 | 98 % |
„、" wird an Phrasengrenzen, nach Partikeln, bei kleinen Pausen in der gesprochenen Sprache und für Untertitel-Umbruch verwendet – es ist richtig, es häufiger zu verwenden als im geschriebenen Japanisch. Dies ist keine Verschlechterung des Textes. Verwende nur 。 、 ! ? …: Klammern wie 「」 sind nicht in der Satzzeichentabelle des Skripts enthalten und werden ignoriert.
Nach dem Hinzufügen der Satzzeichen endet jeder Untertitel in SOURCE_SRT an einem Satzzeichen. Wenn die Ausgabe WARN: ... Ausrichtungsfehlerrate NN% enthält, wurde der Originaltext geändert. Gehe zurück und füge nur Satzzeichen hinzu, wiederhole den Vorgang.
Wie man Satzzeichen für lange Audiodateien hinzufügt: Der Volltext eines 51-minütigen Audios hat über 14.000 Zeichen und kann nicht auf einmal verarbeitet werden. Teile ihn in Blöcke von ~1500 Zeichen auf. Übergib jeden Block einem parallelen Agenten (mit 200 Zeichen Kontext vor und nach dem Block, aber gib nur den aktuellen Block aus). Am Ende validiere mit einem Skript, dass der Text nach dem Entfernen aller Satzzeichen zeichenweise mit dem Original übereinstimmt, und setze ihn dann zusammen. Diese Validierung ist nicht optional und darf auch nicht der Selbsteinschätzung des Agenten vertraut werden – in Tests bei 10 Blöcken behaupteten 2 fälschlicherweise „zeichenweise erfolgreich validiert", obwohl tatsächlich Zeichen fehlten oder geändert wurden, was nur durch diesen Schritt erkannt wurde.
Die Änderung der Dichte und erneute Ausführung ist günstig: Da raw.json wiederverwendet wird, sind die Kosten für das Experimentieren mit der Dichte nahezu null. Wenn nach dem ersten Hinzufügen nur 76 % der Zeilen mit Satzzeichen enden, wiederhole den Vorgang einfach mit einer höheren Dichte.
Schritt 3 · Übersetzung (nur wenn NEEDS_TRANSLATION=yes)
Lies CUES_JSON – es enthält {"cues": [{"id":1,"start":...,"end":...,"text":"..."}]}.
- Lies zuerst den gesamten Abschnitt, verstehe ihn als ganzen Satz, und verteile dann die chinesische Übersetzung auf die einzelnen Cues. Eine unabhängige, zeilenweise Übersetzung würde Sätze, die sich über mehrere Zeilen erstrecken, zerreißen (z.B. würde „replacing people." isoliert als „ersetzt Menschen" übersetzt und der Kontext des vorherigen Satzes ginge verloren).
- Gib jede chinesische Zeile mit maximal 16 Zeichen aus, abgestimmt auf die Dauer des Cues (chinesische Lesegeschwindigkeit etwa 4–5 Zeichen/Sekunde; ein 1,2-Sekunden-Cue mit 18 Zeichen ist für den Zuschauer nicht lesbar).
- Schreibe die Übersetzung als
<STEM>.zh.jsonim Format{"1": "Erste Übersetzung", "2": "..."}, wobei die IDs mit den Cues übereinstimmen müssen. - Achte auf konsistente Terminologie; Eigennamen bleiben im Original oder werden gemäß gängiger Konvention übersetzt.
Schritt 4 · Zusammenstellung der Ausgabe
python scripts/merge_bilingual.py "<STEM>.cues.json" "<STEM>.zh.json"
Optionale Parameter:
--mono– Nur die Übersetzung, ohne Original (wenn der Benutzer nur chinesische Untertitel möchte)--order zh-first– Chinesisch oben (Standard ist das Original oben)--burn "<Video-Pfad>"– Brennt die zweisprachigen Untertitel in das Video ein, Ausgabe<STEM>.bilingual.burned.mp4. Nur verwenden, wenn der Benutzer ein Video bereitstellt und wirklich eingebrannte Untertitel benötigt; das Einbrennen ist langsam und irreversibel.
Ausgaben:
<STEM>.bilingual.srt– Zweisprachige SRT, kompatibel mit jedem Player/Plattform<STEM>.bilingual.ass– Chinesisch groß, Original klein; geeignet zum Einbrennen oder für professionelle Player
Schritt 5 · Bericht
Gib eine Zusammenfassung in einem Satz + Schlüsselzahlen (Sprache, Dauer, Anzahl der Zeilen, Pfade der Ausgabedateien). Zeige 2–3 fertige Untertitelzeilen als Beispiel für die visuelle Qualität. Keine langen Logausgaben.
Häufige Optionen
| Szenario | Parameter |
|---|---|
| Laute Audioumgebung, starker Akzent, viele Fachbegriffe | --accurate (verwendet large-v3 + Beam Search, ca. 2–3x langsamer aber genauer) |
| Automatische Spracherkennung falsch | --lang zh (oder en, ja, th …) |
| Kürzere/längere Untertitel gewünscht | --max-chars 16 (bei Chinesisch in „Zeichen" gemessen) |
| Video-URL | URL direkt übergeben, Skript verwendet intern yt-dlp |
| Erneute Ausführung mit anderen Satzzeichen/anderer Segmentierung | --punct-file <Datei> (verwendet automatisch <STEM>.raw.json erneut, Sekunden) oder explizit --from-raw <STEM>.raw.json |
Fallstricke
- Nicht die von babelscribe mitgelieferte
.srt-Ausgabe als fertiges Produkt verwenden – jede Zeile ist ein einzelnes Whisper-Segment ohne Längensteuerung. Die Skripte dieser Fähigkeit haben bereits neu segmentiert. - Nicht den transkribierten Text korrigieren, um „beiläufig Fehler zu korrigieren". Korrekturen gehören in die Übersetzungsebene.
- Reine Musik-/Stille-Dateien geben
ERROR: Transkriptionsergebnis leerzurück – das ist kein Fehler, teile es dem Benutzer einfach mit. - Bei langen Audiodateien (>30 Minuten) sind die Cues in Schritt 3 sehr zahlreich. Übersetze sie in Batches, aber behalte die ID-Übereinstimmung bei. Dass paralleler Agent
okmeldet, bedeutet nicht, dass die Datei wirklich geschrieben wurde – in Tests gab es in 20 Übersetzungsbatches einen, derstatus: okzurückgab, aber die Datei nicht schrieb, und einen, der null zurückgab. Vor dem Abschluss muss mit einem Skript geprüft werden, dass jeder Cue-ID eine Übersetzung zugeordnet ist – vertraue nicht der Selbstdarstellung des Agenten. - Verwende in PowerShell nicht
python -c "...", um Skripte mit Anführungszeichen auszuführen, da Anführungszeichen in der Regel weggelassen werden und es zu Syntaxfehlern (SyntaxError) kommt. Schreibe stattdessen eine.py-Datei und führe diese aus. - Der erste Durchlauf für eine bestimmte Sprache oder bei Verwendung von
--accuratelädt zusätzliche Modelle herunter – das ist normal und dauert seine Zeit.
Selbsttest
Nach Änderungen am Skript mit den festen Testdaten unter examples/ einen Regressionstest durchführen:
powershell -NoProfile -ExecutionPolicy Bypass -File "examples\gen_fixtures.ps1"
python scripts/make_subtitles.py "examples\audio\zh.wav" --outdir "examples\out"
python scripts/make_subtitles.py "examples\audio\en.wav" --outdir "examples\out"
examples\zh.txt / examples\en.txt werden von Windows SAPI in examples\audio\zh.wav / en.wav gesprochen (benötigt die chinesische Sprachausgabe Microsoft Huihui Desktop, in der chinesischen Windows-Version enthalten). Erwartete Werte:
- Chinesisch: 9 Zeilen ohne eingefügte Satzzeichen, davon etwa 6 ohne Satzzeichen am Ende (
PUNCTUATION_LOST=yes); nach dem Einfügen von Satzzeichen wie oben beschrieben: 10 Zeilen, alle enden mit einem Satzzeichen - Englisch: 19 Zeilen, maximale Länge ≤48 Zeichen