专业字幕设计 是做什么的？
将带时间轴的单词转换为竖屏视频的屏幕字幕。状态：已实现并测试通过。
目的
将单词分组为可读的提示，以测量好的行宽进行布局，使用一组小型命名样式进行样式设置，导出 ASS / SRT / WebVTT，并报告布局问题。
支持的输入
- 单词时间轴：JSON 列表，格式为
{"text", "start", "end"}或{"words": [...]}，时间单位为秒。 文本在加载时规范化为 Unicode NFC，确保越南语变音符号能够可靠比较和渲染。 - 可选的关键词列表以进行高亮，以及可选标志用于高亮包含数字的标记。
不包括语音转文字。 单词时间轴必须由调用方提供。
支持的输出
captions.ass（libass 样式，由渲染管线嵌入）captions.srt，captions.vtt（纯文本，供播放器和平台使用）- 问题列表，包含
level（error|warning）、code、message和cue索引
执行
python3 -m uvs.captions examples/demo_caption/words.json --style bold_shorts \
--keywords "cháo,5" --out-dir out/captions
如果存在任何错误级别的问题，退出码为 1。在 Python 中：uvs.captions.build_captions(...)
然后 write_outputs(build, out_dir)。
参数
style：documentary_minimal、bold_shorts、cinematic、emotional_storytelling。 每个样式设置字体、字号、粗细、颜色、轮廓、阴影、底部安全边距（margin_v）、侧边距、最大行数（2）和动画（fade、pop、none）。frame_w、frame_h：默认 1080x1920。SegmentConfig：max_gap（0.45 秒）、max_duration（2.8 秒，目标值）、hard_max_duration（3.4 秒，句子结束可以结束一个最长至此的提示）、min_duration（0.7 秒）。
依赖项
- Python 3.10+，Pillow。
- fontconfig（
fc-match）用于定位字体文件。没有它，将使用 Pillow 的默认字体，宽度检查是近似的。验证器不会报告该回退，因此请确保安装 fontconfig。 - 样式中命名字体族（默认为
Inter）必须安装，供 libass 和 fontconfig 使用。
布局规则
- 宽度使用实际字体文件测量。可用宽度为
frame_w - 2*margin_h - 2*outline。 - 两行拆分通过测量宽度进行平衡，并在标点符号后断句有少量奖励。
- 提示在句子结束、长时间静默、持续时间限制或下一个单词无法在两行内容纳时中断。
- 高亮的关键词使用颜色变化。在
bold_shorts样式中，它们还会短暂放大（pop）。其他单词不会动画，因此并非每个单词都以相同方式移动。 - ASS 覆盖语法（
{、}、\）在用户文本中被替换为相似字符。
示例
examples/demo_caption/words.json 是一个手动计时的越南语占位符。它不匹配真实的叙述。运行演示：python3 -m uvs.render --out out/demo。
约束条件
- 未根据平台字幕规则（例如每个平台的行长或阅读速度限制）进行验证。
too_fast阈值（每秒 22 个字符）是一个启发式值。 - 没有说话者感知样式，没有按语言的行断字典（越南语仅在空格处断行）。
- “Documentary Minimal”、“Bold Shorts”、“Cinematic”、“Emotional Storytelling”已实现。 “Clean Modern”、“Podcast Highlight”和“Educational”未实现。
错误处理
- 空文本、负时间或乱序时间会在加载时引发
ValueError。 - 未知样式会引发
KeyError。 - 布局问题作为问题报告，而不是静默修复：
line_overflow、too_many_lines、overlap、outside_frame、non_positive_duration、empty_cue（错误）；short_cue、long_cue、orphan_word、too_fast、space_before_punctuation、missing_space_after_punctuation、double_space、not_nfc（警告）。 - 存在错误时
render_captioned拒绝渲染。
测试
tests/unit/test_captions.py（加载、布局、分段、验证、导出）。
tests/render/test_pipeline.py::RenderTests 渲染演示并检查尺寸、编解码器、帧率，
以及字幕文本是否到达 ASS 文件。
集成
渲染管线（uvs/render.py）调用 build_captions 和 write_outputs，然后使用
ffmpeg -vf ass=... 将 ASS 文件嵌入。样式和关键词选项直接映射到管线的 CLI。