AlphaCut v1.6.13

Video & image background removal + compositing.

AlphaCut uses ONNX segmentation models to isolate subjects from video and image backgrounds, with built-in compositing, mixed batch processing, quick previews, and detected hardware encoding.

---

Features

AI & Processing

• 10 AI Models — U2Net, ISNet, BiRefNet (6 variants) — from fast drafts to cinema-quality edges
• 11 Software Output Formats — ProRes 4444+Alpha, WebM VP9+Alpha, H.264, HEVC, AV1, Animated WebP, Animated GIF, PNG sequences, green screen, grayscale matte, FG+Alpha pair
• Hardware Encoder Options — detected NVENC/QSV H.264 and HEVC formats appear automatically when FFmpeg exposes them
• Single & Batch Image Mode — drop one image or mixed image/video batches for transparent PNG export
• Chroma-Key Fallback — auto-detect green/blue screens; FFmpeg chroma-key for 10x speed boost
• Pipelined I/O — parallel decode/infer/save threads for higher throughput
• Frame Skip — process every Nth frame with mask reuse (up to 10x speedup)
• Benchmark Mode — test 10 samples to estimate total processing time
• Memory Monitoring — live RAM % during processing with warnings; animated WebP/GIF exports estimate frame-list RAM and refuse unsafe clips unless explicitly overridden in CLI mode
• Resume Interrupted Jobs — progress saved every 50 frames, auto-resumes on restart
• Pipe Mode — --pipe streams raw RGBA to stdout for FFmpeg/scriptable pipelines without blocking on FFmpeg diagnostics
• Model Registry — models.json declares model name, URL, SHA-256 hash, input size, and license; downloads fail closed on mismatch

Advanced Compositing

• ROI Selection — crop AI inference to a preview-selected subject region
• Manual Mask Painting — foreground/background brush corrections applied to preview, single export, and batch export
• Mask Preview Modes — compare original/result, inspect binary masks, gray masks, and red/green overlays
• Background Replacement — solid color (6 presets + custom picker) or image file
• Color Spill Suppression — reduce green/blue/red spill along mask edges
• Shadow Preservation — detect and keep ground shadows via luminance analysis
• Mask Inversion — remove subject instead of background

Batch & Workflow

• Batch Queue — drop multiple videos, images, folders, or mixed sets and process sequentially
• Job Table — per-file thumbnails, per-job model/format overrides, status, progress %, and output path
• Thumbnail Grid — visual grid preview of all batch files before processing
• Quick Preview — render a 10-second sample clip before committing to full processing
• Drag-Out Export — drag output file directly into NLE timelines
• CLI Mode — full argparse interface for headless/scripted operation (with auto chroma-key detection)
• Watch Folder Automation — poll a local folder, process stable media arrivals with saved presets, and emit JSON status
• Auto-Naming — configurable output patterns ({name}, {model}, {format}, {date})
• Export Presets — save/load all settings including compositing
• Recent Files — last 20 files quick-access menu

UI/UX

• Before/After Split View with draggable divider
• Smart Model Picker, Toast Notifications, Animated Progress
• Mask Quality Inspection — preview reports foreground/transparent coverage, edge density, transition area, jitter-risk, and actionable warnings before export
• System Tray integration, Scrubable Preview
• Menu Bar — File, Tools (Model Manager, Settings Folder), Help (Updates, About)
• About Dialog — version, system info, GitHub links
• Update Checker — checks GitHub releases on startup and on demand
• Model Manager — view/delete cached ONNX models with size info
• Settings Persistence — all preferences saved between sessions with failure logging
• Localization Ready — expanded i18n coverage with locale_template.json for community translations
• Responsive Accessibility Pass — scroll-contained controls, explicit status cues, and pinned keyboard focus order for smaller/high-DPI desktop layouts

Requirements

Requirement	Details
Python	3.9+
FFmpeg	On PATH
CPU	Default onnxruntime profile
NVIDIA GPU	Optional CUDA 12 + cuDNN 9 profile
Windows GPU	Optional DirectML profile
macOS GPU	Optional CoreML profile on supported Apple hardware

Installation

Windows releases include AlphaCut-Setup-<version>.exe, an Inno Setup installer that installs AlphaCut per user and creates Start Menu shortcuts. The portable AlphaCut-windows.exe is still published for users who prefer a standalone executable. Release builds also publish .sha256 sidecar files and SHA256SUMS.txt.

Python Profiles

# GUI CPU profile
pip install -r requirements.txt

# GUI accelerator profiles
pip install -r requirements-cuda.txt       # NVIDIA CUDA 12 + cuDNN 9
pip install -r requirements-directml.txt   # Windows DirectML
pip install -r requirements-coreml.txt     # macOS CoreML-capable ONNX Runtime

# Headless CLI equivalents
pip install -r requirements-cli.txt
pip install -r requirements-cli-cuda.txt
pip install -r requirements-cli-directml.txt
pip install -r requirements-cli-coreml.txt

Run python AlphaCut.py --runtime-info after installation to verify the active ONNX Runtime providers and see package guidance for unavailable accelerators.

Docker

docker build -t alphacut .
docker run --rm -v $(pwd):/data alphacut -i /data/video.mp4 -f webm -o /data/output.webm
docker run --rm -v /path/to/watch:/watch -v /path/to/output:/output alphacut --watch-folder /watch --watch-output /output --watch-once --json

GPU-enabled Docker builds use the NVIDIA CUDA runtime and onnxruntime-gpu:

docker build -f Dockerfile.gpu -t alphacut:gpu .
docker run --rm --gpus all -v $(pwd):/data alphacut:gpu -i /data/video.mp4 -f webm -o /data/output.webm --gpu-device 0
docker run --rm --gpus all -v /path/to/watch:/watch -v /path/to/output:/output alphacut:gpu --watch-folder /watch --watch-output /output --watch-preset /output/preset.json --json

Quick Start

# GUI
python AlphaCut.py

# CLI — single image (outputs transparent PNG)
python AlphaCut.py -i photo.jpg -m BiRefNet

# CLI — video
python AlphaCut.py -i video.mp4 -f prores -m BiRefNet

# CLI — background replacement
python AlphaCut.py -i video.mp4 -f webm --bg-image beach.jpg

# CLI — green spill + shadow preservation
python AlphaCut.py -i greenscreen.mp4 -f prores --spill 60 --shadow 40

# CLI — batch with frame skip
python AlphaCut.py -i vid1.mp4 vid2.mp4 vid3.mp4 -f webm --frame-skip 3

# CLI — batch images (outputs transparent PNG files)
python AlphaCut.py -i photo1.jpg photo2.png photo3.webp -m BiRefNet -y

# CLI — invert mask + custom background
python AlphaCut.py -i video.mp4 -f prores --invert --bg-color 0,0,0

# CLI — FG + Alpha pair (for NLEs without alpha support)
python AlphaCut.py -i video.mp4 -f fg_alpha -m BiRefNet

# CLI — pipe raw RGBA into FFmpeg
python AlphaCut.py -i video.mp4 --pipe 2>nul | ffmpeg -f rawvideo -pix_fmt rgba -s 1920x1080 -r 30 -i - -c:v libvpx-vp9 out.webm

# CLI — process stable files from a local watch folder once
python AlphaCut.py --watch-folder C:\AlphaCut\inbox --watch-output C:\AlphaCut\out --watch-preset C:\AlphaCut\preset.json --watch-once --json

CLI Reference

Flag	Default	Description
-i, --input	—	Input video/image file(s)
-o, --output	Auto-named	Output path
-m, --model	u2net_human_seg	Model name (partial match)
-f, --format	mp4	mp4, hevc, av1, prores, webm, webp_anim, gif_anim, png_seq, greenscreen, matte, fg_alpha, mp4_nvenc, hevc_nvenc, mp4_qsv, hevc_qsv
--gpu-device	-1 (auto)	GPU device index for inference
--fp16	—	Use half-precision inference on GPU
--allow-large-animation	—	Override animated WebP/GIF RAM safety refusal
--max-res	0 (original)	Max resolution
--edge	0	Edge softness (0-100)
--shift	0	Mask shift (-20 to +20)
--temporal	0	Temporal smooth (0-7)
--frame-skip	1	Process every Nth frame
--invert	—	Invert mask
--spill	0	Spill suppression (0-100)
--spill-color	green	Spill color: green, blue, red
--shadow	0	Shadow preservation (0-100)
--bg-color	—	Background R,G,B
--bg-image	—	Background image path
--no-audio	—	Strip audio
-y, --overwrite	—	Overwrite output without confirmation
--chroma-key	—	Use FFmpeg chroma-key when a green/blue screen is detected
--pipe	—	Stream raw RGBA to stdout for FFmpeg pipelines
--json	—	Emit newline-delimited JSON progress/status/error events; failures exit non-zero and end with a failed event
--watch-folder	—	Poll a local folder and process stable media files as they arrive
--watch-output	<watch-folder>/alphacut_out	Output directory for watch-folder jobs
--watch-preset	—	Preset JSON path or saved GUI preset name for watch-folder jobs
--watch-output-pattern	{name}_alphacut	Output naming pattern for watch-folder jobs
--watch-interval	2.0	Seconds between watch-folder scans
--watch-stable-seconds	2.0	Seconds a file size/mtime must remain unchanged before processing
--watch-retry-seconds	30.0	Seconds before retrying a failed watch-folder job
--watch-state	<watch-output>/.alphacut-watch-state.json	Processed-file signature state file
--watch-once	—	Process currently stable watch-folder files, then exit
--runtime-info	—	Print ONNX Runtime provider diagnostics and install profile guidance

AI Models

Model	Speed	Quality	Best For
u2netp	Fast	Good	Quick previews
u2net_human_seg	Fast	Great	People (default)
silueta	Fast	Good	People (small)
u2net	Medium	Great	General subjects
isnet-general-use	Medium	Great	General subjects
isnet-anime	Medium	Great	Anime / illustrations
BiRefNet-portrait	Slow	Excellent	Portraits, hair detail
BiRefNet-general	Slow	Excellent	Best overall
BiRefNet-general-lite	Medium	Excellent	Fast + high quality
BiRefNet-matting	Slow	Excellent	Hair and transparent edges

Project Planning

• ROADMAP.md - active and proposed work.
• Roadmap_Blocked.md - items blocked by external dependencies or research.
• RESEARCH.md - research notes that inform future roadmap candidates.

Architecture

AlphaCut.py (single file, ~5,200 lines)
├── Crash Handler + Bootstrap (auto-installs all deps)
├── AlphaCutEngine — ONNX inference + mask refinement
│   ├── Edge refinement, temporal smoothing
│   ├── Spill suppression, shadow preservation
│   ├── Mask inversion, background compositing
│   ├── SHA-256 model integrity verification
│   └── Engine cache (singleton)
├── ProcessingWorker — Pipelined frame processing
│   ├── Reader thread → AI inference → Saver thread
│   ├── Frame skip with mask reuse
│   └── Resume from last saved frame
├── BatchWorker — Sequential multi-file processing
├── ImageProcessWorker — Single and batch image background removal
├── BenchmarkWorker — 10-frame speed estimation
├── PreviewFrameWorker — Single-frame preview
├── QuickPreviewWorker — 10-second sample render workflow
├── UpdateChecker — GitHub releases API
├── AboutDialog — Version/system info
├── ModelManagerDialog — Download/delete models
├── SplitPreviewWidget — Before/after comparison
│   └── ROI selection + manual mask paint overlays + mask viewer modes
├── DragOutButton — Drag output file to NLE
├── ThumbnailGrid — Visual batch file preview grid
├── ToastWidget — Floating notifications
├── CLI — Full argparse headless interface
├── Pipe Mode — Raw RGBA stdout for FFmpeg pipelines
├── Watch Folder Mode — Local polling automation with preset support and JSON status
├── i18n — _tr() scaffold + locale_template.json
├── models.json — External model registry
└── Settings/Presets — JSON persistence

Local Build

.\packaging\windows\build-release.ps1

The release script cleans stale build outputs, builds dist\AlphaCut-windows.exe, builds dist\installer\AlphaCut-Setup-<version>.exe, and writes AlphaCut-windows.exe.sha256, AlphaCut-Setup-<version>.exe.sha256, and dist\SHA256SUMS.txt.

Signing is automatic when configured. Set ALPHACUT_SIGN=1 to use the first suitable certificate in the Windows certificate store, or set ALPHACUT_SIGN_CERT_SHA1 / ALPHACUT_SIGN_CERT_PATH plus optional ALPHACUT_SIGN_CERT_PASSWORD. ALPHACUT_SIGNTOOL can point to signtool.exe when it is not on PATH. Without signing configuration the same artifacts and checksums are produced unsigned, and the script prints a warning.