keyer — AI 视频背景去除
使用 BiRefNet-general(通过 rembg 的高质量抠图模型)去除视频每一帧的背景。可选择合成到纯色或背景图像上。音频会保留。
技能目录(即此 SKILL.md 所在的目录)以下简称为 $SKILL_DIR。
需要 GPU。 需要具有 ≥ 3 GB 可用显存的 CUDA GPU。 如果 LLM 上下文占用了显存,请先暂停它再运行。
何时使用
当用户希望进行以下操作时使用此技能:
- 去除视频中的背景(如说话人头部、产品演示等)
- 将主体放置到纯色或品牌背景上
- 导出带有透明背景的视频(PNG 帧 alpha 通道)
设置(仅首次运行)
cd "$SKILL_DIR" && uv sync
BiRefNet 模型权重会在首次运行时自动下载(约 500 MB)。
代理工作流程
1. 询问用户
在去除背景之前,我需要了解以下信息:
🎭 背景替换方式
- null — 保留透明 alpha 通道(PNG 帧;mp4 不支持 alpha)
- #hex colour — 例如 "#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 | 路径 | ./input | 存放输入视频的文件夹 |
output_dir | 路径 | ./output | 目标文件夹 |
model | 见上 | birefnet-general | 抠图模型 |
bg | null / hex / 路径 | 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 序列。
错误处理
- 显存不足 → 打印所需与可用 GB、释放显存的提示,然后退出
- 无 CUDA GPU / 缺少 ONNX CUDAExecutionProvider → 给出清晰错误信息,退出
- 输入目录中没有视频 → 给出清晰提示,退出
- 单个视频错误 → 记录日志;其他视频继续处理