captions

Was macht captions?

Lokale Wort-für-Wort-Transkription, Styling und Einbrennen von Kurzform-Untertiteln.

Skripte befinden sich in scripts/:

Skript	Aufgabe
transcribe.py	faster-whisper mit word_timestamps=True → words.json (gecached)
make-captions.mjs	words.json → ASS (gestylt, aktives Wort hervorgehoben) und SRT
burn.mjs	Brennt ASS/SRT mit libass (ass / subtitles Filter) ein
snap-to-words.mjs	Verschiebt Schnittpunkte zur nächstgelegenen Lücke zwischen Wörtern

Arbeitsablauf

1. Transkribieren (einmal pro Quelle; das Ergebnis wird gecached):

   pip install faster-whisper            # einmalig
   python3 scripts/transcribe.py --input clip.mp4 --out edit/clip.words.json --model small --language en
   

   Beim ersten Lauf wird das Modell von Hugging Face heruntergeladen. Falls dies blockiert ist, beendet sich das Skript mit Exit-Code 4 und einer JSON-fix-Nachricht anstelle eines Tracebacks; es schreibt niemals ein gefälschtes Transkript. Leite --model auf einen lokalen CTranslate2-Modellordner, um offline zu arbeiten.
2. Untertitel erstellen:

   node scripts/make-captions.mjs --words edit/clip.words.json --out-ass edit/clip.ass --out-srt edit/clip.srt
   

   Der Stil stammt aus dem Brand-Pack (captions-Block: Größe, Rand, Umriss, Hervorhebung; colors.accent ist die Farbe des aktiven Wortes).
3. Einbrennen als letzten visuellen Schritt:

   node scripts/burn.mjs --input edit/clip-hook.mp4 --subs edit/clip.ass --out edit/clip-captioned.mp4
   

   Verwende --fonts-dir, wenn die Untertitel-Schriftart eine Datei ist und keine installierte Schriftart.
4. Überprüfen mit einem render-qc-Proof-Sheet: lesbar, innerhalb des sicheren Bereichs, nicht über der Hook-Platte.

Regeln

• Schneide niemals innerhalb eines Wortes. Vor dem Aufteilen von Sprache, setze Schnitte auf Wortlücken zurück: node scripts/snap-to-words.mjs --words edit/clip.words.json --markers edit/cuts.json --out edit/cuts.json
• Untertitel kommen zuletzt: nach Schnitten, Overlays und Farbe. Wenn du den Clip nach der Transkription zuschneidest, übergib --offset -<Sekunden abgeschnitten> an make-captions.mjs.
• 1 bis 3 Wörter pro Block für Kurzvideos (maxWords, maxChars). Blöcke brechen an Satzzeichen und bei Pausen.
• Halte Untertitel aus den unteren ~15 % (Plattform-UI) und fern von der Hook-Platte: stimme captions.marginV ab.
• Transkripte werden gecached: führe erneut mit --force aus, nur wenn sich das Audio geändert hat.
• Überprüfe Wörter stichprobenartig mit dem Audio; Whisper kann Namen und Fachbegriffe falsch verstehen. Korrigiere words.json bei Bedarf von Hand.

Ohne ffmpeg libass

Wenn burn.mjs keinen ass-Filter meldet, fehlt dem ffmpeg-Build libass. Installiere einen vollständigen Build (die meisten Paketmanager liefern einen), oder lade die SRT als separaten Untertitel-Track hoch anstatt sie einzubrennen.