專業字幕設計 是做什麼的？
將具有時間戳的文字轉換為直式影片的螢幕字幕。狀態：已實作並測試完成。
目的
將單詞分組為可讀的提示行，以測量的行寬進行排版，為小型命名風格集合設定樣式，匯出 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 檔案。風格和關鍵字選項直接對應到管線的命令列介面。