video-background-remover 0.1.3

CLI tool to remove video backgrounds with rembg and OpenCV

Video Background Remover CLI

A Python CLI tool that removes backgrounds from videos using rembg and OpenCV. It supports full video export, transparent frame extraction, and animated WebP / GIF generation.

✨ Features

• Split a video into frames, remove the background, and rebuild it as a video
• Export transparent webp / png frames at fixed intervals
• Generate transparent animated webp / gif
• Replace the removed background with a solid color or background image
• Switch between isnet-general-use, u2net, u2netp, u2net_human_seg, and silueta

📋 Requirements

• Python 3.10 or later
• FFmpeg is not required
• The model is downloaded on first run

🛠️ Install

From PyPI

pip install video-background-remover

Local development

pip install -e ".[dev]"

With uv

uv sync --extra dev

🚀 Quick Start

1. Export a video with a white background

video-background-remover assets/onizuka_idle_motion.mp4 output/output_white.mp4 --bg-color white

2. Export a transparent animated WebP

video-background-remover assets/onizuka_idle_motion.mp4 output/output_animated.webp --animated webp --webp-fps 10

3. Export transparent frames every second

video-background-remover assets/onizuka_idle_motion.mp4 output/frames --interval 1 --format webp

💡 Usage

video-background-remover INPUT OUTPUT [options]

If you are running directly from the repository, python main.py ... and python -m video_background_remover_cli ... still work.

Full video export

video-background-remover input.mp4 output.mp4 --bg-color white
video-background-remover input.mp4 output.mp4 --bg-image background.jpg
video-background-remover input.mp4 output.mp4 --fps 30

Regular video output does not preserve alpha transparency. If you want a visible background, pass --bg-color or --bg-image.

Transparent frame export

video-background-remover input.mp4 output/frames --interval 0.5 --format webp
video-background-remover input.mp4 output/frames --interval 1 --format png

When --interval is set, OUTPUT is treated as a directory name instead of a file path.

Animated WebP / GIF export

video-background-remover input.mp4 output/output_animated.webp --animated webp
video-background-remover input.mp4 output/output.gif --animated gif --webp-fps 8
video-background-remover input.mp4 output/output --animated both --webp-fps 8 --max-frames 120

With --animated both, the tool writes both .webp and .gif using the same base name.

⚙️ Options

Option	Description
--model	Background removal model. Default: isnet-general-use
--fps	FPS for regular video output. Defaults to the input video's FPS
--bg-color	Background color. Supports white, black, green, blue, red, gray, transparent, or 255,128,0
--bg-image	Path to a background image
--keep-frames	Keep intermediate frames instead of deleting them
--work-dir	Working directory for extracted frames
--interval	Export frames every N seconds
--format	Output format for --interval mode: webp or png
--animated	Animated output mode: webp, gif, or both
--webp-fps	FPS for animated output
--max-frames	Maximum number of frames for animated output

🧠 Models

Model	Description
isnet-general-use	General-purpose default model
u2net	Good for salient object extraction
u2netp	Lightweight variant of u2net
u2net_human_seg	Optimized for human segmentation
silueta	Higher quality but slower

🔥 Fire Effect Comparison

Test clip: assets/onizuka_fire_motion.mp4

Test settings:

video-background-remover assets/onizuka_fire_motion.mp4 output/model.webp --animated webp --webp-fps 8 --model <model>

Model	Preview	Notes
isnet-general-use		Keeps some effect detail, but halo noise remains around the subject
u2net		Stable silhouette, but removes most of the fire aura
u2netp		Fastest, but quality drops on complex fire frames
u2net_human_seg		Not suitable for this effect-heavy clip
silueta		Best overall balance for this sample

Experiment Summary

• silueta gave the best overall balance on this clip.
• u2net was the cleanest fallback when you prefer a stable silhouette.
• u2net_human_seg was not suitable for this stylized, effect-heavy sample.

Visual Comparison

Re-run This Experiment

The tracked experiment definition lives in experiments/onizuka_fire_motion/.

• Script: experiments/onizuka_fire_motion/run_experiment.py
• Config: experiments/onizuka_fire_motion/experiment_config.json
• Notes: experiments/onizuka_fire_motion/README.md
• Generated files: output/model_experiments/onizuka_fire_motion/

Run it again from the repository root:

python experiments/onizuka_fire_motion/run_experiment.py

To test an additional model later, add it to the models array in experiments/onizuka_fire_motion/experiment_config.json and run the same command again.

The script regenerates:

• <model>_anim.webp
• <model>_anim_frames/
• results.csv
• alpha_stats.csv
• comparison_sheet.png
• comparison_masks.png

🖼️ Output Examples

• Input video: assets/onizuka_idle_motion.mp4
• Animated WebP: example/output_animated.webp
• GIF: output/output.gif
• Comparison GIF: example/onizuka_walk_motion.gif
• Comparison WebP: example/onizuka_walk_motion.webp
• Transparent frames: output_frames_webp/

GIF / WebP Comparison

GIF	WebP

📝 Notes

• The initial model load can take some time
• Long videos exported as --animated gif can become large
• If you need transparency, prefer --animated webp or --interval output instead of regular video export

🎨 Documentation Color Map

🧪 Docs Development

• The social card image is published at docs/public/ogp.jpg.
• Social card metadata is configured in docs/.vitepress/config.ts.
• To verify the current card after a docs change or deployment, open https://www.opengraphs.com/tools/og-debugger and test https://sunwood-ai-labs.github.io/video-background-remover-cli/.