professionelles-Untertitel-Design

Was macht professionelles-Untertitel-Design?

Verwandelt zeitlich gesteuerte Wörter in Bildschirmuntertitel für vertikale Videos. Status: implementiert und getestet.

Zweck

Wörter in lesbare Blöcke gruppieren, sie mit gemessenen Zeilenbreiten anordnen, in einer kleinen Reihe von benannten Looks stylen, ASS / SRT / WebVTT exportieren und Layout-Probleme melden.

Unterstützte Eingaben

• Wortzeitsteuerung: JSON-Liste von {"text", "start", "end"} oder {"words": [...]}, Zeiten in Sekunden. Text wird beim Laden auf Unicode NFC normalisiert, sodass vietnamesische Diakritika zuverlässig verglichen und dargestellt werden.
• Optionale Liste von Schlüsselwörtern zum Hervorheben sowie ein optionales Flag, um Token hervorzuheben, die Ziffern enthalten.

Spracherkennung ist nicht enthalten. Wortzeitsteuerung muss vom Aufrufer bereitgestellt werden.

Unterstützte Ausgaben

• captions.ass (libass-gestylt, von der Render-Pipeline eingebrannt)
• captions.srt, captions.vtt (Klartext, für Player und Plattformen)
• Eine Liste von Problemen mit level (error | warning), code, message und cue-Index

Ausführung

python3 -m uvs.captions examples/demo_caption/words.json --style bold_shorts \
  --keywords "cháo,5" --out-dir out/captions

Der Exit-Code ist 1, wenn Fehler-Level-Probleme vorliegen. In Python: uvs.captions.build_captions(...) dann write_outputs(build, out_dir).

Parameter

• style: documentary_minimal, bold_shorts, cinematic, emotional_storytelling. Jeder Style legt Schriftart, Größe, Gewicht, Farben, Kontur, Schatten, unteren Sicherheitsabstand (margin_v), seitlichen Rand, maximale Zeilen (2) und Animation (fade, pop, none) fest.
• frame_w, frame_h: Standard 1080x1920.
• SegmentConfig: max_gap (0,45 s), max_duration (2,8 s, Zielwert), hard_max_duration (3,4 s, ein Satzende darf einen Block bis zu dieser Dauer abschließen), min_duration (0,7 s).

Abhängigkeiten

• Python 3.10+, Pillow.
• fontconfig (fc-match), um die Schriftartdatei zu lokalisieren. Ohne fontconfig wird die Standardschriftart von Pillow verwendet und die Breitenprüfungen sind ungefähr. Der Validator meldet diesen Fallback nicht, also stellen Sie sicher, dass fontconfig installiert ist.
• Die im Style genannte Schriftfamilie (Standard Inter) muss für libass und fontconfig installiert sein.

Layout-Regeln

• Breiten werden mit der tatsächlichen Schriftartdatei gemessen. Die nutzbare Breite beträgt frame_w - 2*margin_h - 2*outline.
• Zweizeilige Aufteilungen werden durch die gemessene Breite ausgeglichen, mit einem kleinen Bonus für einen Zeilenumbruch nach Satzzeichen.
• Blöcke werden an Satzenden, langen Pausen, den Dauerlimits oder gebrochen, wenn das nächste Wort nicht in zwei Zeilen passen würde.
• Hervorgehobene Schlüsselwörter erhalten einen Farbwechsel. Im bold_shorts-Style werden sie kurzzeitig auch vergrößert (pop). Andere Wörter animieren nicht, sodass sich nicht jedes Wort gleich bewegt.
• ASS-Override-Syntax ({, }, \) im Benutzertext wird durch ähnlich aussehende Zeichen ersetzt.

Beispiele

examples/demo_caption/words.json ist ein manuell getimter vietnamesischer Platzhalter. Er entspricht keiner echten Erzählung. Führen Sie die Demo aus: python3 -m uvs.render --out out/demo.

Einschränkungen

• Nicht gegen Plattform-Untertitelregeln validiert (z. B. die Zeilenlängen- oder Lesegeschwindigkeitslimits der einzelnen Plattformen). Der too_fast-Schwellenwert (22 Zeichen pro Sekunde) ist ein Heuristikwert.
• Keine sprecherbezogenen Stile, keine sprachspezifischen Zeilenumbruchwörterbücher (Vietnamesisch bricht nur an Leerzeichen um).
• „Documentary Minimal“, „Bold Shorts“, „Cinematic“, „Emotional Storytelling“ sind implementiert. „Clean Modern“, „Podcast Highlight“ und „Educational“ sind nicht implementiert.

Fehlerbehandlung

• Leerer Text, negative Zeiten oder Zeiten außerhalb der Reihenfolge werfen beim Laden einen ValueError.
• Unbekannter Style wirft einen KeyError.
• Layout-Probleme werden als Issues gemeldet, nicht stillschweigend korrigiert: line_overflow, too_many_lines, overlap, outside_frame, non_positive_duration, empty_cue (Fehler); short_cue, long_cue, orphan_word, too_fast, space_before_punctuation, missing_space_after_punctuation, double_space, not_nfc (Warnungen).
• render_captioned weigert sich zu rendern, wenn Fehler vorliegen.

Tests

tests/unit/test_captions.py (Laden, Layout, Segmentierung, Validierung, Export). tests/render/test_pipeline.py::RenderTests rendert die Demo und überprüft Abmessungen, Codecs, Bildrate und ob der Untertiteltext die ASS-Datei erreicht.

Integration

Die Render-Pipeline (uvs/render.py) ruft build_captions und write_outputs auf und brennt dann die ASS- Datei mit ffmpeg -vf ass=... ein. Die Style- und Keyword-Optionen werden direkt auf die CLI der Pipeline abgebildet.