video-captioner — 動畫字幕管線
使用 Whisper 轉錄語音,並將逐字動畫字幕嵌入影片中。不需要調色——如需視覺增強,請先使用 video-enhancer 技能。
管線
輸入影片 → Whisper 轉錄 → pycaps 字幕渲染 → 輸出帶字幕的影片
字幕樣式
三個選項:
- 預設(無標記) — pycaps 內建極簡風格:純白文字,無特效。
- 未來感(內建) —
--css scripts/futuristic.css— 交替金色/洋紅色字幕,帶有發光效果和等寬字體。適合科技、遊戲或高能量內容。 - 自訂 — 使用者可以透過
--css /path/to/custom.css提供任何 CSS 檔案路徑。
如果使用者沒有提到字幕樣式,請詢問他們想要預設外觀、未來感風格還是自訂 CSS 檔案。
靜態字幕
使用 --caption 在特定時間戳記添加預定義文字,而不是轉錄音訊:
--caption "START-END: TEXT"
格式:
- 時間使用
M:SS或MM:SS格式(例如,0:05= 5 秒,1:30= 90 秒) - 多個字幕:多次使用
--caption - 如果同時提供了靜態字幕和轉錄內容,靜態字幕具有優先權
範例:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello world" \
--caption "0:10-0:20: This is a demo" \
--css scripts/futuristic.css
字幕樣式設定
樣式通過 JSON 設定檔 進行管理。使用靜態字幕時,會自動套用樣式。
預設樣式
未指定 --style-config 時,使用 config.default.json:
- 背景: 白色(
#FFFFFF) - 文字顏色: 藍色(
#0066FF) - 字型:
auto— 首先使用brand-manager中標記為caption的可用品牌字型,否則回退到 Courier New - 內距:
10px 15px - 外距:
0
使用樣式設定檔
透過傳遞設定檔來切換樣式:
# 使用深色模式樣式
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json
內建設定檔:
config.default.json— 白色背景,藍色文字,Courier New(預設)config.dark-mode.json— 深色背景,白色文字,較大字型
建立自訂樣式設定檔
複製 config.default.json 並修改:
{
"caption_bg_color": "#000000",
"caption_color": "#FFFFFF",
"caption_font": "auto",
"caption_font_tag": "caption",
"caption_padding": "20px 30px",
"caption_margin": "10px",
"caption_font_size": 48
}
然後使用它:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Text" \
--style-config my-custom-style.json
使用 CLI 標記覆蓋設定
CLI 標記優先於設定檔中的值:
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json \
--caption-color "#00FF00" # 覆蓋設定檔的文字顏色
樣式設定參考
| 鍵 | 類型 | 說明 |
|---|---|---|
caption_bg_color | 字串 | 背景顏色(十六進位或 CSS 顏色名稱) |
caption_color | 字串 | 文字顏色(十六進位或 CSS 顏色名稱) |
caption_font | 字串 | auto、字型族或 .ttf、.otf、.woff、.woff2 檔案路徑 |
caption_font_tag | 字串或 null | 優先從 brand-manager 使用的品牌字型標籤(caption、body、heading 等) |
caption_padding | 字串 | CSS 內距(例如 "10px 15px") |
caption_margin | 字串 | CSS 外距(例如 "0") |
caption_font_size | 整數或 null | 字型大小(像素;null = 自動縮放) |
可用字型
可以按名稱指定系統字型:
DejaVu Sans/DejaVu Sans Bold/DejaVu SerifLiberation Sans/Liberation MonoCourier NewUbuntu Mono- 任何 TTF 檔案路徑:
/path/to/font.ttf
或者從 skills/brand-manager/brand-assets/asset-manifest.json 中的品牌字型選擇。
當 caption_font 為 auto 時,技能會讀取品牌清單(如果設定了 CLAW_BRAND_ASSETS_DIR 則使用該路徑),並使用第一個可用的、由 caption_font_tag 標記的字型;如果沒有標記的字型,它會嘗試標記為 caption、body、heading 或 bold 的品牌字型,然後回退到 Courier New。如果解析後的品牌字型是檔案路徑,生成的 CSS 將包含一個 @font-face 規則,以便 pycaps 可以渲染它。
如何執行
安裝依賴項(僅首次執行):
cd "$SKILL_DIR" && uv sync
注意: 首次執行會很慢(可能需要幾分鐘),因為 pycaps 會下載 Whisper 語音辨識模型。在開始之前警告使用者。
然後處理影片:
cd "$SKILL_DIR" && uv run python scripts/caption_service.py \
--input <path/to/input> \
--output <path/to/output> \
[--css scripts/futuristic.css]
常見用法
# 預設極簡字幕(Whisper 轉錄)
uv run python scripts/caption_service.py --input ./input --output ./output
# 未來感風格
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css scripts/futuristic.css
# 自訂 CSS
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--css /path/to/my.css
# 靜態字幕,預設樣式(白色背景,藍色文字,Courier New)
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Subscribe for more" \
--caption "0:10-0:15: Follow us on Instagram"
# 靜態字幕,深色模式樣式
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello world" \
--caption "0:10-0:20: This is a demo" \
--style-config config.dark-mode.json
# 靜態字幕,自訂樣式設定
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Custom text" \
--style-config my-custom-style.json
# 靜態字幕,CLI 生命令列參數覆蓋
uv run python scripts/caption_service.py \
--input ./input --output ./output \
--caption "0:01-0:05: Hello" \
--style-config config.dark-mode.json \
--caption-color "#00FF00"
# 監控模式(每 10 秒輪詢新影片)
uv run python scripts/caption_service.py --input ./input --output ./output --watch
執行後
向使用者回報:
- 成功處理了多少部影片,失敗了多少部。
- 輸出目錄的完整路徑。
- 如果有任何影片失敗,請明確列出它們的名稱。
邊緣情況
- 如果未安裝
ffmpeg:告知使用者安裝它(在 Arch/CachyOS 上使用sudo pacman -S ffmpeg,在 macOS 上使用brew install ffmpeg,在 Ubuntu 上使用sudo apt install ffmpeg) - 如果未安裝
uv:引導至 https://docs.astral.sh/uv/getting-started/installation/ - 如果輸入目錄是空的:清楚地報告,而不是默默退出
- 首次執行會下載 Whisper 模型(
tiny約 140 MB,large約 1.5 GB)——這是僅一次的操作
遠端轉錄
此技能現在支援選用的遠端轉錄,同時保持 pycaps 渲染在本機進行。
- 預設行為仍然是完全本機:pycaps 內部的 Whisper 轉錄 + 本機渲染
- 遠端模式僅取代轉錄步驟
- 字幕渲染、模板和 CSS 處理仍保留在本機
支援的提供者
huggingfacereplicate
設定 / CLI 鍵
| 鍵 | 預設值 | 說明 |
|---|---|---|
transcription_provider | null | null 保持本機 Whisper-in-pycaps 流程 |
remote_model | null | 選用,提供者特定的轉錄模型覆蓋 |
hf_token_env | HF_TOKEN | HuggingFace 驗證環境變數名稱 |
replicate_api_key_env | REPLICATE_API_TOKEN | Replicate 驗證環境變數名稱 |
remote_timeout_seconds | 300 | 遠端呼叫超時 |
範例
# HuggingFace 遠端轉錄 + 本機 pycaps 渲染
export HF_TOKEN=hf_your_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider huggingface
# Replicate 遠端轉錄 + 本機 pycaps 渲染
export REPLICATE_API_TOKEN=r8_your_token
uv run python scripts/caption_service.py --input ./input --output ./output --transcription-provider replicate --remote-model <replicate-model-slug>
注意事項
- 如果遠端驗證/設定缺失,不會無聲地回退到本機模式
- 現有的本機 CLI 用法仍然有效
- 如果您不設定
--transcription-provider,pycaps 會繼續使用其內建的 Whisper 流程