keyer — AI 비디오 배경 제거
BiRefNet-general(rembg를 통한 고품질 매팅 모델)을 사용하여 비디오의 모든 프레임에서 배경을 제거합니다. 선택적으로 단색 또는 배경 이미지에 합성합니다. 오디오는 유지됩니다.
이 스킬 디렉토리(이 SKILL.md가 있는 곳)는 아래에서 $SKILL_DIR로 참조됩니다.
GPU 필요. 최소 3 GB 여유 VRAM이 있는 CUDA GPU가 필요합니다. 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에 동일한 파일 이름의 .mp4 파일 하나를 생성합니다. bg=null인 경우 출력은 yuv420p로 인코딩됩니다(mp4에서 실제 투명도 없음). 실제 투명 프레임이 필요하면 clawimig를 실행하거나 PNG 시퀀스로 내보내세요.
오류 처리
- VRAM 부족 → 필요한 GB와 사용 가능한 GB를 출력하고, VRAM을 확보하는 팁을 제공한 후 종료
- CUDA GPU 없음 / ONNX CUDAExecutionProvider 누락 → 명확한 오류 메시지 출력 후 종료
- input_dir에 비디오 없음 → 깔끔한 메시지 출력 후 종료
- 개별 비디오 오류 → 로그에 기록, 다른 비디오는 계속 처리