CorridorKey: Open-Source AI Tool Solves Chroma Key Compositing

The Unmixing Problem

The core innovation of CorridorKey is its approach to semi-transparency. When a red gel is held in front of a green screen, the camera captures a purple pixel. A standard keyer sees this as a color value to be removed or kept. A neural network, however, can be trained to recognize the relationship between the foreground object and the background.

By training the model on complex, semi-transparent scenarios, the network learns to “unmix” the colors. It identifies the foreground color and the background color independently, allowing it to reconstruct the subject’s true color even when the background is bleeding into the edges.

Procedural Data Generation

Training a neural network requires scale — and manually masking thousands of clips was unsustainable. The Corridor team solved this with procedural generation.

Using Houdini and Blender, they established a pipeline to generate thousands of unique renders of subjects against green screens. Because these clips were rendered in 3D, the team had access to the perfect alpha channel — the “Ground Truth.” They could render the subject with the background and with a transparent background simultaneously, allowing the neural network to compare its predictions against a flawless reference.

Niko set up controllers to randomize lighting, object texture, and camera angle so every render triggered a new, unique variation. This procedural approach transformed what would have been a manual, multi-year task into a scalable, automated process.

The Model Architecture: GreenFormer

Under the hood, CorridorKey uses a custom neural network called GreenFormer — a hybrid architecture that combines a vision transformer encoder with convolutional decoders and a CNN refiner. You can explore the full auto-generated codebase docs on DeepWiki.

Encoder: The backbone is hiera_base_plus_224, a hierarchical vision transformer from Meta AI, pre-trained with Masked Autoencoder (MAE) on ImageNet-1K and then fine-tuned on ImageNet-1K. The encoder is loaded via the timm (PyTorch Image Models) library by Ross Wightman, using timm.create_model with features_only=True. It extracts multi-scale features at four hierarchical levels, providing both fine-grained local detail and broad contextual understanding.

Input: The model accepts 4 channels — RGB + a coarse alpha hint. Rather than adding a separate projection layer, Niko used a clever weight patching technique: the first convolutional layer’s weights are expanded from 3 to 4 channels, preserving all pretrained RGB weights while zero-initializing the alpha channel. This means the model keeps everything it learned from ImageNet while learning to incorporate the alpha hint from scratch.

Dual Decoders: Instead of a shared decoder with multiple output heads, GreenFormer uses two completely independent DecoderHead instances — one for alpha matte, one for foreground RGB. This allows task-specific feature fusion, since alpha matting benefits from different feature combinations than color reconstruction.

CNN Refiner: After the initial decode, a dilated residual CNN refiner with a ~65px receptive field addresses macroblocking artifacts and smooths the output. This is critical for eliminating the blocky artifacts that vision transformers tend to produce at tile boundaries.

Resolution Independence: Positional embeddings are baked-in rather than learned, allowing the model to operate beyond its native 2048×2048 training resolution — it dynamically scales to handle 4K plates.

The Workflow

The actual usage is straightforward:

1. Input: Feed CorridorKey your green-screen footage and a rough “alpha hint” — a quick-and-dirty mask from any basic keyer
2. Processing: The neural network refines that rough mask into a professional-grade matte
3. Output: A clean, linear alpha channel in 16-bit or 32-bit float EXR format — the industry standard for high-end V workflows

The tool handles the hard cases automatically: fine hair strands, translucent materials, motion blur, and edge contamination.

EZ-CorridorKey — Free GUI

The most popular community wrapper is EZ-CorridorKey by Ed Zisk, a full-featured GUI application that has garnered over 2.6k GitHub stars. It adds:

• Drag-and-drop project management — import single clips or entire folders
• Three keying modes — fully automatic (Auto GVM), annotation brush-guided (VideoMaMa), and manual alpha hint
• Real-time dual viewer — side-by-side input vs output preview with live parameter adjustment
• Batch processing — queue multiple clips with progress bars and ETA
• Built-in masking tools — brush tool for VideoMaMa and MatAnyone2 masks
• Alpha generators — one-click integration of GVM, BiRefNet, VideoMaMa, and MatAnyone2 for generating coarse alpha hints
• Live VRAM meter and 20+ keyboard shortcuts
• Apple Silicon support via MLX acceleration (auto-detected)

The project also bundles optional modules that the upstream CLI lacks: SAM 2.1 for segmentation, GVM for generative video matting, VideoMaMa for temporal consistency, MatAnyone2 for person-specific matting, and BiRefNet for bidirectional reference segmentation.

DaVinci Resolve OFX Plugin

gitcapoom built corridorkey_ofx, an OFX plugin that brings CorridorKey into DaVinci Resolve 20 as a native node. The plugin uses Windows-specific APIs (named pipes, shared memory) for IPC between the C++ plugin and Python backend, making it a Windows-only release for now.

Nuke Plugin — TRTCorridorKey

Peter Mercell converted the PyTorch model to ONNX and then TensorRT, building a native Nuke C++ plugin called TRTCorridorKey. It runs inference at approximately 300ms per frame at 2048×2048 FP16 on an RTX A5000 (24GB). The plugin presents as a two-input Nuke node:

• Input 0 (plate): RGB green screen footage
• Input 1 (mask): Coarse alpha hint
• Output: RGBA — unmixed foreground color in RGB + linear alpha in A

After Effects Plugin

An After Effects implementation, CorridorKey for Green Screens, is available as a free download on aescripts. It provides a GPU-based effect node for After Effects users, though early reports note it requires 24GB VRAM and can be slow on consumer hardware.

ComfyUI Integration

A ComfyUI custom node for CorridorKey-style edge-aware coarse mask refinement is also available, letting generative AI workflows incorporate the keyer into their node graphs. ComfyUI users note that while the process is heavy and slow, it handles what would otherwise require significant manual work.

CorridorKey-Engine and Other Forks

The community has also produced performance-focused forks like CorridorKey-Engine by 99oblivius (FX graph caching optimization), corridorkey-mlx by Cristopher Yates (MLX acceleration for Apple Silicon), and tiling optimizations by MarcelLieb for lower-VRAM systems.