professional-caption-design

Que fait professional-caption-design ?

Transforme des mots chronométrés en sous-titres vidéo pour des vidéos verticales. Statut : implémenté et testé.

Objectif

Grouper les mots en répliques lisibles, les disposer avec des largeurs de ligne mesurées, les styliser avec un petit ensemble d'apparences nommées, exporter en ASS / SRT / WebVTT et signaler les problèmes de disposition.

Entrées prises en charge

• Horodatages des mots : liste JSON de {"text", "start", "end"} ou {"words": [...]}, les temps en secondes. Le texte est normalisé en Unicode NFC au chargement, de sorte que les diacritiques vietnamiennes se comparent et s'affichent de manière fiable.
• Liste facultative de mots-clés à surligner, et un indicateur facultatif pour surligner les jetons contenant des chiffres.

La reconnaissance vocale n'est pas incluse. Les horodatages des mots doivent provenir de l'appelant.

Sorties prises en charge

• captions.ass (stylisé avec libass, intégré par le pipeline de rendu)
• captions.srt, captions.vtt (texte brut, pour les lecteurs et les plateformes)
• Une liste de problèmes avec level (error | warning), code, message, et l'index cue

Exécution

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

Le code de sortie est 1 si un problème de niveau erreur existe. En Python : uvs.captions.build_captions(...) puis write_outputs(build, out_dir).

Paramètres

• style : documentary_minimal, bold_shorts, cinematic, emotional_storytelling. Chaque style définit la police, la taille, le poids, les couleurs, le contour, l'ombre, la marge de sécurité inférieure (margin_v), la marge latérale, le nombre maximum de lignes (2) et l'animation (fade, pop, none).
• frame_w, frame_h : par défaut 1080x1920.
• SegmentConfig : max_gap (0,45 s), max_duration (2,8 s, cible), hard_max_duration (3,4 s, une fin de phrase peut terminer une réplique jusqu'à cette valeur), min_duration (0,7 s).

Dépendances

• Python 3.10+, Pillow.
• fontconfig (fc-match) pour localiser le fichier de police. Sans lui, la police par défaut de Pillow est utilisée et les vérifications de largeur sont approximatives. Le validateur ne signale pas ce repli, alors gardez fontconfig installé.
• La famille de polices nommée dans le style (par défaut Inter) doit être installée pour libass et fontconfig.

Règles de disposition

• Les largeurs sont mesurées avec le fichier de police réel. La largeur utilisable est frame_w - 2*margin_h - 2*outline.
• Les coupures sur deux lignes sont équilibrées par la largeur mesurée, avec un petit bonus pour la coupure après une ponctuation.
• Les répliques sont coupées aux fins de phrase, aux silences longs, aux limites de durée, ou lorsque le mot suivant ne tiendrait pas sur deux lignes.
• Les mots-clés surlignés utilisent un changement de couleur. Dans le style bold_shorts, ils sont également agrandis brièvement (pop). Les autres mots ne sont pas animés, donc tous les mots ne bougent pas de la même manière.
• La syntaxe de remplacement ASS ({, }, \) dans le texte utilisateur est remplacée par des caractères similaires.

Exemples

examples/demo_caption/words.json est un espace réservé vietnamien chronométré à la main. Il ne correspond pas à une narration réelle. Exécutez la démo : python3 -m uvs.render --out out/demo.

Contraintes

• Non validé par rapport aux règles de sous-titrage des plateformes (par exemple les limites de longueur par ligne ou de vitesse de lecture de chaque plateforme). Le seuil too_fast (22 caractères par seconde) est heuristique.
• Pas de styles par locuteur, ni de dictionnaires de coupure de ligne par langue (le vietnamien coupe uniquement aux espaces).
• "Documentaire Minimal", "Bold Shorts", "Cinématique", "Narrative Émotionnelle" sont implémentés. "Moderne Propre", "Podcast Highlight" et "Éducatif" ne le sont pas.

Gestion des erreurs

• Texte vide, temps négatifs ou temps dans le désordre lèvent ValueError lors du chargement.
• Style inconnu lève KeyError.
• Les problèmes de disposition sont signalés comme des anomalies plutôt que corrigés silencieusement : line_overflow, too_many_lines, overlap, outside_frame, non_positive_duration, empty_cue (erreurs) ; short_cue, long_cue, orphan_word, too_fast, space_before_punctuation, missing_space_after_punctuation, double_space, not_nfc (avertissements).
• render_captioned refuse le rendu lorsqu'il y a des erreurs.

Tests

tests/unit/test_captions.py (chargement, disposition, segmentation, validation, export). tests/render/test_pipeline.py::RenderTests effectue le rendu de la démo et vérifie les dimensions, les codecs, le taux d'images, et que le texte des sous-titres atteigne le fichier ASS.

Intégration

Le pipeline de rendu (uvs/render.py) appelle build_captions et write_outputs, puis intègre le fichier ASS avec ffmpeg -vf ass=.... Les options de style et de mots-clés se mappent directement sur l'interface en ligne de commande du pipeline.