professional-caption-design

¿Qué hace professional-caption-design?

Convierte palabras temporizadas en subtítulos visibles para video vertical. Estado: implementado y probado.

Propósito

Agrupar palabras en fragmentos legibles, disponerlos con anchos de línea medidos, estilizarlos en un conjunto reducido de apariencias nombradas, exportar ASS / SRT / WebVTT y reportar problemas de maquetación.

Entradas admitidas

• Temporización de palabras: lista JSON de {"text", "start", "end"} o {"words": [...]}, tiempos en segundos. El texto se normaliza a Unicode NFC al cargar, por lo que los diacríticos vietnamitas se comparan y renderizan de forma fiable.
• Lista opcional de palabras clave para resaltar, y un indicador opcional para resaltar tokens que contienen dígitos.

El reconocimiento de voz no está incluido. Las temporizaciones de palabras deben ser proporcionadas por el llamante.

Salidas admitidas

• captions.ass (con estilo libass, quemado por el pipeline de renderizado)
• captions.srt, captions.vtt (texto plano, para reproductores y plataformas)
• Una lista de problemas con level (error | warning), code, message e índice de cue

Ejecución

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

El código de salida es 1 si existe algún problema de nivel error. En Python: uvs.captions.build_captions(...) luego write_outputs(build, out_dir).

Parámetros

• style: documentary_minimal, bold_shorts, cinematic, emotional_storytelling. Cada estilo define fuente, tamaño, peso, colores, contorno, sombra, margen inferior seguro (margin_v), margen lateral, máximo de líneas (2) y animación (fade, pop, none).
• frame_w, frame_h: valor predeterminado 1080x1920.
• SegmentConfig: max_gap (0.45 s), max_duration (2.8 s, objetivo), hard_max_duration (3.4 s, un final de oración puede completar un fragmento hasta este límite), min_duration (0.7 s).

Dependencias

• Python 3.10+, Pillow.
• fontconfig (fc-match) para localizar el archivo de fuente. Sin él, se usa la fuente predeterminada de Pillow y las comprobaciones de ancho son aproximadas. El validador no informa sobre esa fallback, así que mantén instalado fontconfig.
• La familia de fuentes nombrada en el estilo (por defecto Inter) debe estar instalada para libass y fontconfig.

Reglas de maquetación

• Los anchos se miden con el archivo de fuente real. El ancho utilizable es frame_w - 2*margin_h - 2*outline.
• Las divisiones de dos líneas se equilibran por ancho medido, con una pequeña bonificación por cortar después de puntuación.
• Los fragmentos se cortan en finales de oración, silencios largos, los límites de duración, o cuando la siguiente palabra no cabría en dos líneas.
• Las palabras clave resaltadas utilizan un cambio de color. En el estilo bold_shorts también aumentan de tamaño brevemente (pop). Otras palabras no se animan, por lo que no todas las palabras se mueven de la misma manera.
• La sintaxis de anulación de ASS ({, }, \) en el texto de usuario se reemplaza con caracteres similares.

Ejemplos

examples/demo_caption/words.json es un marcador de posición vietnamita con tiempos manuales. No coincide con una narración real. Ejecuta la demostración: python3 -m uvs.render --out out/demo.

Restricciones

• No validado contra reglas de subtítulos de plataformas (por ejemplo, los límites de longitud de línea o velocidad de lectura de cada plataforma). El umbral too_fast (22 caracteres por segundo) es una heurística.
• No hay estilos por hablante, ni diccionarios de salto de línea por idioma (el vietnamita solo se divide en espacios).
• "Documentary Minimal", "Bold Shorts", "Cinematic" y "Emotional Storytelling" están implementados. "Clean Modern", "Podcast Highlight" y "Educational" no lo están.

Manejo de errores

• Texto vacío, tiempos negativos o tiempos fuera de orden generan ValueError al cargar.
• Estilo desconocido genera KeyError.
• Los problemas de maquetación se reportan como problemas en lugar de corregirse silenciosamente: line_overflow, too_many_lines, overlap, outside_frame, non_positive_duration, empty_cue (errores); short_cue, long_cue, orphan_word, too_fast, space_before_punctuation, missing_space_after_punctuation, double_space, not_nfc (advertencias).
• render_captioned se niega a renderizar cuando hay errores.

Pruebas

tests/unit/test_captions.py (carga, maquetación, segmentación, validación, exportación). tests/render/test_pipeline.py::RenderTests renderiza la demostración y verifica dimensiones, códecs, velocidad de fotogramas y que el texto de los subtítulos llegue al archivo ASS.

Integración

El pipeline de renderizado (uvs/render.py) llama a build_captions y write_outputs, luego quema el archivo ASS con ffmpeg -vf ass=.... Las opciones de estilo y palabras clave se asignan directamente a la CLI del pipeline.