README.md

---
license: other
license_name: corridor-key-licence-2.0
license_link: https://huggingface.co/cdelta/CorridorKey-v2-MLX/blob/main/LICENSE
base_model: nikopueringer/CorridorKey2.0
library_name: mlx
pipeline_tag: image-segmentation
tags:
  - mlx
  - apple-silicon
  - video-matting
  - green-screen
  - blue-screen
  - chroma-key
  - vfx
  - fp32
  - fp16
  - quantized
---

<div align="center">

# CorridorKey v2 · MLX

### FP32 · FP16 · Q8 matting profiles for Apple Silicon

[Source & CLI](https://github.com/peterteravskis/corridorkey-v2-mlx) · [Original model](https://huggingface.co/nikopueringer/CorridorKey2.0) · [Original project](https://github.com/nikopueringer/CorridorKey2.0) · [License](https://huggingface.co/cdelta/CorridorKey-v2-MLX/blob/main/LICENSE)

</div>

This repository packages **CorridorKey 2.0** as shape-specialized MLX graphs
and safetensors for Apple Silicon. It is a format/runtime conversion of
[`nikopueringer/CorridorKey2.0`](https://huggingface.co/nikopueringer/CorridorKey2.0).
FP32 preserves the learned weights; FP16 and Q8 are optional precision variants.
No variant is fine-tuned or retrained.

**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](https://corridorkey.com).

![Squirrel on green screen and redhead on blue screen: a centre stripe separates each input from its background-removed result](assets/screen-to-foreground.png)

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](assets/examples/squirrel-input.png) | [RGBA cutout](assets/examples/squirrel-cutout.png) |
| Redhead · blue screen | [Input](assets/examples/redhead-input.png) | [RGBA cutout](assets/examples/redhead-cutout.png) |

## Precision downloads

| Download | CLI selection |
| :--- | :--- |
| [FP32](https://huggingface.co/cdelta/CorridorKey-v2-MLX-fp32) | `--precision fp32` |
| [FP16](https://huggingface.co/cdelta/CorridorKey-v2-MLX-fp16) | `--precision fp16` |
| [Q8 / 8-bit](https://huggingface.co/cdelta/CorridorKey-v2-MLX-8bit) | `--precision q8` |

[Browse the Collection](https://huggingface.co/collections/cdelta/corridorkey-v2-mlx-6ad84231314d2593c3799e34). This repository remains the combined bundle with all three precisions. The separate downloads retain the same folder layout and CLI options.

## Use with the companion runtime

Install the [Apache 2.0 source and CLI](https://github.com/peterteravskis/corridorkey-v2-mlx):

```bash
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 --local-dir /path/to/CorridorKey-v2-MLX

corridorkey-mlx --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 | Intended use |
| :--- | :--- | :--- |
| `1024x1536-t1` | RVM, C-RADIO + MoGe foundations, stage 1, stage 2 | 1536 × 1024 stills and one-frame component execution |
| `768x1280-t1`, `768x1280-t4` | Complete FP32 t1, stage-one t4 | Native 1280 × 720 padded to 1280 × 768 |
| `1024x1536-t4` | Stage 1 | Four-frame temporal windows at the same padded dimensions |
| `fp16/1024x1536-t1`, `fp16/1024x1536-t4` | Mixed FP16 versions | Lower-memory still and temporal inference |
| `q8/1024x1536-t1`, `q8/1024x1536-t4` | Packed Q8 / FP16 versions | Further memory savings |
| `fp16/768x1280-*`, `q8/768x1280-*` | Complete t1, stage-one t4, stage-two t2/t4 | Native 1280×720 padded to 1280×768; extra refinement batch profiles |

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](https://github.com/peterteravskis/corridorkey-v2-mlx/blob/main/docs/CLI.md)
documents input, output, hint, and scratch-storage behavior.

Select a variant using the same model root:

```bash
corridorkey-mlx --precision q8 --compile --image-sequence \
  --model-root /path/to/CorridorKey-v2-MLX \
  --input /path/to/shot.mp4 --output-dir outputs/shot-q8 \
  --height 768 --width 1280
```

Use `--precision fp16` for mixed FP16 or omit the option for FP32. Downloading
the whole repository includes every variant; use `hf download --include` to
select only the needed precision folder and license files.

## 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](https://github.com/peterteravskis/corridorkey-v2-mlx/blob/main/docs/PRECISION.md)
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](current-hf-bytecheck.json)
- [Distributed FP32 tensor direct-byte verification](fp32-export-bytecheck.json)
- [Original verification summary](weight-verification.json)
- [Every tensor's paired SHA-256 hashes](weight-tensor-hashes.json)
- [Packaged graph/weight file manifest](model-manifest.json)

Official safetensors SHA-256:
`c43596de98cc8866d577c8a9f9ea239acdf3f7a130ff24e25db4375a50590436`.

## Measurements

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.

![CLI workflow time and physical memory](assets/cli-workflow.png)

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 |

![CLI kernel optimization comparison with all timing samples](assets/cli-kernel-gains.png)

**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.

![CLI time by processing stage](assets/cli-stage-times.png)

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.

![Saved output agreement for every fixture and precision](assets/cli-output-agreement.png)

![Initial model load and first CLI workflow versus warmed execution](assets/cli-first-use.png)

[Methodology and raw samples](https://github.com/peterteravskis/corridorkey-v2-mlx/blob/main/docs/BENCHMARKS.md) ·
[Kernel implementation and isolated measurements](https://github.com/peterteravskis/corridorkey-v2-mlx/blob/main/docs/OPTIMIZATIONS.md) ·
[Release validation](https://github.com/peterteravskis/corridorkey-v2-mlx/blob/main/docs/VALIDATION.md).

The retained [MPS comparison](https://github.com/peterteravskis/corridorkey-v2-mlx/blob/main/docs/HISTORICAL_BENCHMARKS.md) 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](https://huggingface.co/nikopueringer/CorridorKey2.0)
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](https://huggingface.co/cdelta/CorridorKey-v2-MLX/blob/main/LICENSE), including its additional terms.
The [Apache 2.0 source license](https://github.com/peterteravskis/corridorkey-v2-mlx/blob/main/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](https://github.com/nikopueringer/CorridorKey2.0/blob/master/LICENSE)
for details.

The foundation components retain their own licenses:

| Component | Publisher | License |
| :--- | :--- | :--- |
| [C-RADIOv4-SO400M](https://huggingface.co/nvidia/C-RADIOv4-SO400M) | NVIDIA | NVIDIA Open Model License |
| [MoGe-2 ViT-B](https://huggingface.co/Ruicheng/moge-2-vitb-normal) | Microsoft / Ruicheng | MIT |
| [RVM small](https://github.com/google-deepmind/representations4d) | 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](THIRD_PARTY_NOTICES.md)
identifies those changes and the bundled license texts. Nothing here implies
endorsement by the original authors or their organizations.