keyer — AI動画背景除去
動画の全フレームから背景を除去します。BiRefNet-general(rembg経由の高品質マッティングモデル)を使用。任意で単色または背景画像に合成できます。音声は保持されます。
このSKILL.mdが存在するスキルディレクトリを、以下$SKILL_DIRと表記します。
GPU必須。 CUDA GPUで3 GB以上の空きVRAMが必要です。 LLMコンテキストがVRAMを占有している場合は、実行前に一時停止してください。
使用すべき場面
以下の場合にこのスキルを使用します。
- 動画(トーキングヘッド、製品デモなど)から背景を除去したい
- 被写体を単色またはブランド背景に配置したい
- 透明な背景を持つ動画(アルファチャンネルPNGフレーム)をエクスポートしたい
セットアップ(初回のみ)
cd "$SKILL_DIR" && uv sync
BiRefNetモデルの重みは初回実行時に自動ダウンロードされます(約500 MB)。
エージェントワークフロー
1. ユーザーに質問する
背景を除去する前に、以下の情報を教えてください。
🎭 背景の置き換え
- null — 透明アルファチャンネルを維持(PNGフレーム; mp4アルファは非対応)
- #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 | パス | ./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に同じファイル名で1つの.mp4ファイルが出力されます。bg=nullの場合、出力はyuv420pでエンコードされます(mp4では本当の透明度は利用不可)。実際の透明フレームが必要な場合は、clawimigを実行するか、PNGシーケンスとしてエクスポートしてください。
エラー処理
- VRAM不足 → 必要・利用可能なGB数とVRAM解放のヒントを表示して終了
- CUDA GPUなし / ONNX CUDAExecutionProviderなし → 明確なエラーを表示して終了
- input_dirに動画がない → クリーンなメッセージを表示して終了
- 個別の動画エラー → ログに記録。他の動画は処理を続行