professional-caption-design

O que professional-caption-design faz?

Transforma palavras temporizadas em legendas na tela para vídeos verticais. Status: implementado e testado.

Propósito

Agrupar palavras em blocos de leitura, organizá-los com larguras de linha medidas, estilizá-los em um conjunto pequeno de estilos nomeados, exportar ASS / SRT / WebVTT e relatar problemas de layout.

Entradas suportadas

• Temporizações de palavras: Lista JSON de {"text", "start", "end"} ou {"words": [...]}, tempos em segundos. O texto é normalizado para Unicode NFC ao carregar, para que diacríticos vietnamitas sejam comparados e renderizados de forma confiável.
• Lista opcional de palavras-chave para destacar, e uma flag opcional para destacar tokens que contenham dígitos.

Reconhecimento de fala não está incluído. Os timestamps das palavras devem vir do chamador.

Saídas suportadas

• captions.ass (estilizado com libass, queimado pelo pipeline de renderização)
• captions.srt, captions.vtt (texto simples, para players e plataformas)
• Uma lista de problemas com level (error | warning), code, message e índice do bloco (cue)

Execução

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

Código de saída é 1 se houver algum problema de nível erro. Em Python: uvs.captions.build_captions(...) em seguida write_outputs(build, out_dir).

Parâmetros

• style: documentary_minimal, bold_shorts, cinematic, emotional_storytelling. Cada estilo define fonte, tamanho, peso, cores, contorno, sombra, margem inferior de segurança (margin_v), margem lateral, máximo de linhas (2) e animação (fade, pop, none).
• frame_w, frame_h: padrão 1080x1920.
• SegmentConfig: max_gap (0.45 s), max_duration (2.8 s, alvo), hard_max_duration (3.4 s, o fim de uma frase pode finalizar um bloco até esse valor), min_duration (0.7 s).

Dependências

• Python 3.10+, Pillow.
• fontconfig (fc-match) para localizar o arquivo de fonte. Sem ele, a fonte padrão do Pillow é usada e as verificações de largura são aproximadas. O validador não reporta essa substituição, então mantenha fontconfig instalado.
• A família de fontes nomeada no estilo (padrão Inter) deve estar instalada para libass e fontconfig.

Regras de layout

• As larguras são medidas com o arquivo de fonte real. A largura utilizável é frame_w - 2*margin_h - 2*outline.
• Divisões de duas linhas são balanceadas pela largura medida, com um pequeno bônus para quebrar após pontuação.
• Os blocos quebram em finais de frase, pausas longas, nos limites de duração, ou quando a próxima palavra não caberia em duas linhas.
• Palavras-chave destacadas usam uma mudança de cor. No estilo bold_shorts elas também escalam brevemente (pop). Outras palavras não animam, então nem toda palavra se move da mesma forma.
• A sintaxe de substituição do ASS ({, }, \) no texto do usuário é substituída por caracteres semelhantes.

Exemplos

examples/demo_caption/words.json é um placeholder vietnamita temporizado manualmente. Não corresponde a narração real. Execute a demonstração: python3 -m uvs.render --out out/demo.

Restrições

• Não validado contra regras de legendas de plataforma (por exemplo, limites de comprimento de linha ou velocidade de leitura de cada plataforma). O limite too_fast (22 caracteres por segundo) é heurístico.
• Sem estilos por locutor, sem dicionários de quebra de linha por idioma (vietnamita quebra apenas em espaços).
• "Documentary Minimal", "Bold Shorts", "Cinematic", "Emotional Storytelling" estão implementados. "Clean Modern", "Podcast Highlight" e "Educational" não estão.

Tratamento de erros

• Texto vazio, tempos negativos ou tempos fora de ordem geram ValueError ao carregar.
• Estilo desconhecido gera KeyError.
• Problemas de layout são reportados como problemas em vez de corrigidos silenciosamente: line_overflow, too_many_lines, overlap, outside_frame, non_positive_duration, empty_cue (erros); short_cue, long_cue, orphan_word, too_fast, space_before_punctuation, missing_space_after_punctuation, double_space, not_nfc (avisos).
• render_captioned se recusa a renderizar quando há erros.

Testes

tests/unit/test_captions.py (carregamento, layout, segmentação, validação, exportação). tests/render/test_pipeline.py::RenderTests renderiza a demonstração e verifica dimensões, codecs, taxa de quadros, e que o texto da legenda chega ao arquivo ASS.

Integração

O pipeline de renderização (uvs/render.py) chama build_captions e write_outputs, em seguida queima o arquivo ASS com ffmpeg -vf ass=.... As opções de estilo e palavra-chave mapeiam diretamente para a CLI do pipeline.