auto-subtitle – Automatische Untertitelung mit SubtitleCue-Ausg…

auto-subtitle — Automatische Transkription von Audio/Video in SubtitleCue mit einem Befehl

Ein Befehl, Untertitel: Audio-/Videodatei rein, <Name>.cues.json + <Name>.srt raus. Datenvertrag ist zeichengenau an das SubtitleCue-Schema von video-motion angelehnt: {start, end, text} – Sekunden, 3 Nachkommastellen, einzeiliger Text (lange Sätze bereits geteilt) – das subtitles-Array kann direkt in die video-motion-Zeitleiste eingefügt werden.

Schritt 1 · Material und Sprache bestätigen

• mp4 / wav / flac werden unterstützt (PyAV liest direkt). Bei Dekodierungsfehlern → zuerst transcodieren: ffmpeg -i in.mp4 -vn -ac 1 -ar 16000 out.wav
• Sprache bestätigen und --lang übergeben: zh (Standard) / en usw. (Whisper-Sprachcodes)
• Reine Musik-/Soundeffektdateien nicht ausführen: VAD filtert leere oder extrem kurze Ergebnisse heraus (das ist ein Feature, kein Fehler)
• Falls bekanntes Textmaterial (Sprechertext, Drehbuch, Originaltext) vorhanden ist: vorher als UTF-8 sichern – Grundlage für den L2-Abgleich in Schritt 3, um eine Drift der Referenz zu vermeiden

Schritt 2 · Transkription ausführen

Das venv wird nicht versioniert (Build-Ergebnis mit ~284 MB, .gitignore deckt .venv/ bereits ab). Dieses Repository verwendet die Konvention, dass Skills keine Build-Artefakte enthalten, analog zu node_modules. Daher wird das venv außerhalb des Repos erstellt und von allen Projekten gemeinsam genutzt:

python -m venv "$env:USERPROFILE\.cache\vibe-studio\asr-venv"
& "$env:USERPROFILE\.cache\vibe-studio\asr-venv\Scripts\python.exe" -m pip install -r skills/auto-subtitle/templates/asr/requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

cd skills/auto-subtitle/templates/asr
& "$env:USERPROFILE\.cache\vibe-studio\asr-venv\Scripts\python.exe" transcribe.py <Eingabe.mp4|wav> --outdir <Ausgabeverzeichnis>

• Modell standardmäßig large-v3-turbo (~1,6 GB, wird beim ersten Lauf automatisch heruntergeladen, gute Qualität für Chinesisch); für schnelle Tests --model small (~484 MB). Modelle werden in ~/.cache/huggingface zwischengespeichert, einmaliger Download, global wiederverwendet
• Bei Modell-Download-Fehlern HF_ENDPOINT umstellen: Standard ist offizielle Direktverbindung (Stand 2026-08 funktionierend); Alternative z.B. $env:HF_ENDPOINT="https://hf-mirror.com" (Hinweis: Dieser Mirror kann unter hub 1.x 308-Rückfall-Kompatibilitätsprobleme haben, daher offizielle Quelle bevorzugen)
• stdout enthält eine englische Zusammenfassung in einer Zeile: segments=N cues=M total_audio=... model=... lang=... out=...; exit 0 = Erfolg, 1 = Fehler

Schritt 3 · Drei Überprüfungsstufen (obligatorisch, nicht überspringbar)

L1 Programmebene: JSON mit json.load ladbar; subtitles ein Array, jedes Element hat genau die drei Felder start/end/text; start < end und über Einträge hinweg monoton nicht fallend; Werte auf 3 Nachkommastellen; letzter Eintrag end ≤ ffprobe-Dauer + 1s. SRT-Zeitstempelzeilen entsprechen HH:MM:SS,mmm --> HH:MM:SS,mmm, Nummerierung fortlaufend ab 1.

L2 Genauigkeit: Bei vorhandenem Referenztext → Vergleich mit difflib.SequenceMatcher (beide Seiten zuerst ohne Satzzeichen/Leerzeichen, normalisiert); Gesamtähnlichkeit ≥0.85, Satzweise ≥0.70 (für zusammenhängende Cue-Fenster max nehmen, um Teilungen/Zusammenfassungen abzudecken); ohne Referenztext → Stichprobenartiges Hören von Anfang/Mitte/Ende zur Überprüfung.

L2.5 Zeitleiste (Standardprüfung): Untertitelfenster müssen mit den Wort-Zeitfenstern übereinstimmen. Stille zwischen Sätzen darf nicht mit Untertiteln belegt sein. – Lücken zwischen benachbarten Cues prüfen: Zwischen Sätzen sollte eine echte Stille von >1s auftreten (Lücke = 0 bei Satzteilung ist normal); keine Fragmente <0,3s; erster cue startet am Beginn der Sprachaktivität; letzter cue endet nicht vor der Endstille. Das Skript intern verwendet bereits Wort-Zeitstempel (Start des ersten Worts / Ende des letzten Worts) zur Fensterbestimmung; dieser Schritt dient der Ergebnisvalidierung.

L3 Fazitzeile: Alle bestanden = ALL GREEN; bei roten Punkten → Teilung neu einstellen / VAD-Parameter anpassen und erneut prüfen; bei 2 aufeinanderfolgenden roten Runden → anhalten und melden, kein blindes Optimieren.

Schritt 4 · Auslieferung

• Bericht: Absoluter Pfad der cues.json + Anzahl der Cues + Audiolänge + Modell/Sprache + Ergebnis der dreistufigen Überprüfung
• Anbindung an video-motion: subtitles-Array direkt in die video-motion-Projekt-Datei src/cues.ts in cues.subtitles einfügen – sofort verwendbar, keine Feldkonvertierung nötig
• Ausdrücklich nicht Bestandteil (kommt in späteren Versionen): Sprecherdiarisierung, Export von Wort-Zeitstempeln, Übersetzung, TTS-Vertonung

Schritt 5 · Wiederholbaren Befehl dokumentieren

Am Ende des Auslieferungsberichts den vollständigen wiederholbaren Befehl angeben (Eingabepfad / --lang / --outdir / --model), damit nachfolgende Sitzungen oder andere Personen genau reproduzieren können; Ergebnisse (cues.json / srt) im Ausgabebereich ablegen (dieses Repo: products/, bei Cross-Repo: Projektstamm output/), nicht in git – der Befehl ist das Asset.

Grenzen und Stolpersteine

• GBK-Konsole: Skript gibt alles auf Englisch aus; Dateien explizit mit encoding="utf-8" schreiben, JSON mit ensure_ascii=False
• Teilungsregel: Einzelne Cues >20 Zeichen werden an Satzzeichen (。！？；，、) geteilt; wenn im Fenster keine Satzzeichen, dann harter Bruch und das letzte Fragment mindestens 3 Zeichen (um 1-Zeichen-Fragmente zu vermeiden); Fragmente <0,3s werden an den vorherigen Cue angehängt, ohne das 20-Zeichen-Limit zu überschreiten
• Wort-Zeitstempel sind die einzig korrekte Quelle für Untertitelfenster – Satz-Zeitstempel würden Stille zwischen Sätzen verschlucken, sodass Untertitel etwa eine Stille-Periode zu früh erscheinen (bereits korrigiert, nicht auf word_timestamps=False zurückfallen)
• CPU-Int8-Inferenz: 28s Audio → Ergebnis in etwa 1 Minute; längere Audios proportional; erster Lauf von large-v3-turbo inkl. Download, daher ausreichend Timeout einplanen
• Bei chinesischer Erkennung werden Zahlen oft in arabische Ziffern umgewandelt („zwei hundert Millisekunden“ → „200ms“); dies ist ein normaler Unterschied beim L2-Vergleich und kein Erkennungsfehler

Auslieferungsanschluss

SRT/cues zusammen mit der ursprünglichen Audio-/Videoquelle und der Modellversion archivieren; nicht nur das untertitelte mp4 abliefern. Bei Auslieferung eines Videos mit media-qc die Untertitelfenster gegen die tatsächliche Länge prüfen; Genauigkeit weiterhin anhand bekannter Skripte oder Stichprobenhören prüfen. Standardmäßiger Modell-Download und lokale Inferenz ersetzen keine manuelle Vertonung.