license: other
license_name: corridor-key-licence-2.0
license_link: https://huggingface.co/cdelta/CorridorKey-v2-MLX-8bit/blob/main/LICENSE
base_model: nikopueringer/CorridorKey2.0
base_model_relation: quantized
library_name: mlx
pipeline_tag: image-segmentation
tags:
- mlx
- apple-silicon
- video-matting
- green-screen
- blue-screen
- chroma-key
- vfx
- fp32
- fp16
- quantized
This repository contains the Q8 / 8-bit profiles of CorridorKey 2.0 for Apple Silicon. It uses group-64 affine quantization for 445 linear matrices, with FP16 residual weights and activations. No fine-tuning or retraining was performed.
All variants 路 FP32 路 FP16 路 Q8 / 8-bit 路 Combined bundle
The original model was designed and trained by Zachary Harris in direct collaboration with Niko Pueringer and Corridor Digital. Credit for the model, architecture, and training belongs to them. Peter Teravskis maintains this community MLX implementation and its Apple Silicon evaluation work. For the official supported plugins, visit corridorkey.com.
Actual FP32 results from the companion CLI, shown with a central split between the original screen and a checkerboard transparency preview. Fine fur, a blurred paw, flyaway hair, and translucent gauze remain visible. The plates are synthetic demonstration inputs, without ground-truth mattes.
| Example | Original input | Transparent 16-bit PNG |
|---|---|---|
| Squirrel 路 green screen | Input | RGBA cutout |
| Redhead 路 blue screen | Input | RGBA cutout |
Use with the companion runtime
Install the Apache 2.0 source and CLI:
git clone https://github.com/peterteravskis/corridorkey-v2-mlx.git
cd corridorkey-v2-mlx
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install '.[download]'
hf download cdelta/CorridorKey-v2-MLX-8bit --local-dir /path/to/CorridorKey-v2-MLX
corridorkey-mlx --precision q8 --compile --image-sequence \
--model-root /path/to/CorridorKey-v2-MLX \
--input /path/to/plate.png --output-dir outputs/plate \
--outputs alpha fg raw_fg checker cutout
Use an Apple Silicon Mac with Python 3.12. MLX 0.32.4 and PyTorch 2.9.1 are
pinned by the source package. PyTorch is used for CPU preparation; the neural
networks and output renderer execute on MLX. FFmpeg is required for video
export. The profiles are custom MLX inference graphs, not an MLX-LM or
Transformers checkpoint; use the companion runtime rather than AutoModel.
Profile contents
| Profile | Components |
|---|---|
q8/1024x1536-t1, q8/768x1280-t1 |
RVM, C-RADIO + MoGe foundations, stage 1, stage 2 |
q8/1024x1536-t4, q8/768x1280-t4 |
Four-frame stage 1 and an additional 768脳1280 stage-two batch profile |
q8/768x1280-t2 |
Two-frame stage-two batch profile for API/research use |
Each component contains graph.json and weights.safetensors. The single-frame
profile also supplies normalization statistics. Profile names use height 脳
width. Inputs are padded to a multiple of 128, then cropped back to their
native dimensions; the padded shape must match a profile.
For temporal clips of four or more frames, use Hann window/stride 4/2 and stage-two batch one. Two- or three-frame clips require their own stage-one profiles or explicit 1/1 processing without temporal windows. Larger resolutions and other stage-one window lengths are not included in this bundle. The CLI guide documents input, output, hint, and scratch-storage behavior.
Use this repository with --precision q8. Keep its folder layout intact; pass the downloaded repository root to --model-root, not its q8/ subfolder.
For native 1280 脳 720 footage, add --height 768 --width 1280. Download another precision from the Collection, or use the combined bundle for all three.
Precision tradeoffs
FP16 retains sensitive reductions and normalization in FP32. Q8 uses native MLX group-64 affine quantization on 445 linear matrices, covering 74.47% of floating-point parameters, with FP16 residual weights and activations. Convolutions and activations are not 8-bit. Output rendering stays FP32.
FP16 and Q8 reduce memory use but change numerical results. The CLI measurements below report current time and memory. The retained precision study compares against FP32 and records larger localized Q8 transparency differences, including a maximum 6.885-percentage-point alpha difference on the blue-glass fixture. Numerical agreement and visible quality are separate questions.
Verified parent weights
Direct byte comparisons cover the FP32 conversion inputs and both distributed FP32 single-frame profiles. FP16 rounding and Q8 quantization intentionally change tensor values; their file hashes and source conversion hashes are retained separately in the profiles and model manifest.
The official public checkpoint was checked at revision
cf44a8db3f024bb49fd59daa408848ccf05f7477 before adding the base_model link.
| Check | Result |
|---|---|
| Learned tensors | 738 / 738 equal in direct byte comparisons and SHA-256 |
| Foundation normalization tensors | 6 / 6 equal in direct byte comparisons and SHA-256 |
| Tensor names, shapes, and dtypes | Exact match |
| Distributed FP32 stage-one/stage-two tensors | 1,476 / 1,476 direct byte comparisons passed across both resolutions |
| Model configuration | Match after JSON sequence normalization |
| Missing, extra, or changed learned tensors | None |
The conversion inputs match the official release's tensor payloads byte for byte. Exported MLX files have different container hashes because graph export names and partitions tensors by component. The model manifest checks the exact bytes of the distributed MLX files separately.
- Current official checkpoint direct-byte verification
- Distributed FP32 tensor direct-byte verification
- Original verification summary
- Every tensor's paired SHA-256 hashes
- Packaged graph/weight file manifest
Official safetensors SHA-256:
c43596de98cc8866d577c8a9f9ea239acdf3f7a130ff24e25db4375a50590436.
Measurements
The comparison below covers all three companion precision releases. This repository contains Q8 / 8-bit profiles only.
Fresh measurements of this packaged CLI on an Apple M4 Pro with 48 GiB, using the distributed FP32, FP16, and Q8 profiles. Each condition runs one complete warm-up followed by three measured workflows. Timings include input decoding, neural inference, rendering, four completed 16-bit PNG outputs per frame, and scratch cleanup. Initial model loading and compilation are reported separately.
The table below measures 32 moving frames at native 1280 脳 720, padded to 1280 脳 768. Reference mode disables the custom graph rewrites and kernels; enabled mode uses the release defaults. Both use identical weights, precision, Hann windows/stride 4/2, and stage-two batch one.
| Precision | Reference | Enabled | Less time | Enabled physical memory |
|---|---|---|---|---|
| FP32 | 50.465 s | 37.657 s | 25.4% | 7.05 GiB |
| FP16 | 42.975 s | 37.123 s | 13.6% | 4.11 GiB |
| Q8 | 46.088 s | 39.397 s | 14.5% | 3.28 GiB |
The speed optimizations ship enabled. FP32 uses specialized reconstruction, reflection padding/layout, dense projection pairing, and paired 7脳7 channel convolution. FP16/Q8 use the accepted half-precision paired-convolution path. Half-precision projection pairing remains disabled.
All four stills and all 32 moving frames were compared with optimizations enabled and disabled at each precision. Every comparison passed the recorded numerical limits. FP16 and Q8 outputs match their own reference paths exactly. FP32 differs by at most 1/65535 in alpha and 2/65535 in the checker output. These checks do not establish FP16/Q8 equality with FP32 or accuracy against ground-truth mattes.
Methodology and raw samples 路 Kernel implementation and isolated measurements 路 Release validation.
The retained MPS comparison and isolated operator studies use earlier measurement setups. Their ratios are not combined with these CLI results. These measurements describe the recorded Mac and fixtures, not a minimum-RAM requirement or a guarantee for other footage.
Intended use and limitations
Use for green-/blue-screen foreground separation, matte review, and compositing. Fine hair, gauze, transparent objects, blur, and subject identity can still need artist review or hints. The port does not improve the original model's learned semantic decisions. It is a shape-specialized inference release; training and arbitrary-shape execution are outside its scope.
The basic CLI accepts display-referred PNG/JPEG/video and produces SDR PNG/video exports. It does not expose the original model's HDR EXR workflow. Audio is not copied. Validation is specific to the recorded hardware and fixtures; other Macs and longer clips need their own evaluation. FP16/Q8 do not meet the strict FP32 agreement criteria and remain explicit opt-in choices.
Upstream reports that the original training data was generated in-house using 3D rendering. No additional training dataset was used for this conversion. No broad demographic or production-shot generalization evaluation is claimed. See the original model card for the publisher's training and intended-use information.
License and acknowledgements
CorridorKey-derived weights and graphs retain the unchanged Corridor Key Licence 2.0, including its additional terms. The Apache 2.0 source license applies to the separate runtime code and grants no additional rights to these model assets.
Organizations with over US $20 million in annual gross revenue require a CorridorKey plugin seat per user. See the original license for details.
The foundation components retain their own licenses:
| Component | Publisher | License |
|---|---|---|
| C-RADIOv4-SO400M | NVIDIA | NVIDIA Open Model License |
| MoGe-2 ViT-B | Microsoft / Ruicheng | MIT |
| RVM small | Google DeepMind | CC BY 4.0 weights |
Licensed by NVIDIA Corporation under the NVIDIA Open Model License. The foundation profiles are converted representations, not unmodified copies of their original file containers. THIRD_PARTY_NOTICES.md identifies those changes and the bundled license texts. Nothing here implies endorsement by the original authors or their organizations.