keyer — Eliminación de fondo de video con IA
Elimina el fondo de cada fotograma de un video usando BiRefNet-general (un modelo de matting de alta calidad vía rembg). Opcionalmente compone sobre un color sólido o una imagen de fondo. El audio se conserva.
El directorio de la habilidad (donde reside este SKILL.md) se denomina $SKILL_DIR a continuación.
Se requiere GPU. Necesita una GPU CUDA con ≥ 3 GB de VRAM libre. Si el contexto del LLM está ocupando VRAM, pausa el LLM antes de ejecutar.
Cuándo usar
Usa esta habilidad cuando el usuario quiera:
- Eliminar el fondo de un video (cabeza parlante, demostración de producto, etc.).
- Colocar un sujeto sobre un color sólido o un fondo con marca.
- Exportar un video con fondo transparente (fotogramas PNG con canal alfa).
Configuración (solo la primera vez)
cd "$SKILL_DIR" && uv sync
Los pesos del modelo BiRefNet se descargan automáticamente en la primera ejecución (~500 MB).
Flujo de trabajo del agente
1. Preguntar al usuario
Antes de eliminar el fondo, necesito saber:
🎭 Reemplazo de fondo
- null — mantener canal alfa transparente (fotogramas PNG; sin alfa en mp4)
- #color hex — ej. "#1a1a2e" para azul marino oscuro
- /ruta/al/fondo — componer sobre un archivo de imagen
🧠 Modelo
- birefnet-general — mejor calidad general [por defecto]
- birefnet-portrait — optimizado para personas
- isnet-general-use — alternativa más rápida
- u2net_human_seg — rápido, solo humanos
📁 Directorios de entrada / salida (por defecto: ./input y ./output)
Espera la respuesta del usuario antes de continuar.
2. Editar config.json
Escribe o actualiza $SKILL_DIR/config.json según las elecciones del usuario.
3. Ejecutar
cd "$SKILL_DIR" && uv run python scripts/matte.py --config config.json
4. Informar resultados
Indica al usuario las rutas de los archivos de salida y el modo de fondo utilizado.
Referencia de configuración
| Clave | Valores | Por defecto | Descripción |
|---|---|---|---|
input_dir | ruta | ./input | Carpeta que contiene los videos de entrada |
output_dir | ruta | ./output | Carpeta de destino |
model | ver arriba | birefnet-general | Modelo de matting |
bg | null / hex / ruta | null | Reemplazo de fondo |
Invocaciones comunes
# Por defecto: eliminar fondo, salida transparente
cd "$SKILL_DIR" && uv run python scripts/matte.py
# Composición con fondo oscuro
cd "$SKILL_DIR" && uv run python scripts/matte.py --bg "#0d0d0d"
# Composición sobre una imagen
cd "$SKILL_DIR" && uv run python scripts/matte.py --bg /ruta/a/studio_bg.jpg
# Modelo optimizado para retratos
cd "$SKILL_DIR" && uv run python scripts/matte.py --model birefnet-portrait
# Fondo nulo (pasar como cadena "null" a través de la CLI)
cd "$SKILL_DIR" && uv run python scripts/matte.py --bg null
Salida
Cada video de entrada produce un archivo .mp4 de salida en output_dir con el
mismo nombre de archivo. Si bg=null, la salida se codifica con yuv420p (sin transparencia real
en mp4); para fotogramas realmente transparentes, ejecuta clawimig o exporta como secuencia PNG.
Manejo de errores
- VRAM insuficiente → imprime GB requeridos vs disponibles, consejos para liberar VRAM, sale
- Sin GPU CUDA / Falta ONNX CUDAExecutionProvider → mensaje claro de error, sale
- Sin videos en input_dir → mensaje limpio, sale
- Errores de video individuales → se registran; otros videos continúan procesándose