OpenCaptions 擴充功能
將 CWI（Caption With Intent）字幕整合到 Content Engine 的後製流程中。有別於平面、靜態的字幕，CWI 會編碼語音的感受體驗—音高驅動字重、音量驅動字型大小、強調觸發發光動畫，而說話者身分則對應到 WCAG AA 色彩。結果是字幕不僅傳達說了什麼，更傳達了說話的方式。
CWI 是由 FCB Chicago 與 Chicago Hearing Society 於 2025 年榮獲奧斯卡獎的字幕標準。OpenCaptions 是第一個用於此標準的開放原始碼程式化工具鏈。
管線接入點
階段： 後製（階段 3） 位置： 在放大與調色之後、最終匯出之前。
後製鏈：
1. 放大（Real-ESRGAN / Topaz） --> 更高解析度
2. 調色（品牌 LUT / ffmpeg） --> 品牌色調
3. OpenCaptions（CWI） --> 意圖驅動字幕
4. 最終匯出（ffmpeg） --> 可發行檔案
擴充功能接收一段已調色的影片檔案，並產出：
- CWI 文件（
.cwi.json）含逐字意圖註釋 - WebVTT 備用檔（
.vtt）供需要標準字幕的平台使用 - 驗證報告（JSON）含支柱評分
- 帶字幕的影片（
.mp4）以 Remotion 或 ffmpeg 燒錄渲染
運作方式
已調色影片 + 場景簡報
|
├── [1] 轉錄（faster-whisper）--> 逐字時間戳記
├── [2] 分離說話者（pyannote-audio）--> 說話者歸屬
├── [3] 提取意圖 --> 每段話的音高、音量、情緒、強調
| V1：parselmouth + FER（音訊+視覺）
| V2：V-JEPA2 世界模型
| V3：TRIBE v2 神經網路預測
├── [4] 映射意圖 --> CWI --> 每個字的字重、字型大小、強調、動畫
| V1：規則映射器（音高-->字重，音量-->字型大小）
| V2：學習映射器（以校正資料訓練）
| V3：神經映射器（腦區活動驅動樣式）
├── [5] 驗證（12 條規則）--> 歸屬 + 同步 + 語調評分
└── [6] 渲染 --> Remotion 疊加 或 ffmpeg 燒錄
步驟 1-2：轉錄 + 分離說話者
管線會呼叫 OpenCaptions CLI 或 MCP 伺服器，執行 faster-whisper 以取得逐字時間戳記，以及 pyannote-audio 進行說話者偵測。這些階段會產出 DiarizedTranscript，每個字都會標記所屬的說話者。
步驟 3：意圖提取
意圖提取器分析音訊與視訊，以判斷每段話的感受語氣：
- 聲音訊號：音高（Hz）、音量（dB）、語速（WPM）、停頓時機
- 情感訊號：效價（-1 到 1）、喚醒度（0 到 1）、主要情緒
- 語義訊號：諷刺機率、強調詞、修辭手法
這些訊號會為每段話形成一個 IntentFrame。偏離話語基準線的個別字詞則會收到 WordIntent 覆寫。
步驟 4：意圖映射
映射器將意圖訊號轉換為 CWI 視覺參數：
| 意圖訊號 | CWI 屬性 | 映射方式（V1 規則映射器） |
|---|---|---|
| 音高（歸一化 0-1） | weight（100-900） | 線性插值：100 + pitch_norm * 800 |
| 音量（歸一化 0-1） | size（0.7-1.5） | 線性插值：0.8 + volume_norm * 0.55 |
| 語義強調 + 高音量 | emphasis（布林值） | 字詞在 emphasis_words 中 或 音量 > p90 |
| 說話者身分 | 說話者的 color | 從 12 色 WCAG AA 調色盤分配 |
| 低語（低音量） | weight < 300 | 覆寫：字重限制在 100-250 |
| 高喊（高音量） | size > 1.3 + 強調 | 覆寫：字型大小 1.35-1.5，強調啟用 |
步驟 5：驗證
@opencaptions/spec 驗證器會根據三根支柱的 12 條規則檢查 CWI 文件：
歸屬（3 條規則）：
- ATT_001：每個字幕都有屬於 cast 的說話者
- ATT_002：說話者擁有獨特的顏色
- ATT_003：顏色符合 WCAG AA 對比度（相對於 #1a1a1a 為 4.5:1）
**同步（5 條規則）：
- SYN_001：所有字詞都有時間戳記
- SYN_002：時間戳記嚴格遞增
- SYN_003：字幕事件不重疊
- SYN_004：動畫持續時間依規格為 600ms
- FCC_001：說話期間無間隔 > 3 秒
- FCC_002：每行最多 42 個字元（符合 FCC 規範）
語調（3 條規則）：
- INT_001：字重在有效範圍（100-900）內
- INT_002：字型大小在有效範圍（0.7-1.5）內
- INT_003：> 20% 的字詞具有非預設字重（字幕確實有變化）
每根支柱評分 0-100。若三根支柱評分皆 >= 80，則 CWI 文件通過驗證。
步驟 6：渲染
兩種渲染路徑：
Remotion 路徑（Content Engine 偏好）：CWI 字詞變成 React 組件，放在 <CaptionOverlay> 組合中。每個字詞在其時間戳記出現，搭配 spring() 進場動畫、說話者顏色、可變字重與強調發光效果。完整對應請參閱 references/cwi-remotion-bridge.md。
ffmpeg 燒錄（備用）：從 CWI 文件產生 ASS 字幕檔，並透過 ffmpeg -vf ass=captions.ass 燒錄到影片中。會失去逐字動畫，但保留說話者顏色與字重變化。
CLI 使用方式
# 從影片產生 CWI 字幕
npx opencaptions generate video.mp4 --output captions.cwi.json
# 使用 TRIBE v2 神經網路後端產生
npx opencaptions generate video.mp4 --backend tribe --output captions.cwi.json
# 驗證 CWI 文件
npx opencaptions validate captions.cwi.json
# 在終端機預覽字幕（ANSI 色彩）
npx opencaptions preview captions.cwi.json
# 匯出為 WebVTT
npx opencaptions export captions.cwi.json --format webvtt
# 匯出為 After Effects ExtendScript
npx opencaptions export captions.cwi.json --format ae-json
# 匯出為 Premiere Pro XML
npx opencaptions export captions.cwi.json --format premiere-xml
# 檢查系統相依套件
npx opencaptions doctor
# 安裝 Python 相依套件
npx opencaptions setup
MCP 伺服器使用方式
OpenCaptions MCP 伺服器提供四個工具供代理整合：
| 工具 | 說明 |
|---|---|
generate_captions | 對影片檔案執行完整管線 |
validate_captions | 根據 12 條規則驗證 CWI 文件 |
preview_captions | 在指定時間點以終端機格式預覽 |
export_captions | 匯出為 WebVTT 格式 |
若要透過 Claude Code 使用，請將 MCP 伺服器加入設定：
{
"mcpServers": {
"opencaptions": {
"command": "npx",
"args": ["@opencaptions/mcp"]
}
}
}
然後在對話中呼叫：「為 video.mp4 產生 CWI 字幕」會觸發 generate_captions。
compose-video.py 整合
Content Engine 的 compose-video.py 支援 --captions 旗標：
python3 scripts/compose-video.py storyboard.md --brand arcan-studio --captions
當傳入 --captions 時，在所有片段產生並拼接後，管線會：
- 執行
npx opencaptions generate {final-video}.mp4 --output {output-dir}/captions.cwi.json - 驗證 CWI 文件（若評分 < 80 則提出警告，但不阻斷）
- 若同時傳入
--remotion，則將 CWI JSON 注入 Remotion 組合，作為<CaptionOverlay>的 props - 否則，在最終影片旁邊產生 WebVTT 側載檔案
如果未安裝 OpenCaptions（npx opencaptions doctor 失敗），管線會優雅降級：
- 降級為場景簡報文字疊加（來自分鏡腳本
## Shot描述的靜態文字） - 記錄警告：「OpenCaptions 不可用，使用場景簡報文字疊加」
- 仍會產出一個
.vtt檔案，時間點來自片段邊界
字幕樣式
三種內建字幕樣式預設，可透過設定選擇：
1. 逐字型（腦腐）
高保留風格：每個字個別出現、置中、字型大小變化極大。用於針對多巴胺鉤子最佳化的社交媒體/TikTok/Reels 內容。
- 一次只顯示一個字
- 基底大小較大（1080p 下 64px）
- 極端字重變化（100-900 全範圍）
- 強調字詞放大至 1.5 倍並帶有發光效果
- 背景：無（字詞浮在影片上）
- 字型：Roboto Flex 可變字型
2. 敘事型（編輯）
完整句子顯示，逐字樣式。用於長篇內容、紀錄片、部落格影片嵌入。
- 完整字幕事件可見，字詞內嵌樣式
- 中等基底大小（1080p 下 48px）
- 適度字重變化（300-700）
- 強調字詞稍微放大（1.15 倍）
- 背景：半透明藥丸（rgba(0,0,0,0.6)）
- 字型：Roboto Flex 可變字型
3. 極簡型（下方三分之一）
乾淨的下方三分之一呈現。說話者名稱 + 文字。視覺干擾最少。用於訪談、談話頭、會議錄影。
- 說話者名稱標籤使用說話者顏色，字幕文字為白色
- 基底大小較小（1080p 下 36px）
- 僅強調時有字重變化（預設 400，強調 700）
- 無字型大小變化
- 背景：漸層條（畫面底部 15%）
- 字型：系統無襯線字型
資料合約
讀取（不可變）
- 來自前一個後製步驟的已調色影片資產
knowledge/compiled/brands/{brand_slug}.md-- 用於字幕調色盤與字體偏好- 場景簡報（執行時期參數）-- 提供預期情緒基調的脈絡
寫入（僅限自有命名空間）
extensions/opencaptions/output/{asset_id}.cwi.json-- CWI 文件extensions/opencaptions/output/{asset_id}.vtt-- WebVTT 備用檔extensions/opencaptions/output/{asset_id}-report.json-- 驗證報告extensions/opencaptions/output/{asset_id}-captioned.mp4-- 渲染影片（僅 Remotion 路徑）
設定
opencaptions:
# 字幕樣式預設
style: "narrative" # word-by-word | narrative | minimal
# 視覺參數
font_family: "Roboto Flex" # 用於字重軸的可變字型
base_font_size: 48 # 1080p 下的像素值
position: "bottom" # top | center | bottom
max_chars_per_line: 42 # FCC 合規
background: "pill" # pill | shadow | gradient | none
background_opacity: 0.6 # 0.0 - 1.0
# 管線後端
backend: "av" # av（V1）| jepa（V2）| tribe（V3）
language: "en" # 轉錄的 ISO 639-1 提示
# 說話者覆寫（選用，預設自動偵測）
speakers:
- name: "Narrator"
color: "#6B8AFF"
- name: "Guest"
color: "#FF6B6B"
# 渲染
render_mode: "remotion" # remotion | ffmpeg | sidecar-only
output_format: "mp4" # mp4 | webm
fps: 30 # 與來源影片相符
# 驗證
min_score: 80 # 繼續進行的最低整體評分
fail_on_low_score: false # 若為 true，則在低評分時阻斷管線
# TRIBE v2 神經映射（僅 V3 後端）
neural_mapping: false # 啟用預測神經反應樣式
優雅降級
擴充功能絕不會阻斷 Content Engine 管線。降級階梯：
| 條件 | 行為 |
|---|---|
| OpenCaptions CLI 已安裝 + 所有 Python 相依套件 | 完整 CWI 管線（轉錄、分離、意圖、映射） |
| OpenCaptions CLI 已安裝，無 Python 相依套件 | 使用模擬後端產生佔位字幕 + 驗證 |
| OpenCaptions CLI 未安裝 | 在片段邊界使用場景簡報文字疊加作為靜態字幕 |
| 影片無音軌 | 跳過字幕產生，記錄資訊訊息 |
| 驗證評分 < 80 | 提出警告但繼續執行（除非 fail_on_low_score: true） |
| Remotion 不可用 | 降級為 ffmpeg ASS 燒錄 |
| ffmpeg 不可用 | 僅輸出 CWI JSON + WebVTT 側載檔案（無渲染影片） |
相關資源
- OpenCaptions 專案：
~/broomva/apps/opencaptions/ - CWI-Remotion 橋接：
references/cwi-remotion-bridge.md - 整合指南：
references/integration-guide.md - Content Engine SKILL.md：
../../SKILL.md - 擴充功能框架：
../README.md