# ✂️ RemoveBG Studio (Images & Video with FFmpeg)

A powerful, high-performance background removal tool supporting single images, batch image folders, and video files with lossless frame extraction using FFmpeg. Ships as a native Windows app with a modern WebView2 UI, plus a scriptable CLI.

---

## 🖥️ Native App (Recommended)

`native/` is a small C++ host application: a native window that embeds a **WebView2** view (Chromium, via the OS-provided WebView2 Runtime) for the UI, and spawns the Python engine as a background **sidecar** process it talks to over a newline-delimited JSON protocol on stdin/stdout.

```
native/RemoveBGStudio.exe   (native C++ host + WebView2 UI, no console)
        │
        ├── web/index.html, styles.css, app.js   (the actual UI)
        │
        └── spawns → .venv/Scripts/python.exe -u core/sidecar.py
                       (rembg + FFmpeg engine, JSON-over-stdio)
```

The C++ side never talks to rembg/FFmpeg directly — all of that logic still lives in `core/processor.py` and `core/ffmpeg_utils.py`, unchanged. `core/sidecar.py` is the only new piece of Python: it wraps those modules in a JSON request/response loop so the native UI can drive them.

### Building the native app

Requirements: CMake 3.20+, MSVC (Visual Studio 2022 Build Tools or full VS), PowerShell, `make`, Windows 10/11 x64. No vcpkg or NuGet install needed — `native/third_party/fetch-webview2.ps1` pulls the WebView2 SDK headers/libs straight from nuget.org the first time they're needed. The nlohmann/json single header is small enough to vendor directly and lives at `native/third_party/json/`.

```bash
make sync   # uv sync — installs the Python engine's dependencies
make run    # fetches WebView2 SDK (first run only) → configures → builds → launches
```

Other targets: `make build` (build only), `make fetch-deps` (just the WebView2 SDK fetch), `make clean` (removes `native/build/`).

The exe locates the repo root by walking up from its own path looking for `pyproject.toml`, then launches the sidecar with `.venv/Scripts/python.exe` if that venv exists, otherwise falls back to `python` on `PATH`.

For a console-attached debug variant with DevTools enabled (right-click → Inspect in the WebView2 UI) and sidecar stderr visible, configure manually with `-DRBG_CONSOLE=ON`:

```bash
cmake -S native -B native/build -G "Visual Studio 17 2022" -A x64 -DRBG_CONSOLE=ON
cmake --build native/build --config Release
```

---

## 🌟 Key Features

- **Single & Batch Image Support**: Remove backgrounds from a single image or an entire folder of images in PNG, WebP, JPG, BMP, or TIFF.
- **FFmpeg Lossless Video Processing**:
  - Extracts frames in **100% Lossless PNG** format (`-c:v png`) to ensure zero quality degradation during extraction.
  - Preserves original audio streams from input videos.
  - Supports exporting to QuickTime MOV (ProRes 4444 with Alpha Channel), WebM VP9 (Alpha Transparency), MP4 H.264 (Solid / Green Screen keying), or raw PNG Frame Sequences.
- **Multiple AI Models**:
  - `u2net`: General purpose default model.
  - `u2netp`: Lightweight and fast model.
  - `u2net_human_seg`: Optimized for human portraits & people.
  - `u2net_cloth_seg`: Optimized for fashion & clothing.
  - `isnet-general-use`: High detail and crisp edge detection.
  - `birefnet-general`: State-of-the-art high-precision background removal.
- **Background Replacement**: Replace background with transparency, green screen keying (`#00FF00`), solid white, solid black, or any custom hex color.
- **Alpha Matting**: Optional advanced alpha matting for fine details (hair, fur, transparent fabrics).
- **Dual Interface**: Use either the native **GUI** (`native/`) or the scriptable **CLI** (`removebg.py`).

---

## 🚀 Quick Start

### 1. Requirements
Ensure Python 3.8+ and [FFmpeg](https://ffmpeg.org/) are installed on your system.

Install required dependencies:
```bash
pip install -r requirements.txt
```

---

## 💻 Usage

### ⌨️ Command Line Interface (CLI)

#### 1. Single Image Processing
```bash
# Output defaults to input_nobg.png
python removebg.py -i portrait.jpg

# Specify output destination & custom model
python removebg.py -i portrait.jpg -o result.png --model isnet-general-use
```

#### 2. Batch Image Processing
```bash
# Process all images in a directory
python removebg.py -b ./my_photos -o ./no_bg_photos

# Batch processing with green screen background replacement & WebP output
python removebg.py -b ./my_photos -o ./green_photos --bg-color green --format webp
```

#### 3. Video Processing (FFmpeg Frame Extraction & Reassembly)
```bash
# Extract frames, remove background, reassemble as transparent MOV ProRes 4444:
python removebg.py -v input.mp4 -o output_transparent.mov --export-format mov_transparent

# Video with Green Screen background keying:
python removebg.py -v dance.mp4 -o dance_green.mp4 --export-format mp4_solid --bg-color green

# Export as WebM with alpha transparency:
python removebg.py -v video.mp4 -o video_alpha.webm --export-format webm_transparent

# Export processed frames as a PNG sequence folder:
python removebg.py -v clip.mp4 -o ./processed_frames --export-format png_sequence
```

---

## ⚙️ CLI Options Reference

| Argument | Short | Description |
| :--- | :--- | :--- |
| `--image` | `-i` | Input image file path(s) |
| `--batch` | `-b` | Input directory containing images for batch processing |
| `--video` | `-v` | Input video file path for FFmpeg frame extraction & processing |
| `--output` | `-o` | Output file path or directory |
| `--model` | `-m` | AI model selection (`u2net`, `u2netp`, `u2net_human_seg`, `isnet-general-use`, `birefnet-general`) |
| `--bg-color` | `-bg` | Background replacement (`green`, `white`, `black`, or Hex `#00FF00`) |
| `--alpha-matting` | `-am` | Enable alpha matting for finer edge detail (hair/fur) |
| `--format` | | Output image format (`png`, `webp`, `jpg`) |
| `--fps` | | Target frame rate for video frame extraction (0 = original FPS) |
| `--export-format` | | Video reassembly format (`mov_transparent`, `webm_transparent`, `mp4_solid`, `png_sequence`) |

---

## 🎨 Frame Extraction & Quality Guarantee

When processing video files:
1. **FFmpeg** extracts frames using `-c:v png -pred mixed` into a 24-bit/32-bit PNG sequence, ensuring zero compression loss during frame extraction.
2. The AI background removal engine processes each PNG frame cleanly.
3. **FFmpeg** reassembles frames with original audio synced into your target codec (ProRes 4444 / VP9 / H.264).