This document defines the current product scope, support philosophy, and runtime architecture of CorridorKey Runtime. It answers what the product is, why it exists, and what it explicitly includes and excludes.
See also: Support Matrix - explicit support status by platform and hardware | ARCHITECTURE.md - source structure and dependency rules | GUIDELINES.md - code standards and build rules
CorridorKey Runtime is a native C++ runtime for the CorridorKey neural green screen model. It exists to eliminate the Python dependency from model execution and to deliver a distributable, hardware-accelerated inference engine for professional video production workflows.
The product currently provides three released surfaces:
- An OFX plugin for DaVinci Resolve and Foundry Nuke on Windows and macOS, backed by an out-of-process runtime service. The plugin is host-agnostic at the OFX 1.4 contract level; per-host workarounds (Resolve and Nuke 17 today) live in dedicated branches that never regress the path the other host depends on.
- A CLI (
corridorkey) for direct command-line and pipeline use. The Windows suite installs the CLI/runtime core as the fixed base and registers it on the systemPATH. The CLI is also available in the portable runtime bundle, and standalone OFX support packages may carry a colocated copy for host-plugin support. - A GUI (Tauri-based desktop app) for users who prefer a graphical workflow over the CLI. The GUI is distributed through the suite installer or portable Runtime bundle and resolves the shared or side-by-side packaged runtime payload; it is not bundled into the OFX installer.
Adobe After Effects and Premiere plugins are an accepted implementation track, but they are not a supported release surface until the host plugin, package, and validation tasks pass. All surfaces consume the same underlying library. Logic is never duplicated between them.
- Not a retraining framework or new model architecture.
- Not a generic multi-backend AI serving system.
- Not a broadly supported cross-platform engine; platform and hardware support is curated and explicitly designated. See Support Matrix.
- Not a replacement for the original CorridorKey project; it is a focused native runtime and integration layer for deployment.
- Local operators who want native execution without Python or virtual environments.
- Color graders and compositors using DaVinci Resolve or Foundry Nuke on officially supported hardware.
- Adobe video users using After Effects or Premiere once the Adobe host plugin track is packaged and validated.
- Pipeline integrators who need a stable CLI or library surface for automated workflows.
- Desktop users who prefer a graphical interface to the CLI for keying and diagnostics tasks.
Hardware and platform support is classified by one of four explicit designations:
| Designation | Meaning |
|---|---|
| Officially supported | Validated on this hardware/platform. Releases are tested against it. Bug reports are accepted and prioritized. |
| Best-effort | Known to work in most cases, but not systematically validated. Known limitations exist. Bug reports are accepted but not guaranteed to be resolved. |
| Experimental | Partially integrated. Known errors exist in practice. Not recommended for production use. Bug reports are accepted for tracking purposes only. |
| Unsupported | Not integrated or known to be broken. No bug reports accepted. |
Vague claims such as "works on most hardware" or "compatible with" are not used. Every hardware path and host version has an explicit designation.
Support is defined by packaged and validated product tracks. A backend present in the core runtime for probing, diagnostics, or future integration does not become a support claim unless it is distributed and validated as a product track.
The complete support table is in Support Matrix.
- Interface layer: CLI, OFX plugin, Adobe plugins, and Tauri GUI
- Application layer: job orchestration, host-plugin runtime service, diagnostics
- Core layer: inference session management, device detection, frame I/O, post-process, and session policies
The runtime contains multiple backend hooks, but product support is defined by curated execution tracks.
The current official product tracks are:
- Apple Silicon via MLX model pack and bridge exports
- Windows RTX via ONNX Runtime TensorRT RTX EP for the green model and a dynamic TorchScript path for the blue model on NVIDIA RTX 30 series and newer
The current experimental product tracks are:
- Windows DirectML
- Linux RTX via ONNX Runtime CUDA EP on NVIDIA RTX 30 series and newer
Additional provider hooks may exist in the core runtime for diagnostics, bring-up, or future tracks. Those hooks are not support claims by themselves.
Interactive host plugins run the inference backend in a separate process managed by the App-layer runtime service. The plugin is a thin IPC client; it does not load ONNX sessions or GPU backends directly.
This design isolates backend failures, TensorRT RTX compilation errors, and VRAM exhaustion from the host process (DaVinci Resolve, Foundry Nuke, After Effects, or Premiere). The session broker in the service layer pools initialized sessions across multiple host plugin instances to avoid redundant GPU warmups.
Frame data moves between plugin and service over shared memory. The IPC protocol is versioned to ensure the plugin and service remain compatible across incremental updates.
Each product track ships curated model artifacts optimized for that track. The runtime contract - API, parameter schema, and output format - is identical across tracks. The artifact format and execution provider may differ.
Quality policy is product-defined, not a vendor support claim. The runtime uses conservative safe quality ceilings by backend and available memory to pick a direct artifact, downgrade automatically, or force an explicit error when the requested quality is outside the current validated tier.
CorridorKey ships two model variants distinguished by training plate color:
- Green (
corridorkey_fp16_<res>.onnx): the canonical variant. Officially packaged across the full validated resolution ladder for every official product track. Served via the canonical ONNX backend on every host. - Blue (
corridorkey_dynamic_blue_fp16.ts): the dedicated Windows RTX variant for blue screen plates. Blue is distributed as one dynamic TorchScript artifact instead of a per-resolution ladder. The runtime uses the requested quality resolution at execution time and keeps the green ONNX ladder unchanged.
The runtime selects the variant by the user-provided screen color parameter. When the blue pack is not installed or cannot initialize, the runtime applies the documented green-domain canonicalization fallback rather than substituting another blue resolution.
Model artifacts are distributed as selectable packs rather than a single
mandatory bundle. Each pack is identified by product track and screen color
variant. Packs are hosted on Hugging Face and addressable through the
download_url field on every catalog entry.
The installer or first-run flow offers the user a pack selection: runtime/CLI
core only, green only, blue only, or both. Selecting fewer packs reduces
install footprint without disabling runtime features beyond the unselected
variants. The
corridorkey doctor command reports which packs are present, which are
missing, and the canonical Hugging Face source for any missing pack.
Models are data, not executable code. Pack downloads after install do not invalidate macOS notarization or Windows Authenticode signatures of the plugin, CLI, or GUI binaries.
Fallback is surface-dependent.
- CLI and tolerant automation workflows may fall back to ONNX CPU execution.
- The OFX plugin favors explicit failure over silent CPU fallback on unsupported interactive GPU requests.
Fallback or failure is logged explicitly. The corridorkey doctor command
reports the active execution path and any fallback conditions before
processing begins.
- Native inference execution:
- MLX for the official Apple Silicon track
- TensorRT RTX EP for the official Windows RTX track on NVIDIA RTX 30 series and newer
- DirectML for the experimental Windows DirectML track
- CUDA EP via ONNX Runtime for the experimental Linux RTX track
- ONNX CPU fallback for tolerant workflows
- CLI surface (
corridorkey) with stable JSON and NDJSON output contracts - OFX plugin for DaVinci Resolve 20 and Foundry Nuke 17 on Apple Silicon, Windows, and Linux
- Adobe After Effects SDK effect plugin implementation for After Effects and Premiere validation
- Tauri desktop GUI distributed as a suite component or portable desktop package that resolves the packaged or shared runtime payload
- Green and blue screen color model variants, distributed as independent selectable packs
- Alpha hint ingestion and rough-matte fallback generation
- host plugin runtime/status reporting for guide source, safe quality ceiling, and the actual runtime path used for the last render
- Platform-specific model artifact packaging
doctor,benchmark, andprocesscommands with structured diagnostics
The four officially supported user surfaces are DaVinci Resolve OFX, Foundry
Nuke OFX, the corridorkey CLI, and the Tauri desktop GUI. The OFX path is
shared between Resolve and Nuke at the OFX 1.4 contract level. Per-host
adjustments live in dedicated branches that never regress the path the other
host depends on.
These four surfaces form the currently supported boundary for the product line. Adobe After Effects and Premiere are accepted implementation targets, but they stay outside the supported release boundary until their host validation and packaging tasks pass.
- Training, fine-tuning, or exporting new model architectures
- A generic plugin framework or SDK for third-party extension
- Support for editing hosts beyond DaVinci Resolve, Foundry Nuke, After Effects, and Premiere as part of the current product line
- Browser, cloud, or server-side deployment
- Real-time preview at full resolution without hardware acceleration
All commands produce human-readable output by default. Append --json to
receive NDJSON event streams. The NDJSON schema is stable across patch
releases and is the integration surface for pipeline automation.
corridorkey doctor reports:
- detected hardware and selected backend
- fallback conditions, if any
- model artifact presence and validity
- platform-specific constraints relevant to the current runtime
The CLI uses deterministic exit codes. Zero indicates success. Non-zero codes
correspond to specific failure categories documented in the --help output.
- No Python in any execution path
- No heap allocation in per-frame or per-pixel loops
- All image buffers are 64-byte aligned for SIMD compatibility
- Zero-copy frame passing via
std::spanbetween processing stages - TensorRT RTX first-run compilation is expected and takes 10-30 seconds for a new GPU and model combination