keyer — AI 影片背景移除
使用 BiRefNet-general(透過 rembg 的高品質去背模型)移除影片每一幀的背景。可選擇合成到純色或背景圖片上。音訊會保留。
此技能目錄(即此 SKILL.md 所在位置)在下文中簡稱為 $SKILL_DIR。
需要 GPU。 需要可用 VRAM ≥ 3 GB 的 CUDA GPU。 若 LLM 上下文佔用了 VRAM,請先暫停它再執行。
使用時機
當使用者想要進行以下操作時,使用此技能:
- 移除影片的背景(人物演講、產品展示等)
- 將主體置於純色或品牌背景上
- 匯出帶有透明背景的影片(Alpha 通道 PNG 幀)
設定(僅首次執行)
cd "$SKILL_DIR" && uv sync
BiRefNet 模型權重會在首次執行時自動下載(約 500 MB)。
代理工作流程
1. 詢問使用者
在移除背景之前,我需要知道:
🎭 背景替換
- null — 保留透明 Alpha 通道(PNG 幀;mp4 無 Alpha)
- #hex 顏色 — 例如 "#1a1a2e" 為深海軍藍
- /path/to/bg — 合成到背景圖片檔案上
🧠 模型
- birefnet-general — 最佳通用品質 [預設]
- birefnet-portrait — 針對人物最佳化
- isnet-general-use — 更快的替代方案
- u2net_human_seg — 快速,僅限人物
📁 輸入 / 輸出目錄 (預設:./input 和 ./output)
等待使用者回覆後再繼續。
2. 編輯 config.json
根據使用者的選擇,寫入或更新 $SKILL_DIR/config.json。
3. 執行
cd "$SKILL_DIR" && uv run python scripts/matte.py --config config.json
4. 報告結果
告知使用者輸出檔案路徑以及使用的背景模式。
設定參考
| 鍵 | 值 | 預設值 | 說明 |
|---|---|---|---|
input_dir | path | ./input | 包含輸入影片的資料夾 |
output_dir | path | ./output | 目標資料夾 |
model | 見上方 | birefnet-general | 去背模型 |
bg | null / hex / path | null | 背景替換 |
常用指令
# 預設:移除背景,透明輸出
cd "$SKILL_DIR" && uv run python scripts/matte.py
# 深色背景合成
cd "$SKILL_DIR" && uv run python scripts/matte.py --bg "#0d0d0d"
# 合成到圖片上
cd "$SKILL_DIR" && uv run python scripts/matte.py --bg /path/to/studio_bg.jpg
# 人物最佳化模型
cd "$SKILL_DIR" && uv run python scripts/matte.py --model birefnet-portrait
# 無背景(透過 CLI 傳入字串 "null")
cd "$SKILL_DIR" && uv run python scripts/matte.py --bg null
輸出
每個輸入影片會在 output_dir 中產生一個同名的輸出 .mp4 檔案。若 bg=null,輸出會以 yuv420p 編碼(mp4 中無真正的透明度);若要獲得真正的透明幀,請執行 clawimig 或匯出為 PNG 序列。
錯誤處理
- VRAM 不足 → 顯示所需與可用 GB,提供釋放 VRAM 的提示,然後退出
- 無 CUDA GPU 或缺少 ONNX CUDAExecutionProvider → 顯示明確錯誤訊息,然後退出
- input_dir 中無影片 → 顯示簡潔訊息,然後退出
- 個別影片錯誤 → 記錄錯誤;其他影片繼續處理