cdelta/CorridorKey-v2-MLX

CorridorKey v2 · MLX

FP32 · FP16 · Q8 matting profiles for Apple Silicon

Source & CLI · Original model · Original project · License

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

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

Precision downloads

Download	CLI selection
FP32	--precision fp32
FP16	--precision fp16
Q8 / 8-bit	--precision q8

Browse the Collection. 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:

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 documents input, output, hint, and scratch-storage behavior.

Select a variant using the same model root:

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

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.