CorridorKey: Neural Green Screen Unmixing for VFX Pipelines

The unmixing problem CorridorKey targets

A green screen plate is not two images. It is one image in which every edge pixel is a weighted sum of foreground colour and screen colour, and the weight is the alpha you are trying to recover. A keyer that outputs a binary mask throws that weight away. You get a hard edge, and the semi-transparent pixels that carry hair, motion blur and defocused edges are either fully in or fully out. The README frames this as the reason the project exists: the author describes building CorridorKey to solve the unmixing problem, and states that even modern AI roto tools typically output a harsh binary mask that destroys the semi-transparent pixels a composite needs.

The claim is narrower than a general keyer. For each pixel the model predicts the un-multiplied straight colour of the foreground and a linear alpha, so the green contribution is removed from the colour rather than merely masked. The README describes this as reconstructing the colour of the foreground as if the green screen was never there. That matters in comp: a despilled edge pixel with a wrong colour still reads as wrong once it is over a new background, no matter how good the alpha is.

Who this is for is implied by the outputs rather than stated. The README lists 16-bit and 32-bit linear float EXR read and write, and names Nuke, Fusion and Resolve as integration targets. The pyproject description calls it neural network green screen keying for professional VFX pipelines. This is a compositor's tool, not an editor's effect.

How the network, the AlphaHint and the despill fit together

The pipeline is a batch job over clips, not an interactive keyer. You place clips in a folder, the engine reads frames, runs inference, and writes results to an output directory. The repository layout reflects this: ClipsForInference/ is the input drop, Output/ is the destination, and clip_manager.py plus corridorkey_cli.py are the entry points that walk the batch.

The backbone is described as a native 2048x2048 high-fidelity model, with inference dynamically scaled so 4K plates can be processed through that fixed resolution. That is a deliberate trade: the network sees a normalised view of the plate and the engine handles the scaling, which is why the README can call the result resolution independent without claiming a per-resolution model.

Screen colour is chosen by a heuristic. With the default --screen-color auto, CorridorKey samples the first frame of the first clip in the batch and picks the dominant screen colour from the background pixels. Passing --screen-color green or --screen-color blue skips the heuristic and forces the choice. The despill then removes spill from the channel you are actually shooting against. The README states this is currently Torch backend only, and that the MLX path is green-screen until a blue MLX checkpoint ships.

The AlphaHint is the part worth reading twice. CorridorKey does not work from nothing; the README says you give it a hint of what you want. Three optional generators are bundled: GVM, VideoMaMa and BiRefNet, the last described as a lightweight option. The others are not lightweight. GVM is documented as requiring roughly 80 GB of VRAM and large Stable Video Diffusion models, and VideoMaMa is described as originally needing 80GB+, with community tweaks below 24GB that the README says have not been fully implemented here. The README is explicit that providing your own hint from an editing program, BiRefNet or any other method is fine, and that the better the AlphaHint, the better the result. That sentence is the honest summary of the architecture: the hint is a real input to quality, and the bundled generators that would automate it are the most expensive part of the stack.

Finally, a morphological cleanup system prunes tracking markers and small background features that slip through detection. That is a post-process on the alpha, and the README presents it as automatic rather than configurable.

Installing CorridorKey with uv on Windows, Linux or macOS

Dependencies are managed by uv, which the README describes as handling Python installation, virtual environments and packages in one step. You do not install Python yourself. On Windows the documented path is to clone the repository and double-click Install_CorridorKey_Windows.bat, which installs uv if needed, sets up the environment, installs dependencies and downloads the model. The README notes one wrinkle: if uv was installed for the first time, terminals that were already open will not see it, and you should close and reopen them if you get a uv is not recognized error.

On Linux and macOS the automated route is the shell script. The README gives an unusual instruction for it: type bash, add a space, drag the script into the terminal, then press enter.

bash Install_CorridorKey_Linux_Mac.sh

The manual route starts with uv itself, then a sync. The extras select the compute backend, and the README lists three.

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync                  # CPU/MPS (default, works everywhere)
uv sync --extra cuda     # CUDA GPU acceleration (Linux/Windows)

A fourth extra, mlx, is declared in pyproject.toml as corridorkey-mlx for Python 3.11 and above, which is the Apple silicon path. The ROCm extra exists for AMD on Linux, and pyproject.toml pins pytorch-triton-rocm for x86_64 Linux only.

The optional hint generators are separate installers, Install_GVM_Windows.bat and Install_VideoMaMa_Windows.bat on Windows, and the equivalent shell scripts elsewhere. The README calls these completely optional because of the model sizes and hardware demands, and repeats that you can supply your own AlphaHint instead.

For a first run, the Dockerfile sets the entry point to the CLI and defaults to listing work rather than processing it.

ENTRYPOINT ["/app/.venv/bin/python", "corridorkey_cli.py"]
CMD ["--action", "list"]

That default is a useful sanity check: build the image, run it, and you should get a listing of clips rather than an inference run. The compose file defines two profiles, gpu and cpu, and both mount ClipsForInference, Output and the three checkpoint directories as volumes, so the container reads your plates from the host and writes EXRs back to the host. OPENCV_IO_ENABLE_OPENEXR=1 is set as an environment variable in the image and in compose, which is what enables OpenEXR support in OpenCV. Without it, EXR handling in the OpenCV path is not enabled.

Where CorridorKey breaks or is the wrong tool

The README carries an alert at the top calling this a brand new release and inviting patches and pull requests, and the author writes that he has not tested everything. Treat the first release as something you validate on your own footage before it sits in a delivery pipeline.

The hardware floor is the first real constraint. The project was designed and built on a Linux workstation with an NVIDIA RTX Pro 6000 and 96GB of VRAM. The README says the most recent build should work on 6-8GB of VRAM and on most M1+ Macs with unified memory, but that is a statement about the build, not a benchmark, and the optional generators sit far above it. On Windows with NVIDIA, the README states your drivers must support CUDA 12.8 or higher, and that if they only support older CUDA versions the installer will likely fall back to the CPU. A silent fallback is the worst kind of failure here: the run completes, and you only find out when you look at the clock.

AMD support is split by platform. RDNA3 and RDNA4 cards are supported through ROCm on Linux. Windows ROCm is described as experimental, and torch.compile is stated not to be functional there. If you are on an AMD Windows machine, this is not the tool for you yet.

Blue screen has a backend boundary. The dedicated blue checkpoint works on the Torch path, but the README says the MLX path is green-screen until the blue MLX checkpoint ships. An Apple silicon user shooting blue screen is on the wrong side of that line.

The AlphaHint generators are the biggest practical gap. GVM needs roughly 80GB of VRAM. VideoMaMa's memory optimisations are described as not yet fully implemented in this repository. That leaves BiRefNet or an external hint as the realistic default, and it means the quality of your result depends on a step CorridorKey does not perform for you.

Where it is the wrong tool: inside an NLE. There is no After Effects, Premiere Pro or Resolve plugin in this repository. It is a batch CLI that reads folders and writes EXRs, so if your work lives in an editing timeline, the integration is a round trip through a compositor, not a drag-and-drop effect.

CorridorKey compared with a traditional keyer

The difference is what the output represents. A conventional chroma keyer, the kind built into Nuke, Fusion or Resolve, estimates alpha from the screen colour and then applies despill to the RGB. The alpha is the primary product and the colour is patched afterwards. CorridorKey inverts the emphasis: the network predicts the straight foreground colour and the alpha together, so the colour is reconstructed rather than corrected.

That distinction shows up in the failure cases. A traditional keyer with a bad edge produces a fringe you fight with core and edge mattes, which is exactly the workflow the README describes as the thing it wants to replace. A network that predicts colour can produce a plausible edge over a new background without a spill-correction pass, but it can also hallucinate colour where the hint is poor, and the README's own advice that the better the AlphaHint the better the result is an admission of that dependency.

The second difference is control. A traditional keyer exposes sliders: screen colour, clip black, clip white, edge blur, despill strength. CorridorKey exposes a screen colour choice and a hint. You trade tunability for a model that decides, which is faster when it is right and harder to steer when it is not. The morphological cleanup is described as automatic, so the same applies to marker removal.

The third is format. Traditional keyers operate on whatever the host application holds in memory. CorridorKey reads and writes 16-bit and 32-bit linear float EXR natively, which is the format a VFX pipeline wants and the reason the README names Nuke, Fusion and Resolve rather than an NLE.

Licence, maintenance and upgrade cost

The licence is the first thing to check. The repository LICENSE file is not classified in the metadata, but pyproject.toml declares license = { text = "CC-BY-NC-SA-4.0" } and names Corridor Digital as the author. CC-BY-NC-SA-4.0 is a Creative Commons licence with a non-commercial restriction and a share-alike term. That is not a typical software licence, and it is worth reading in full before you build a commercial service on top of the model or redistribute a modified version. This is a description of what the file says, not legal advice.

Maintenance is active on the evidence available. The repository is not archived, and the last push was on 2026-05-28. Renovate is configured in the repository, which suggests dependency updates are intended to be automated, and the README points to a Discord for ideas, forks and work.

Upgrade cost is dominated by the model weights and the pinned stack. torch and torchvision are pinned to exact versions in pyproject.toml, and the CUDA, ROCm and MLX paths each carry their own pins. A torch bump means re-validating whichever backend you use, and the ROCm path additionally pins pytorch-triton-rocm for x86_64 Linux. The Dockerfile uses uv sync --frozen, so container builds follow uv.lock rather than resolving fresh. If you run the optional generators, their weights are large and live in mounted checkpoint directories, which means a rebuild does not necessarily re-download them but a fresh machine will.

The practical upgrade question is whether a new checkpoint changes your keys. The README does not document a checkpoint versioning or rollback scheme, so plan on keeping the weights you validated against if you need reproducible output.

Editorial conclusion

Adopt CorridorKey if you already composite in Nuke, Fusion or Resolve, your plates are EXR, and you have a CUDA 12.8+ NVIDIA card or an M1+ Mac to run the MLX path. Do not adopt it if you need a native After Effects or Premiere Pro plugin, a Windows ROCm build, or blue-screen support on Apple silicon, since the README states the MLX path is green-screen only. Before committing, verify three things on your own footage: that your driver reports CUDA 12.8 or higher, that a short clip survives the uv sync --extra cuda install and the corridorkey_cli.py run, and that the CC-BY-NC-SA-4.0 licence is acceptable for the work you intend to do with the output.

Frequently asked questions

Official sources

1. Issues
2. nikopueringer/CorridorKey on GitHub
3. README