EZ-CorridorKey v2.1.5

Latest release: v2.1.5: Matte quality fix. AI alpha mattes no longer trace a thin dark band around the subject on high-resolution footage (#179), and alpha is now clamped to the valid range after upscaling so premultiplied output stays clean. See the full changelog.

A full desktop GUI for Niko Pueringer's CorridorKey — the AI chroma keyer by Corridor Digital that physically unmixes foreground from background, preserving hair, motion blur, and translucency.

This GUI replaces the CLI drag-and-drop workflow with a complete desktop application while preserving 100% backward compatibility (python main.py --cli still runs the original wizard).

Official site, install guide, and downloads: ezcorridorkey.com

Contents

• Installation — Desktop installer, CLI setup, Docker
• Uninstalling — Remove the app cleanly
• Application Layout — UI overview
• Quick Start — Import, generate alpha, run inference
• Keyboard Shortcuts — Full hotkey reference
• View Modes — Output channel switching
• Inference Controls — Parameters and output formats
• Hardware Requirements — VRAM, GPU, and platform info
• Security — Verified downloads, signed updates, checksums
• Localization — Translate EZ-CorridorKey into your language
• Contributing — How to help and get help

---

Installation

Prefer video? Watch the step-by-step tutorial by the app's creator:

Desktop App Installer (recommended)

Don't want to deal with Python, git, or the command line? A full Windows installer and portable exe are available. Mac users can grab the v2.0.0 macOS .pkg while the native Mac app is in production. Entirely optional and free, donations help support active development.

The installer includes everything — Python runtime, AI models, GPU libraries — no setup required. Just install and run.

Terminal (CLI) Install (Windows / macOS / Linux)

1. Clone or download this repository.
2. The one-click path provisions and uses managed Python 3.11 automatically, so you do not need to pre-install Python just to use 1-install.
3. Run the installer for your platform:
   • Windows: Double-click 1-install.bat
   • macOS / Linux: chmod +x 1-install.sh && ./1-install.sh
4. The installer handles everything: managed Python, virtual environment, dependencies (including the correct PyTorch backend for your GPU when available), verification, and model downloads.
5. To launch: double-click 2-start.bat (Windows) or ./2-start.sh (macOS/Linux).

Prerequisites:

• For the one-click installer: no preinstalled Python required
• For manual installs: Python 3.10–3.13 (3.14 is not yet supported)
• Windows/Linux: NVIDIA GPU with CUDA support (8 GB+ VRAM recommended). Keep your driver current — the installer verifies the torch runtime and will stop with diagnostics instead of silently leaving you on the wrong backend.
• macOS: Apple Silicon (M1+). CorridorKey inference runs natively via MLX (1.5–2x faster than MPS). GPU-intensive alpha generators (SAM2, GVM, VideoMaMa, MatAnyone2) run on MPS but are significantly slower — importing pre-made alpha mattes is recommended on Mac.

What the installer does:

• Checks for Visual Studio Build Tools (C++ compiler needed by OpenEXR) — offers to auto-install if missing
• Installs uv and provisions managed Python 3.11 for the installer path
• Creates a .venv virtual environment in the project folder
• Installs the correct PyTorch backend for your platform/GPU and verifies the resulting torch runtime before reporting success
• Downloads and installs FFmpeg locally if not found on PATH (used for video import)
• Downloads the CorridorKey model checkpoint (383 MB, required)
• Optionally installs SAM2 tracking support and pre-downloads the default Base+ checkpoint (324 MB)
• Optionally downloads BiRefNet (~940 MB), MatAnyone2 (~135 MB), GVM (~6 GB), and VideoMaMa (~37 GB) alpha hint generators
• Creates a desktop shortcut (optional)

Updating:

• Windows Desktop App Installer users: The app checks for updates automatically. When a new version is available, click the update button in the app. It downloads a lightweight patch and relaunches.
• macOS Desktop App users: The app checks for updates automatically. When a new version is available, click the update button in the app. It downloads a lightweight patch and relaunches.
• CLI users: Double-click 3-update.bat (Windows) or run ./3-update.sh (macOS/Linux). This pulls the latest code via git, or downloads a ZIP if git isn't available.

Note: The update ZIP on GitHub Releases (EZ-CorridorKey-windows-x64.zip) is for Windows Desktop App Installer users only. It patches an existing installation. CLI users should continue using 3-update.bat / 3-update.sh.

Alternate Installation: Docker

For Linux users or remote/cloud setups, EZ-CorridorKey can run inside Docker with browser-based access via noVNC. See docker/README.md for setup instructions. The native install above is recommended for Windows and macOS.

---

Uninstalling

Desktop app installer

Windows: ☼ Open Settings > Apps > Installed Apps ☼ Find EZ-CorridorKey and click Uninstall ☼ This removes the application and Start Menu shortcut ☼ Your projects and downloaded models are stored in %APPDATA%\EZ-CorridorKey\. Delete that folder to remove all user data.

macOS: ☼ Drag /Applications/EZ-CorridorKey.app to the Trash ☼ Your projects, preferences, and downloaded models are stored in ~/Library/Application Support/EZ-CorridorKey/. Delete that folder to remove all user data.

CLI install (git clone)

☼ Delete the cloned repository folder (e.g. EZ-CorridorKey/). This includes the .venv virtual environment, downloaded models, and all project data inside Projects/. ☼ If you created a desktop shortcut during install, delete it manually. ☼ No system-level files are modified by the CLI install. Nothing else to clean up.

Hugging Face model cache

Some optional models (BiRefNet, SAM2) are downloaded via Hugging Face Hub and cached outside the project folder. To reclaim that disk space:

☼ Windows: %USERPROFILE%\.cache\huggingface\hub\ ☼ macOS / Linux: ~/.cache/huggingface/hub/

This cache is shared across all applications that use Hugging Face. If you use other AI tools, only delete the specific model folders (e.g. models--ZhengPeng7--BiRefNet, models--facebook--sam2.1-hiera-base-plus) rather than the entire hub/ directory.

---

Application Layout

+--------------------------------------------------------------------+
| File | Edit | View | Help                             Volume ---->-|
| CORRIDORKEY                                        RTX 5090  ## 4GB|
+------+------------------------+---------------------+--------------+
|      |      241 frames - RAW | IN|FG|MATTE[COMP]PROC| ALPHA GEN    |
|  Q   |                       |                      |  GVM/BIREFNET|
|  U   +-----------------------+----------------------+  MATANYONE2  |
|      |                       |                      |  VIDEOMAMA   |
|  E   |                       |                      |  EXPORT MASK |
|  U   |                       |                      |--------------+
|  E   |   INPUT viewer        |   OUTPUT viewer      | INFERENCE    |
|      |   (left image)        |   (right image)      |  Color Space |
|      |                       |                      |  Despill     |
| tab  |                       |                      |  Despeckle   |
|      |                       |                      |  Refiner     |
|      |                       |                      |  Live Preview|
|      |                       |                      |--------------+
|      |                       |                      | OUTPUT       |
|      |                       |                      |  FG          |
|      |                       |                      |  Matte       |
|      |                       |                      |  Comp        |
|      |                    SCRUBBER                  |  Processed   |
|------+<<-<-------In=====================Out----->->>+--------------|
|INPUT (3)               + ADD | EXPORTS (2)                         |
| +-----+ +-----+ +-----+      | +-----+ +-----+                     |
| |thumb| |thumb| |thumb|      | |thumb| |thumb| ..                  |
| +-----+ +-----+ +-----+      | +-----+ +-----+                     |
+--------------------------------------------------------------------+
|  Status Bar                                         [RUN INFERENCE]|
+--------------------------------------------------------------------+

• Brand bar + menu — top row with logo, menu bar, GPU name + VRAM meter
• Queue panel — collapsible sidebar (left), toggle with Q
• Dual viewer — center, split into INPUT (left) and switchable output (right)
• Parameter panel — right sidebar with Alpha Generation, Inference, and Output controls
• I/O tray — horizontal thumbnail strip below the viewer
• Status bar — progress bar and RUN INFERENCE button

---

Quick Start

1. Import

Drop a video file onto the welcome screen (or File > Import Clips > Import Video). The video is automatically extracted to a high-quality image sequence:

1. FFmpeg extracts each frame as EXR half-float (ZIP16 compression)
2. Recompression pass converts ZIP16 → DWAB (VFX-standard lossy compression, ~4× smaller)

This two-pass approach preserves full floating-point precision from the video decoder — no 8-bit quantization, no banding. Even 8-bit source video benefits because FFmpeg's internal YUV→RGB conversion stays in float, avoiding rounding errors that accumulate in integer pipelines. The DWAB-compressed EXR frames are typically comparable in size to PNG while retaining 16-bit half-float dynamic range.

The recompression runs in a separate process so the UI stays fully responsive during extraction.

Companion hints: files with "alphahint" or "maskhint" anywhere in the filename (case insensitive) are automatically paired with the matching clip as alpha or mask hints instead of being imported as separate clips. Works for video imports and frame sequence folders alike.

2. Generate Alpha Hint

Your clip starts in RAW state (gray badge). You need an alpha hint before running inference.

Option A — Chroma Key (manual, no AI model): Click CHROMA KEY in the parameter panel. Color-difference keyer for green or blue screen footage. Press E to activate the eyedropper, then drag across the screen to sample a range of colors. Adjust Key Strength, Clip Black, and Clip White to refine the matte. Click GENERATE to produce the alpha hint.

Option B — One-click alpha generators:

• GVM Auto — click GVM AUTO in the parameter panel. Works great for most green screen footage with people.
• BiRefNet (recommended) — click BIREFNET in the parameter panel. Fast, accurate, and works well on a wide range of footage.
• Apple Vision (macOS 14+) — click APPLE VISION in the parameter panel. Apple's Neural Engine segments the foreground, no painting or annotation needed. Auto-hidden on other platforms.

Option C — MatAnyone2 / VideoMaMa: These models need a mask hint. Two ways to provide one:

C1. Paint + Track (from scratch):

1. Press 1 to activate foreground mode (green)
2. Paint over the subject on a few key frames
3. Press 2 to switch to background mode (red)
4. Paint over background areas
5. Click TRACK MASK to generate a dense SAM2 mask track
6. Click MATANYONE2 or VIDEOMAMA in the parameter panel

C2. Import mask (bring your own):

1. Click the + button next to VIDEOMAMA to import a pre-made mask sequence or video
2. Click MATANYONE2 or VIDEOMAMA to run the model

Option D — Import Alpha (bring your own): If you already have alpha mattes from another tool (Rotobrush, Silhouette, Resolve, Nuke, etc.), click IMPORT ALPHA in the parameter panel and choose either an image folder or a matte video file.

• Supported image formats: PNG, JPG, JPEG, TIF, TIFF, EXR
• Supported alpha-video path: standard video files accepted by the normal clip importer (for example MOV or MP4)
• Images and visible matte videos should be grayscale (white = foreground, black = background)
• Frame count should match your input sequence
• Non-PNG stills are automatically converted to grayscale PNG on import
• Imported alpha videos are decoded into grayscale AlphaHint/*.png frames so they follow the same downstream path as image-sequence hints
• Imported files are copied into the clip's AlphaHint/ folder and the clip advances to READY state

You can re-import at any time — if the clip already has alpha hints, you'll be asked whether to overwrite them.

3. Run Inference

Your clip is now READY (yellow badge). Adjust parameters as needed, then click RUN INFERENCE (or Ctrl+R).

Batch Pipeline (Unattended)

Two ways to run a batch:

From the I/O tray: select multiple clips (Ctrl+click or Shift+click), then click RUN PIPELINE in the status bar.

From a folder: File > Batch Pipeline opens a dialog for processing an entire folder of clips. Pick the folder, choose which alpha generation model to use (GVM, BiRefNet, VideoMaMa, MatAnyone2), and run everything autonomously. Per-clip overrides let you mix models in one batch. Live progress bars and checkmarks track each clip's status. Image sequence subfolders are detected and can be mixed with videos in the same batch.

For tray-selected clips, the system automatically:

1. Detects each clip's state and paint strokes
2. Runs TRACK MASK and then VideoMaMa for painted clips
3. Runs GVM Auto for unpainted RAW clips
4. Chains inference after each alpha generation completes

The entire pipeline is cancellable (Esc) and checkpointable — if interrupted, restarting picks up where each clip left off.

4. Review

Switch between view modes to inspect results:

• COMP — key over checkerboard
• FG — check for green fringing
• MATTE — inspect alpha quality
• PROCESSED — production RGBA

Outputs are written to the project's Output/ subdirectories during inference (configurable — see Custom Output Directory).

---

Keyboard Shortcuts

Viewable and rebindable in-app via Edit > Hotkeys.

Global

Viewer

Pan and zoom are tandem: both viewers always show the same region, and double-click reset applies to both.

Timeline

Paint

---

View Modes

The view mode bar at the top of each viewport switches what the right viewer displays:

---

Inference Controls

Color Space behavior

• The left INPUT viewer always shows CorridorKey's current interpretation of the source. If the input looks wrong there, your future inference results and exports will be based on that wrong interpretation too.
• Changing Color Space before clicking RUN INFERENCE affects how the next live preview and the next export run are generated.
• Changing Color Space after outputs already exist does not rewrite those files on disk. It only updates the viewer and live preview. To keep that new interpretation in saved files, rerun inference.
• CorridorKey auto-detects color space from file type and metadata when possible, but you can override it if the INPUT viewer does not look representative.
• With Live Preview enabled, the first adjustment after a fresh launch may pause briefly while the inference engine loads.

Middle-click any slider to reset it to default.

Output Format

Each output channel can be individually enabled and set to EXR or PNG:

---

Status Colors

---

Frame Scrubber

The scrubber below the dual viewer provides:

• Transport buttons: First frame, step back, play/pause, step forward, last frame
• Playback is CAPPED: Pressing spacebar will play back footage at a hardcoded rate of 3FPS. This is intentional, the files are large.
• Coverage bar: Three color-coded lanes showing which frames have paint strokes (green), alpha hints (white), and inference output (yellow)
• In/Out markers: Press I / O to set a sub-range for processing. When set, the RUN button changes to "RUN SELECTED" and playback loops within the range.

---

Project Structure

Each imported clip creates a project folder:

Projects/
  260301_093000_Woman_Jumps/
    Source/              # Original video
    Frames/              # Extracted EXR DWAB half-float image sequence
    AlphaHint/           # Generated alpha hints
    Output/
      FG/                # Foreground EXR/PNG
      Matte/             # Alpha matte EXR/PNG
      Comp/              # Checkerboard composite PNG
      Processed/         # Production RGBA EXR
    project.json         # Metadata and settings

---

Preferences

Access via Edit > Preferences.

Custom Output Directory

By default, inference output is written to Output/ inside each clip folder. You can redirect output at three levels:

• Global: Preferences > Output > Default output directory
• Per-project: File > Set Project Output Folder
• Per-clip: Right-click a clip > Set Output Directory

Priority: per-clip > per-project > global preference > default.

When using a non-default directory, outputs are organized as <dir>/<ProjectName>/<ClipName>/FG/, Matte/, etc. to prevent collisions between projects. The per-project setting persists to project.json.

---

Running from the Command Line

# GUI mode (default)
python main.py

# CLI mode (original terminal wizard)
python main.py --cli

# Verbose logging
python main.py --log-level DEBUG

Logs are written to logs/backend/YYMMDD_HHMMSS_corridorkey.log.

---

Hardware Requirements

Windows / Linux (NVIDIA CUDA)

VRAM modes

Mode is auto-detected from available VRAM. Override with CORRIDORKEY_OPT_MODE=speed|lowvram|auto.

macOS (Apple Silicon)

Applies to v2.0.0 and source installs. 2.1.5 is a Windows-only patch, so there is no macOS update this release; source installs can still update with 3-update.sh.

CorridorKey inference auto-selects the fastest available backend: the built-in MLX engine (roughly 2x faster than MPS, runs in float16) when its .mlx.safetensors checkpoints are present, otherwise PyTorch MPS. Both green and blue MLX checkpoints download through the setup wizard. Override with CORRIDORKEY_BACKEND=torch|mlx|auto.

Alpha generators (SAM2, GVM, VideoMaMa, MatAnyone2) always run on PyTorch MPS — no MLX ports exist for these models. For best Mac experience, import pre-made alpha mattes from After Effects, DaVinci Resolve, or Nuke.

---

Quality Verification

EZ-CorridorKey's optimizations (Hiera FlashAttention, TF32 tensor cores, torch.compile, tiled refiner) produce output identical to upstream CorridorKey within float32 noise floor — verified across PSNR, SSIM, MS-SSIM, LPIPS, and DeltaE 2000.

---

Security

Verified download sources

The only official sources for EZ-CorridorKey are:

☼ GitHub: github.com/edenaion/EZ-CorridorKey/releases ☼ Gumroad: edenaion.gumroad.com

Any other site hosting EZ-CorridorKey downloads is unverified and potentially malware. Do not download from third-party mirrors, repackaging sites, or file-sharing links. If you see EZ-CorridorKey hosted elsewhere, please report it in GitHub Issues or in the EZSCAPE Discord.

Code signing

☼ Windows: The installer (.exe) is signed via Azure Trusted Signing. Windows SmartScreen shows EZscape Ventures LLC as the verified publisher. ☼ macOS: The .pkg is code-signed and Apple-notarized under Developer ID: Edward Zisk (UX6RDC39ZW). Gatekeeper verifies it on first launch.

Signed updates

Starting with v1.10.0, every GitHub release ships a signed manifest (manifest.json + manifest.json.sig). When the in-app updater downloads a new version, it verifies the Ed25519 signature and SHA-256 hash before applying the update. If either check fails, the update is rejected and the user is warned.

This means even if the GitHub account were compromised, the attacker could not push a malicious update to installed users without also possessing the offline signing key.

The verification code is open source: backend/update_verify.py.

Checksums

Each release includes a SHA256SUMS.txt file listing the SHA-256 hash of every release artifact. Use it to confirm your download is genuine and not corrupted. Put SHA256SUMS.txt in the same folder as the file you downloaded, then follow the steps for your system.

Windows (PowerShell):

# In the download folder (Shift + right-click > "Open PowerShell window here")
Get-FileHash .\EZ-CorridorKey-2.1.0-Windows-x64-Setup.exe -Algorithm SHA256
# Open SHA256SUMS.txt, find the line ending in that filename, compare the hash.
# The two strings must match exactly. If they differ, do not run the file, download it again.

macOS (Terminal):

cd ~/Downloads   # wherever you saved the files
shasum -a 256 -c SHA256SUMS.txt --ignore-missing
# Expect: EZ-CorridorKey-2.0.0-macOS-arm64.dmg: OK
# If it says FAILED, the file is corrupted or tampered with, download it again.

Linux:

cd ~/Downloads
sha256sum -c SHA256SUMS.txt --ignore-missing
# Expect OK next to each file you downloaded.

Git integrity

All commits to main are signed with an Ed25519 SSH key. Branch protection enforces signed commits, pull request reviews, and blocks force pushes and branch deletion.

VirusTotal

Independent scans:

• EZ-CorridorKey.exe (v2.0.0, signed inner executable) — VirusTotal scan
• EZ-CorridorKey.exe (v1.10.0, signed inner executable) — VirusTotal scan

Third-party models: The core CorridorKey checkpoint (CorridorKey.pth) is the only model we can vouch for. Optional models (SAM2, GVM, VideoMaMa, MatAnyone2, BiRefNet) are downloaded from their respective authors' repositories -- use them at your own discretion.

---

Privacy

EZ-CorridorKey sends no telemetry by default. No usage analytics, no tracking, ever.

Two things can send data, both under your control:

☼ Report Issue: when you file a report from the Help menu, the diagnostic summary you see in the dialog can also be sent directly to the developer. A visible checkbox controls it per report. ☼ Crash reporting: an optional toggle in Preferences > Privacy, off by default. When you enable it, crash details are sent automatically.

What a report contains: crash details, GPU/driver info, OS and app version. What it never contains: your media, file names, projects, or personal info. File paths are anonymized before sending.

---

Localization

EZ-CorridorKey supports translation into any language. All UI strings are extracted into standard Qt .ts files that translators can edit with Qt Linguist (free) or any text editor.

How to add your language:

1. Copy ui/translations/corridorkey_en.ts to your language code (e.g. corridorkey_fr.ts for French)
2. Open the new file in Qt Linguist and fill in translations
3. Compile it: pyside6-lrelease ui/translations/corridorkey_fr.ts
4. Submit a pull request with both the .ts and .qm files

Full instructions with examples are in ui/translations/TRANSLATING.md.

Current languages: English plus German, Spanish, French, Hindi, Indonesian, Italian, Japanese, Korean, Polish, Portuguese (Brazil), Russian, Turkish, Ukrainian, Vietnamese, Chinese (Simplified), and Chinese (Traditional, Taiwan). Pick yours in Edit > Preferences. Want to see your language here or improve upon a translation? PRs welcome.

---

Contributing & Support

EZ-CorridorKey is a labor of love — built and maintained by one man from Brooklyn for the VFX community. If this tool saves you time on a project, consider paying it forward:

• Star this repo if you find it useful -- it helps others discover the project
• Purchase a plugin -- I pour my heart into EZSCAPE plugins
• Report bugs via GitHub Issues
• Contribute code -- see CONTRIBUTING.md for guidelines
• Security issues -- see SECURITY.md for responsible disclosure

Need GPU compute for inference? RunPod offers on-demand cloud GPUs — great for batch processing large shoots without tying up your local machine. Using my referral link will enable me to build more tools for all!

Community

---

Licensing & Attribution

This project wraps Niko Pueringer's CorridorKey, licensed under CC BY-NC-SA 4.0.

GUI/SFX/Workflow/QA/Maintenance by Ed Zisk.

Contributors

• Logo by Sara Ann Stewart
• Hiera optimization by Jhe Kim
• Tiling optimization by MarcelLieb
• MLX Apple Silicon backend by Cristopher Yates (corridorkey-mlx)
• FX graph cache from 99oblivius (CorridorKey-Engine)
• BiRefNet integration adapted from Warwlock's upstream PR
• Docker / noVNC browser mode by DCRepublic

Optional modules & licenses

• SAM 2.1 (facebookresearch/sam2) — Apache 2.0
• GVM (aim-uofa/GVM) — CC BY-NC-SA 4.0
• VideoMaMa (cvlab-kaist/VideoMaMa) — CC BY-NC 4.0, model weights under Stability AI Community License
• MatAnyone2 (pq-yang/MatAnyone2) — Apache 2.0
• BiRefNet (ZhengPeng7/BiRefNet) — MIT

If you use or build on this project, please star this repo and credit the contributors.