greenscreen-tool

Replace the background behind a person in a video — with a solid color (chroma key) or with an image. Runs entirely on your Mac, no video is sent anywhere online.

Uses RVM (Robust Video Matting) for accurate person segmentation, including fine hair strands. The model is recurrent — it takes neighboring frames into account, so edges are stable and flicker-free across the video.

Features

Two commands:

• greenscreen — fills the background with a solid color (green by default), ready for chroma keying in a video editor
• greenscreen-bg — replaces the background with an image directly

Installation

Requires macOS.

git clone https://github.com/alishapckg/VideoBackgroundTool.git
cd VideoBackgroundTool
chmod +x install.sh
./install.sh

On first run, install.sh will automatically install everything needed: Homebrew (if missing), ffmpeg, a Python virtual environment with required libraries, and the segmentation model (~15 MB). This takes a few minutes and will ask for your Mac password once (to install to /usr/local/bin).

After installation, greenscreen and greenscreen-bg are available from any directory in Terminal.

Usage

Replace background with solid green:

greenscreen video.mov

Replace background with an image:

greenscreen-bg video.mov background.jpg

Specify output filename:

greenscreen video.mov result.mp4
greenscreen-bg video.mov background.jpg result.mp4

Custom background color (R,G,B format):

greenscreen video.mov --color 0,0,255

Speed/quality trade-off (fast, balanced — default, high):

greenscreen video.mov --quality high

Processing time

Roughly ~1 second per frame on balanced quality (CPU only). A 10-second video at 60 fps (~600 frames) takes around 8–12 minutes. Progress is printed to the terminal while processing.

Uninstall

./uninstall.sh

How it works

1. The video is split into individual frames (via ffmpeg)
2. Each frame is passed through RVM, which computes an alpha matte (how "human" each pixel is) — the model uses previous frames for temporal stability
3. Each frame is composited over the chosen background using the alpha matte
4. Frames are assembled back into a video (via ffmpeg)

Limitations

• Works best with a single person in the frame
• macOS only (uses Homebrew for dependency installation)

License

MIT — see LICENSE