Subtitle Studio - 動態字幕生成工具

SKILL: Subtitles Studio — 動態字幕模組化函式庫 (subtitles_studio)

1. 給 AI 的總覽

官方儲存庫：https://github.com/NicolasCoder/subtitles_studio.git

這個資料夾是一個完全獨立且可分享的工具箱，用於為 HyperFrames (1080x1920 @ 30fps) 生成 Lockup 風格的動態字幕（一個巨大的中央主要詞彙，加上嵌入在字型實際上升/下降空隙中的較小詞彙）。

資料夾架構

subtitles_studio/
├── SKILL.md                        # 此完整指南（給 AI 代理使用）
├── README.md                       # 給人類使用的快速指南
├── requirements.txt                # fonttools, brotli, Pillow, numpy
├── cli.py                          # 立即可用的命令列介面
├── fonts/                          # 預先打包的本機 .woff2 字型（+ 從 Google Fonts 自動下載）
├── caption_kit/                    # 可匯入的 Python 套件
│   ├── __init__.py                 # 公開 API
│   ├── nesting.py                  # 真實字型幾何引擎 + 自動下載 Google Fonts
│   ├── grouper.py                  # 智慧逐詞分組器（停留 >= 0.38 秒，防閃爍）
│   ├── renderer.py                 # HTML/CSS/GSAP 編譯器，以及 styles/ 資料夾的動態載入器
│   └── transcribe.py               # 逐詞轉錄（CrisperWhisper / faster-whisper / whisper）
├── styles/                         # 樣式模組（1 個 .py 或 .json 檔案 = 1 個可分享的樣式！）
│   ├── _TEMPLATE_NOVO_ESTILO.py    # 附有註解的範本，用於建立新樣式
│   ├── bold_ciano.py               # 粗體社群 — 青色 (#3de0c8)
│   ├── bold_vermelho.py            # 粗體社群 — 紅色 (#ff3355)
│   ├── bold_roxo.py                # 粗體社群 — 紫色 (#b855ff)
│   ├── bold_dourado.py             # 粗體社群 — 金色 (#ffd24a)
│   ├── editorial.py                # 編輯混合 (Inter 900 + Playfair Display Italic)
│   ├── gold_script.py              # 金色手寫 (Pinyon Script + Oswald)
│   └── poster_impact.py            # 海報衝擊 (League Gothic + Montserrat 900)
└── examples/                       # 可立即測試的範例（葡萄牙語）
    ├── demo_words_pt.json          # 帶時間戳的詞彙（葡萄牙語）
    └── demo_groups_pt.json         # Lockup 或一般分組（葡萄牙語）

---

2. 如何透過命令列使用 (cli.py)

# 1. 列出 styles/ 中所有已安裝的樣式
python cli.py --list-styles

# 2. 為任何樣式產生快速示範
python cli.py --demo --style bold_roxo

# 3. 從帶時間戳的詞彙 JSON 檔案產生（word, start, end）
python cli.py --words examples/demo_words_pt.json --style bold_vermelho --out output/meu_teste

# 4. 即時切換強調色，無需編輯樣式檔案
python cli.py --words examples/demo_words_pt.json --style bold_ciano --accent "#00ff88"

# 5. 轉錄影片/音訊 (.mp4/.wav/.mp3) 並直接產生同步字幕
python cli.py --media meu_video.mp4 --lang pt --style bold_dourado --video meu_video.mp4

---

3. 如何透過 Python 使用（嵌入 HyperFrames 專案）

當你在 HyperFrames 中組裝完整組合（包含 A-roll、B-roll、動畫、音效和音樂）時，請匯入 caption_kit 並使用 render_embeddable()：

import sys
sys.path.insert(0, "路徑/至/legendas_dinamicas_kit")

from caption_kit import build_groups_from_words, render_embeddable

# 1. `words` 是一個列表 [{"word": "Criar", "start": 0.15, "end": 0.42}, ...]
groups = build_groups_from_words(words, min_hold=0.38)

# 2. 產生 CSS、DOM（內含 <span> 以達到 lint 零警告）和 GSAP JavaScript：
caps_css, caps_dom, caps_js, report = render_embeddable(
    groups,
    prefix="v1",                 # 唯一 ID 前綴（#v1-g0, #v1-g1...）
    style_name="bold_vermelho",  # styles/<名稱>.py 中的任何檔案
    accent_override=None,        # 或傳入例如 "#ff3355" 僅切換顏色
    y_lockup=0.74,               # Instagram Reels 安全範圍（1080x1920 中約 1300-1560px）
    y_plain=0.75,
    track_index=3,
    z_index=95,
)

之後只需注入：

• 將 {caps_css} 放入組合的 <style> 標籤中；
• 將 {caps_dom} 放入 <div id="root" ...> 中；
• 將 {caps_js} 放入 const tl = gsap.timeline({ paused: true }); 之後的 <script> 標籤中。

---

4. 如何建立新的可分享樣式（styles/ 中的外掛系統）

此樣式系統設計為完全即插即用：

• 放置在 styles/ 資料夾中的每個 .py（或 .json）檔案（名稱不以 _ 開頭）都會被 load_styles() 自動發現。
• 要根據使用者要求建立新樣式，請遵循以下步驟：
  1. 將 styles/_TEMPLATE_NOVO_ESTILO.py 複製為 styles/<樣式名稱>.py。
  2. 編輯 STYLE = { ... } 字典。
  3. 如果你使用 Google Fonts 的新字型（例如 "Bebas Neue"、"Poppins"、"Syne"），無需手動下載：caption_kit/nesting.py 引擎會在首次執行時自動從 Google Fonts 下載 .woff2 檔案，並儲存在 fonts/<字型家族>/ 中！
  4. 使用者要與他人分享此樣式時，只需傳送這個單一檔案 styles/<樣式名稱>.py 即可！

STYLE 字典的結構

STYLE = {
    "id": "neon_cyber",
    "label": "Neon Cyber (Montserrat 900 + 綠色 Glow)",
    # 主要詞彙（lockup 中央）
    "main_font": "Montserrat",
    "main_weight": 900,
    "main_style": "normal",
    "main_track": -0.05,
    "main_case": "none",           # 重要：使用 "none" 以保留上升/下降部分並允許嵌入！僅在 "nest_mode": "overlap" 時使用 "upper"。
    "main_lh": 0.80,
    "main_css": "color:#ffffff;text-shadow:0 10px 34px rgba(0,0,0,.6);",
    "max_px": 280,
    # 輔助小詞彙（上方和下方）
    "small_font": "Inter",
    "small_weight": 800,
    "small_style": "normal",
    "small_track": -0.03,
    "small_case": "none",
    "small_css": "color:#ffffff;text-shadow:0 5px 20px rgba(0,0,0,.6);",
    "small_scale": 0.44,           # 主要詞彙大小的 0.25 到 0.50
    # 簡單連續字幕
    "plain_font": "Inter",
    "plain_weight": 800,
    "plain_style": "normal",
    "plain_case": "none",
    "plain_css": "color:#ffffff;text-shadow:0 5px 20px rgba(0,0,0,.6);",
    # 強調色和光澤效果
    "accent": "#00ff88",
    "accent_extra_css": "text-shadow:0 0 24px rgba(0,255,136,0.55);",
    "shine": ("#ffffff", "rgba(0,255,136,.9)"),
    # 幾何和動畫
    "tilt": (-2, 2),               # 上方和下方行的傾斜角度（度）
    "clear": 0.03,                 # 字型間的最小間距
    "variants": ("slam", "letters", "rise", "blur"),
}

---

5. 品質黃金規則（從實際生產中學到的）

1. 閱讀時間（最小停留時間）：分組器 (caption_kit/grouper.py) 確保每組字幕在切換到下一個區塊之前，至少在畫面上停留 0.38s。當語速較快時，它會壓縮詞彙入場的 stagger，以確保不會截斷句子的結尾。
2. 時間順序：行總是以實際說出的順序進入畫面（above → main → below）。
3. Instagram Reels / TikTok 安全區域 (1080x1920)：
   • 預設 y_lockup=0.74（約 1420px），落在安全範圍 1300–1560px 內（低於臉部和動態卡片區域，且高於 Reels 底部按鈕）。
4. HyperFrames 中的音訊同步：
   • 如果影片使用分割成多個片段的音訊，絕不要使用多個指向同一檔案並帶有 data-media-start 的 <audio> 標籤（這會在 HyperFrames 中導致音訊偏移）。請始終先將音訊預先裁剪成一個連續的 .wav 檔案，並使用單一的 <audio data-start="0.000"> 標籤。