Griptape Nodes CorridorKey Library

A Griptape Nodes library for neural-network green/blue screen keying using CorridorKey.

Overview

This library wraps CorridorKey, a transformer-based chroma keying tool built by Niko Pueringer / Corridor Digital for professional VFX pipelines. Given an RGB frame and an optional coarse alpha hint, CorridorKey produces a clean straight (unpremultiplied) alpha matte, a despilled foreground with the screen color removed, a linear premultiplied RGBA matte for compositing, and an optional checkerboard composite preview.

The library exposes two nodes: CorridorKey Inference, which handles the full pipeline on a single image frame (when no alpha hint is supplied it runs BiRefNet internally to generate one, then runs the CorridorKey GreenFormer (Hiera + refiner) keying network with the green-screen or blue-screen checkpoint), and CorridorKey Video Inference, which runs the same per-frame pipeline natively across a video clip or image sequence, with BiRefNet, GVM, or VideoMaMa as the source of the per-frame alpha hint. All weights auto-download from HuggingFace on first use.

Requirements

• GPU: CUDA (NVIDIA), Apple Silicon MPS, or AMD ROCm (Linux). CPU fallback is supported but slow. Minimum 6-8 GB VRAM is recommended for 2048x2048 inference. The video node's gvm and videomama hint sources are only tested on CUDA GPUs with ~80 GB VRAM on a single GPU (no multi-GPU VRAM pooling); birefnet (the default hint source) works on any GPU including Apple Silicon.
• Griptape Nodes Engine: Version 0.89.0 or later

Nodes

CorridorKey Inference

Runs the full CorridorKey neural keying pipeline on a single image frame. If alpha_hint is left empty, BiRefNet is used internally to generate a coarse hint from the source image.

Parameters:

CorridorKey Video Inference

Runs the full CorridorKey neural keying pipeline across every frame of a video clip or image sequence. The per-frame alpha hint is generated by one of three sources, selected via hint_source:

• birefnet (default): BiRefNet runs independently on each frame. Works on any GPU.
• gvm: the GVM video model generates temporally-consistent hints across the whole clip in one pass. Only tested on CUDA GPUs with ~80 GB VRAM on a single GPU (the vendored GVMProcessor has no multi-GPU/offload support); on other devices the node warns rather than blocking.
• videomama: also generates temporally-consistent hints, guided by a rough per-frame mask supplied via mask_hint. Same CUDA/VRAM caveat as GVM.

Only the parameters relevant to the current hint_source and output_format selection are shown; the rest are hidden automatically.

Parameters:

Available Models

The following models are available from HuggingFace:

Models are downloaded automatically on first use and cached for subsequent runs. The CorridorKey checkpoints land under <site-packages>/CorridorKeyModule/checkpoints/; the BiRefNet weights land under <site-packages>/BiRefNetModule/checkpoints/<repo_name>/; GVM and VideoMaMa weights are resolved from the standard HuggingFace hub cache (~/.cache/huggingface/hub/ by default).

Installation

Prerequisites

• Griptape Nodes installed and running
• A CUDA-capable NVIDIA GPU, an Apple Silicon Mac, or an AMD ROCm-capable Linux machine

Dependencies

pip_dependencies in the library JSON is the edit-time set, installed wherever the library is registered, and holds only what importing and instantiating a node needs. pip_dependencies_exec is the ML stack, installed into .venv-exec, which only the worker process that runs a node ever reads. On top of that, the advanced library installs the pinned CorridorKey submodule itself with --no-deps into the same .venv-exec, because BiRefNetModule is absent from the wheel's package list and is reached through sys.path rather than installed.

Install the Library

1. Clone the repository to your Griptape Nodes workspace directory:

   cd `gtn config show workspace_directory`
   git clone --recurse-submodules https://github.com/griptape-ai/griptape-nodes-library-corridorkey.git
   

2. Add the library in the Griptape Nodes Editor:

   • Open the Settings menu and navigate to the Libraries settings
   • Click on + Add Library at the bottom of the settings panel
   • Enter the path to the library JSON file:

     <workspace_directory>/griptape-nodes-library-corridorkey/griptape_nodes_library_corridorkey/griptape-nodes-library.json
     

   • You can check your workspace directory with gtn config show workspace_directory
   • Close the Settings Panel
   • Click on Refresh Libraries

3. Verify installation by checking that the CorridorKey Inference and CorridorKey Video Inference nodes appear in the node palette under the "CorridorKey" category.

Usage

CorridorKey Inference

1. Add a CorridorKey Inference node to your workflow.
2. Connect your source image to image. The node accepts any resolution; the source is resized internally to img_size for inference and upsampled back to its original resolution.
3. Choose the keying checkpoint via model: nikopueringer/CorridorKey_v1.0 for green screens, nikopueringer/CorridorKeyBlue_1.0 for blue screens.
4. (Optional) Connect a coarse alpha_hint mask if you have one. If you leave it empty, the node will run BiRefNet on image to generate the hint automatically; pick the BiRefNet variant via birefnet_model (matting for soft edges, general for hard edges).
5. (Optional) Tune despill_strength, auto_despeckle, despeckle_size, and refiner_scale to control the despill pass, matte cleanup, and refiner head.
6. Connect any of alpha, foreground, composite, or rgba to your downstream nodes:
   • alpha is the cleaned matte for use in compositing
   • foreground is the despilled sRGB plate
   • rgba is an 8-bit linear premultiplied RGBA matte ready to drop into a compositor
   • composite is a quick checkerboard preview for sanity-checking the matte

The first run will download the selected CorridorKey checkpoint (~300 MB) and, if used, the BiRefNet weights (varies by variant). On Linux/Windows with a C compiler installed, CorridorKey also performs a one-time torch.compile pass that adds 30 s - 20 min to the first call; subsequent calls reuse the autotune cache under ~/.cache/corridorkey/inductor/.

CorridorKey Video Inference

1. Add a CorridorKey Video Inference node to your workflow.
2. Connect your source clip to video: a video file, a Sequence, a directory of frames, a sequence pattern (frame.####.exr), or a list of frame paths.
3. Choose the keying checkpoint via model, same as the image node.
4. Choose hint_source:
   • birefnet (default) — pick the variant via birefnet_model, same as the image node. Works on any GPU.
   • gvm — pick the checkpoint via gvm_model; tune gvm_num_frames_per_batch, gvm_num_overlap_frames, and gvm_denoise_steps if needed. Requires a CUDA GPU with ~80 GB VRAM.
   • videomama — connect a rough per-frame foreground mask to mask_hint, and pick the checkpoints via videomama_unet_model/videomama_base_model. Requires a CUDA GPU with ~80 GB VRAM.
5. Choose output_format: video for mp4 outputs (alpha/foreground/composite), or exr_sequence for a float32 EXR sequence per output (alpha_sequence/foreground_sequence/composite_sequence) if you need a genuine alpha channel.
6. (Optional) Tune img_size, batch_size, despill_strength, auto_despeckle, despeckle_size, and refiner_scale as with the image node. Use max_frames to cap processing while previewing a long clip, and output_frame_rate to set the frame rate for outputs when the source is an image sequence.
7. Connect the relevant outputs (video or sequence, depending on output_format) to your downstream nodes.

The first run of gvm or videomama will download their (large) checkpoints through Griptape Nodes' Model Manager, with visible progress in the UI.

Runtime Patches

CorridorKey vendors a third-party engine (CorridorKeyModule) and depends on timm for its Hiera backbone. On load, corridorkey_common.py applies two runtime patches (in-process only, idempotent, no installed files are modified) to work around upstream bugs that otherwise only surface on Apple Silicon (MPS):

• Hiera .view() → .reshape() (_patch_timm_hiera_view_bug): timm's hiera_base_plus_224 backbone's MaskUnitAttention.forward() calls .view() on a tensor produced by a preceding .permute(), which raises "view size is not compatible with input tensor's size and stride" on MPS (the stride layout that triggers it doesn't come up on CPU/CUDA). Patches the forward pass to use .reshape() instead (a drop-in replacement that only copies when a view isn't possible), and makes q/k/v contiguous before scaled_dot_product_attention, which does its own internal .view() on its inputs.
• connected_components MPS race (_patch_connected_components_mps_race): the despeckle pass's connected_components() (in the vendored CorridorKeyModule.core.color_utils) writes and reads its flood-fill buffer via boolean advanced indexing (comp[mask == 1] = pooled[mask == 1]). On MPS, the scatter and gather sides each trigger their own async nonzero-count kernel invocation, and the two occasionally disagree on the mask's true-count even given the same mask tensor — an indexing-kernel race, not a mask-recomputation issue, so hoisting the mask evaluation out of the loop doesn't fix it. Patched to use torch.where (an elementwise select with no variable-length indexing step) instead, which removes the race entirely (the race's documented symptom is a RuntimeError: shape mismatch crash inside connected_components, not silent data corruption).

Also investigated, separate from the two patches above: on some Apple Silicon Macs, the very first CorridorKey Inference/CorridorKey Video Inference call in a freshly-started engine process was once observed to return fully-NaN alpha/foreground/rgba (visibly all-black output), regardless of auto_despeckle, with every subsequent call in the same process reliable. Follow-up testing -- a synthetic repro against the real checkpoint at several resolutions, plus a fresh end-to-end run in the desktop app at the production default img_size=2048 on a newly-launched engine -- could not reproduce it, and ruled out the originally-suspected mechanism: production never actually runs the model under torch.autocast on fp32 weights (CorridorKeyEngine disables mixed precision whenever model_precision=torch.float16, which it always is in practice, so the forward pass runs native fp16 end-to-end). Current best guess is a one-off cold macOS/Metal shader-compilation cache artifact on that machine rather than a reliably-reproducing bug -- if you ever hit a fully black result on a first run, re-run the node; it has not recurred in testing since.

Troubleshooting

Library Not Loading

• Ensure the git submodule is initialized. If you cloned without --recurse-submodules, run:

  git submodule update --init --recursive
  

GPU Not Available

• Verify your GPU drivers are up to date
• For NVIDIA GPUs, ensure CUDA is properly installed and nvidia-smi reports your GPU correctly
• For Apple Silicon, ensure you're running on macOS 12.3 or later
• For AMD ROCm, ensure ROCm 6+ is installed and /opt/rocm exists (Linux only)

Out of Memory Errors

• Reduce img_size (e.g., from 2048 to 1024). The 2048 default matches the trained resolution; lower values run faster and use less VRAM at the cost of fine-edge accuracy.
• Reduce batch_size on CorridorKey Video Inference to lower peak VRAM usage for the keying pass itself.
• Close other GPU-intensive applications before running inference.
• gvm and videomama hint sources need ~80 GB VRAM on a single CUDA GPU; if that's not available, use hint_source=birefnet instead, which works on any GPU with the same VRAM budget as the image node.

Slow First Run

• On Linux and Windows, CorridorKey runs torch.compile on the first process_frame call to autotune kernels for the active GPU. This adds 30 s - 20 min depending on the backend. The autotune cache is persisted under ~/.cache/corridorkey/inductor/ and reused on subsequent runs.
• To skip compilation entirely (slower steady-state, but no compile delay), set the environment variable CORRIDORKEY_SKIP_COMPILE=1 before launching the engine.

Additional Resources

• CorridorKey GitHub
• Griptape Nodes Documentation
• Griptape Discord

License

This library is distributed under the Corridor Key Licence (Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International, with the Corridor Key Additional Terms and Conditions). This matches the license of the upstream CorridorKey project, as required by the share-alike clause of that licence. See the LICENSE file in this repository for the full text.

The "CorridorKey" name and any associated trademarks remain the property of Corridor Digital.