CorridorKey
https://github.com/user-attachments/assets/1fb27ea8-bc91-4ebc-818f-5a3b5585af08
When you film something against a green screen, the edges of your subject inevitably blend with the green background. This creates pixels that are a mix of your subject's color and the green screen's color. Traditional keyers struggle to untangle these colors, forcing you to spend hours building complex edge mattes or manually rotoscoping. Even modern "AI Roto" solutions typically output a harsh binary mask, completely destroying the delicate, semi-transparent pixels needed for a realistic composite.
I built CorridorKey to solve this unmixing problem.
You input a raw green screen frame, and the neural network completely separates the foreground object from the green screen. For every single pixel, even the highly transparent ones like motion blur or out-of-focus edges, the model predicts the true, un-multiplied straight color of the foreground element, alongside a clean, linear alpha channel. It doesn't just guess what is opaque and what is transparent; it actively reconstructs the color of the foreground object as if the green screen was never there.
No more fighting with garbage mattes or agonizing over "core" vs "edge" keys. Give CorridorKey a hint of what you want, and it separates the light for you.
Alert!
This is a brand new release, I'm sure you will discover many ways it can be improved! I invite everyone to help. Join us on the "Corridor Creates" Discord to share ideas, work, forks, etc! https://discord.gg/zvwUrdWXJm
If you want an easy-install, artist-friendly user interface version of CorridorKey, check out EZ-CorridorKey
This project uses uv to manage dependencies — it handles Python installation, virtual environments, and packages all in one step, so you don't need to worry about any of that. Just run the appropriate install script for your OS.
Naturally, I have not tested everything. If you encounter errors, please consider patching the code as needed and submitting a pull request.
Features
- Physically Accurate Unmixing: Clean extraction of straight color foreground and linear alpha channels, preserving hair, motion blur, and translucency.
- Green or Blue Screen: Dedicated checkpoints for green and blue plates. By default (
--screen-color auto) CorridorKey samples the first frame of the first clip in your batch and picks the dominant screen color from the background pixels; pass --screen-color green or --screen-color blue to skip the heuristic and force the choice. The despill then removes spill from the channel you're actually shooting against. Currently Torch backend only — the MLX path is green-screen until the blue MLX checkpoint ships.
- Resolution Independent: The engine dynamically scales inference to handle 4K plates while predicting using its native 2048x2048 high-fidelity backbone.
- VFX Standard Outputs: Natively reads and writes 16-bit and 32-bit Linear float EXR files, preserving true color math for integration in Nuke, Fusion, or Resolve.
- Auto-Cleanup: Includes a morphological cleanup system to automatically prune any tracking markers or tiny background features that slip through CorridorKey's detection.
Hardware Requirements
This project was designed and built on a Linux workstation (Puget Systems PC) equipped with an NVIDIA RTX Pro 6000 with 96GB of VRAM. The community is ACTIVELY optimizing it for consumer GPUS.
The most recent build should work on computers with 6-8 gig of VRAM, and it can run on most M1+ Mac systems with unified memory. Yes, it might even work on your old Macbook pro. Let us know on the Discord!
- Windows Users (NVIDIA): To run GPU acceleration natively on Windows, your system MUST have NVIDIA drivers that support CUDA 12.8 or higher installed. If your drivers only support older CUDA versions, the installer will likely fallback to the CPU.
- AMD GPU Users (ROCm): AMD Radeon RX 7000 series (RDNA3) and RX 9000 series (RDNA4) are supported via ROCm on Linux. Windows ROCm support is experimental (torch.compile is not yet functional). See the AMD ROCm Setup section below.
- GVM (Optional): Requires approximately 80 GB of VRAM and utilizes massive Stable Video Diffusion models.
- VideoMaMa (Optional): Natively requires a massive chunk of VRAM as well (originally 80GB+). While the community has tweaked the architecture to run at less than 24GB, those extreme memory optimizations have not yet been fully implemented in this repository.
- BiRefNet (Optional): Lightweight AlphaHint generator option.
Because GVM and VideoMaMa have huge model file sizes and extreme hardware requirements, installing their modules is completely optional. You can always provide your own Alpha Hints generated from your editing program, BiRefNet, or any other method. The better the AlphaHint, the better the result.
Getting Started
1. Installation
This project uses uv to manage Python and all dependencies. uv is a fast, modern replacement for pip that automatically handles Python versions, virtual environments, and package installation in a single step. You do not need to install Python yourself — uv does it for you.
For Windows Users (Automated):
- Clone or download this repository to your local machine.
- Double-click
Install_CorridorKey_Windows.bat. This will automatically install uv (if needed), set up your Python environment, install all dependencies, and download the CorridorKey model.
Note: If this is the first time installing uv, any terminal windows you already had open won't see it. The installer script handles the current window automatically, but if you open a new terminal and get "'uv' is not recognized", just close and reopen that terminal.
- (Optional) Double-click
Install_GVM_Windows.bat and Install_VideoMaMa_Windows.bat to download the heavy optional Alpha Hint generator weights.
For Linux / Mac Users (Automated):
- Clone or download this repository to your local machine.
- Open terminal and write
bash. Put a space after writing bash.
- Drag and drop
Install_CorridorKey_Linux_Mac.sh into the terminal. Then press enter.
- (Optional) Do the 2. step again. But now drag and drop
Install_GVM_Linux_Mac.sh and Install_VideoMaMa_Linux_Mac.sh to download the heavy optional Alpha Hint generator weights.
For Linux / Mac Users (Manual):
- Clone or download this repository to your local machine.
- Install uv if you don't have it:
curl -LsSf https://astral.sh/uv/install.sh | sh
- Install all dependencies (uv will download Python 3.10+ automatically if needed):
uv sync # CPU/MPS (default — works everywhere)
uv sync --extra cuda # CUDA GPU acceleration (Linux/Windows)
uv sync --extra mlx # Apple Silicon MLX acceleration
For AMD ROCm setup, see the AMD ROCm Setup section below.
- Download the Models:
- CorridorKey v1.0 Model (~300MB): Downloads automatically on first run. If no checkpoint is found in
CorridorKeyModule/checkpoints/, the engine fetches it from CorridorKey's HuggingFace and saves it as CorridorKey_v1.0.safetensors (preferred — safer, no pickle). Legacy .pth files are still loaded automatically if already present. No manual download needed.
- CorridorKeyBlue 1.0 Model (~300MB): Dedicated blue-screen checkpoint. Downloaded on demand the first time you run with
--screen-color blue (or when auto-detection picks blue) from CorridorKeyBlue's HuggingFace, saved as CorridorKeyBlue_1.0.safetensors. The two models coexist in checkpoints/ and are picked automatically per clip.
- GVM Weights (Optional): HuggingFace: geyongtao/gvm
- Download using the CLI:
uv run hf download geyongtao/gvm --local-dir gvm_core/weights
- VideoMaMa Weights (Optional): HuggingFace: SammyLim/VideoMaMa
- Download the VideoMaMa fine-tuned weights:
uv run hf download SammyLim/VideoMaMa --local-dir VideoMaMaInferenceModule/checkpoints/VideoMaMa
- VideoMaMa also requires the Stable Video Diffusion base model (VAE + image encoder only, ~2.5GB). Accept the license at stabilityai/stable-video-diffusion-img2vid-xt, then:
uv run hf download stabilityai/stable-video-diffusion-img2vid-xt \
--local-dir VideoMaMaInferenceModule/checkpoints/stable-video-diffusion-img2vid-xt \
--include "feature_extractor/*" "image_encoder/*" "vae/*" "model_index.json"
- VideoMaMa is an amazing project, please go star their repo and show them some support!
2. How it Works
CorridorKey requires two inputs to process a frame:
- The Original RGB Image: The to-be-processed green or blue screen footage. This requires the sRGB color gamut (interchangeable with REC709 gamut), and the engine can ingest either an sRGB gamma or Linear gamma curve.
- A Coarse Alpha Hint: A rough black-and-white mask that generally isolates the subject. This does not need to be precise. It can be generated by you with a rough chroma key or AI roto.
By default the screen color is auto-detected from the first frame's background pixels (where the alpha hint is dark). Pass --screen-color green or --screen-color blue to skip detection and force a specific checkpoint.
I've had the best results using GVM or VideoMaMa to create the AlphaHint, so I've repackaged those projects and integrated them here as optional modules inside clip_manager.py. Here is how they compare:
- GVM: Completely automatic and requires no additional input. It works exceptionally well for people, but can struggle with inanimate objects.
- VideoMaMa: Requires you to provide a rough VideoMamaMaskHint (often drawn by hand or AI) telling it what you want to key. If you choose to use this, place your mask hint in the
VideoMamaMaskHint/ folder that the wizard creates for your shot. VideoMaMa results are spectacular and can be controlled more easily than GVM due to this mask hint.
- Please go show the creators of these projects some love and star their repos. VideoMaMa and GVM
Perhaps in the future, I will implement other generators for the AlphaHint! In the meantime, the better your Alpha Hint, the better CorridorKey's final result will be. Experiment with different amounts of mask erosion or feathering. The model was trained on coarse, blurry, eroded masks, and is exceptional at filling in details from the hint. However, it is generally less effective at subtracting unwanted mask details if your Alpha Hint is expanded too far.
Please give feedback and share your results!
Docker (Linux + NVIDIA GPU)
If you prefer not to install dependencies locally, you can run CorridorKey in Docker.
Prerequisites:
- Docker Engine + Docker Compose plugin installed.
- NVIDIA driver installed on the host (Linux), with CUDA compatibility for the PyTorch CUDA 12.6 wheels used by this project.
- NVIDIA Container Toolkit installed and configured for Docker (
nvidia-smi should work on host, and docker run --rm --gpus all nvidia/cuda:12.6.3-runtime-ubuntu22.04 nvidia-smi should succeed).
- Build the image:
docker build -t corridorkey:latest .
- Run an action directly (example: inference):
docker run --rm -it --gpus all \
-e OPENCV_IO_ENABLE_OPENEXR=1 \
-v "$(pwd)/ClipsForInference:/app/ClipsForInference" \
-v "$(pwd)/Output:/app/Output" \
-v "$(pwd)/CorridorKeyModule/checkpoints:/app/CorridorKeyModule/checkpoints" \
-v "$(pwd)/gvm_core/weights:/app/gvm_core/weights" \
-v "$(pwd)/VideoMaMaInferenceModule/checkpoints:/app/VideoMaMaInferenceModule/checkpoints" \
corridorkey:latest run_inference --device cuda
- Docker Compose (recommended for repeat runs):
docker compose build
docker compose --profile gpu run --rm corridorkey run_inference --device cuda
docker compose --profile gpu run --rm corridorkey list
docker compose --profile cpu run --rm corridorkey-cpu run_inference --device cpu
- Optional: pin to specific GPU(s) for multi-GPU workstations:
NVIDIA_VISIBLE_DEVICES=0 docker compose --profile gpu run --rm corridorkey list
NVIDIA_VISIBLE_DEVICES=1,2 docker compose --profile gpu run --rm corridorkey run_inference --device cuda
Notes:
3. Usage: The Command Line Wizard
For the easiest experience, use the provided launcher scripts. These scripts launch a prompt-based configuration wizard in your terminal.
- Windows: Drag-and-drop a video file or folder onto
CorridorKey_DRAG_CLIPS_HERE_local.bat (Note: Only launch via Drag-and-Drop or CMD. Double-clicking the .bat directly will throw an error).
- Linux / Mac: Run or drag-and-drop a video file or folder onto
./CorridorKey_DRAG_CLIPS_HERE_local.sh.
- Or write
bash again in terminal. Put a space after and then drag-and-drop CorridorKey_DRAG_CLIPS_HERE_local.sh and your clip folder together into terminal, respectively. Then press enter.
Workflow Steps:
- Launch: You can drag-and-drop a single loose video file (like an
.mp4), a shot folder containing image sequences, or even a master "batch" folder containing multiple different shots all at once onto the launcher script.
- Organization: The wizard will detect what you dragged in. If you dropped loose video files or unorganized folders, the first prompt will ask if you want it to organize your clips into the proper structure.
- If you say Yes, the script will automatically create a shot folder, move your footage into an
Input/ sub-folder, and generate empty AlphaHint/ and VideoMamaMaskHint/ folders for you. This structure is required for the engine to pair your hints and footage correctly!
- Generate Hints (Optional): If the wizard detects your shots are missing an
AlphaHint, it will ask if you want to generate them automatically using the repackaged GVM or VideoMaMa modules.
- Configure: Once your clips have both Inputs and AlphaHints, select "Process Ready Clips". The wizard will prompt you to configure the run:
- Gamma Space: Tell the engine if your sequence uses a Linear or sRGB gamma curve.
- Despill Strength: This is a traditional despill filter (0-10), if you wish to have it baked into the output now as opposed to applying it in your comp later.
- Auto-Despeckle: Toggle automatic cleanup and define the size threshold. This isn't just for tracking dots, it removes any small, disconnected islands of pixels.
- Refiner Strength: Use the default (1.0) unless you are experimenting with extreme detail pushing.
- Result: The engine will generate several folders inside your shot directory:
/Matte: The raw Linear Alpha channel (EXR)./FG: The raw Straight Foreground Color Object. (Note: The engine natively computes this in the sRGB gamut. You must manually convert this pass to linear gamma before being combined with the alpha in your compositing program)./Processed: An RGBA image containing the Linear Foreground premultiplied against the Linear Alpha (EXR). This pass exists so you can immediately drop the footage into Premiere/Resolve for a quick preview without dealing with complex premultiplication routing. However, if you want more control over your image, working with the raw FG and Matte outputs will give you that./Comp: A simple preview of the key composited over a checkerboard (PNG).
But What About Training and Datasets?
If enough people find this project interesting I'll get the training program and datasets uploaded so we can all really go to town making the absolute best keyer fine tunes! Just hit me with some messages on the Corridor Creates discord or here. If enough people lock in, I'll get this stuff packaged up. Hardware requirements are beefy and the gigabytes are plentiful so I don't want to commit the time unless there's demand.
Device Selection
By default, CorridorKey auto-detects the best available compute device: CUDA > MPS > CPU.
Override via CLI flag:
uv run python clip_manager.py --action wizard --win_path "V:\..." --device mps
uv run python clip_manager.py --action run_inference --device cpu
Override via environment variable:
export CORRIDORKEY_DEVICE=cpu
uv run python clip_manager.py --action wizard --win_path "V:\..."
Priority: --device flag > CORRIDORKEY_DEVICE env var > auto-detect.
Apple Silicon / MPS Troubleshooting
Confirm MPS is active: Run with verbose logging to see which device was selected:
uv run python clip_manager.py --action list 2>&1 | grep -i "device\|backend\|mps"
MPS operator errors (NotImplementedError: ... not implemented for 'MPS'): Some PyTorch operations are not yet supported on MPS. Enable CPU fallback for those ops:
export PYTORCH_ENABLE_MPS_FALLBACK=1
uv run python corridorkey_cli.py wizard --win_path "/path/to/clips"
Silent CPU fallback: If MPS silently falls back to CPU without this variable, the run will be much slower. Setting PYTORCH_ENABLE_MPS_FALLBACK=1 in your shell profile (~/.zshrc) ensures it is always active.
Use native MLX instead of PyTorch MPS: MLX avoids PyTorch's MPS layer entirely and typically runs faster on Apple Silicon. See the Backend Selection section below for setup steps.
AMD ROCm Setup
CorridorKey supports AMD GPUs via PyTorch's ROCm/HIP backend. The torch.cuda.* API works transparently on AMD — HIP intercepts all CUDA calls at runtime, so the inference code runs unchanged.
Supported GPUs (ROCm 7.2+):
- RX 7900 XTX (24GB) / XT (20GB) / GRE (16GB) — RDNA3, gfx1100
- RX 7800 XT (16GB) / 7700 XT (12GB) — RDNA3, gfx1101
- RX 9070 XT / 9070 (16GB) — RDNA4, gfx1201
VRAM requirements: CorridorKey inference at 2048x2048 uses ~10GB on NVIDIA but ~18GB on AMD due to HIP allocator overhead. The RX 7900 XTX (24GB) and RX 7900 XT (20GB) run at full resolution. Cards with 16GB (RX 7800 XT, 9070 XT) work on Windows (which uses system RAM as overflow) but may OOM on Linux — see notes below.
Linux native (recommended):
uv sync --extra rocm
# Verify
uv run python -c "import torch; print(torch.cuda.is_available(), to
CorridorKey 是一款基于神经网络的工具，可对绿幕或蓝幕素材进行抠像。它会为每个像素预测真实的、未预乘的前景颜色，以及干净的线性 Alpha 通道，包括运动模糊或焦外边缘等半透明像素。