The Problem

Running MiniMax-H3 (a video/audio generation model) on Apple Silicon requires bridging a Python/PyTorch model into native Metal performance. The official stack is heavy and slow on Macs. This repo is a native C inference engine that runs H3 directly on Apple Silicon's GPU via Metal, targeting practical generation speeds on M3/M4/M5-class hardware.

What This Does

h3.c is a from-scratch C implementation of MiniMax-H3 inference. It loads Hugging Face model snapshots (via h3_safetensors.c), runs the DiT transformer (h3_dit.c), and encodes/decodes video and audio through dedicated VAEs (h3_video_vae.c, h3_audio_vae.c). All heavy compute goes through Metal shaders (h3_shaders.metal, h3_metal.m).

The project is built as vertical slices: model metadata, Metal block parity, prompt encoding, then prompt-to-video/audio with first/last-frame conditioning and ordered Ref2VA references. Those features work end-to-end. Current work is incremental Metal performance tuning on M3 Max and M5 Max.

How It Is Wired

Execution starts in main.c. It parses CLI flags, loads the model directory, and dispatches to either --info (model layout check) or the interactive session. The session loop routes prompts through h3_text_encoder.c for conditioning, then h3_dit.c for denoising, then h3_video_vae.c for decode, and writes MP4 via h3_ffmpeg.c. Audio goes through h3_audio_vae.c. Metal kernels are dispatched from h3_metal.m using the shaders in h3_shaders.metal.

The control flow is flat: main.c -> session loop -> encoder/DiT/VAE -> Metal. The widest blast radius sits in h3_dit.c (the transformer core) and h3_metal.m (all GPU dispatch); changes there ripple across every generation path.

File map:

  • h3.c/h3.h — core model orchestration
  • h3_dit.c — diffusion transformer (the heavy compute)
  • h3_video_vae.c, h3_audio_vae.c — media codecs
  • h3_ffmpeg.c — MP4 muxing
  • h3_metal.m, h3_shaders.metal — Metal GPU kernels
  • main.c — CLI and interactive session
  • tests/ — 21 test files, mostly integration-style (test_real_*)

How To Use It

Build and run are documented in the README. Commands verbatim:

make -j8
mkdir -p outputs
./h3 --info -d ./MiniMax-H3

Requires a Hugging Face snapshot at ./MiniMax-H3 and FFmpeg/FFprobe on PATH. For generation:

./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6

The --profile flag prints phase timings. --show enables terminal preview (Kitty/Ghostty/iTerm2/WezTerm). No environment variables or config files are required.

Real-World Use

This fits a content-generation pipeline where you need local, fast video synthesis on a Mac without a GPU server. A typical workflow: load a prompt, generate a short clip, save to MP4, then feed it downstream to an editor or renderer. The interactive session keeps the model resident, so iterating on seeds or prompts avoids reloading weights.

Code Health & Issues

Static analysis (not opinion) reports 87 findings: 53 high, 34 medium, 0 low.

  • High — Deep nesting (x53) in h3.c, h3.h, h3_audio_vae.c. Max indentation depth is 12; control flow is hard to follow. Fix: early returns and guard clauses.
  • High — Duplicated code blocks — 198 repeated 6-line blocks across 33 files (h3_audio_vae.c, h3_video_encoder.c, h3_video_vae.c, h3_dit.c). Fix: extract shared helpers.
  • High — Oversized files (x6) — h3.c alone is 1643 code lines. Fix: split by responsibility.
  • High — No CI — 38 source files, no workflow that builds or tests. Every change merges unverified.
  • Med — No CI/CD pipeline — no .github/ or CI config detected.

Tests exist (21 files) but there is no automated gate running them.

The Bottom Line

This is a serious, working native inference engine for a complex model on Apple Silicon. The architecture is sound and the feature set is real. The code needs refactoring (deep nesting, duplication, oversized files) and CI before it is maintainable by more than one person. Use it if you need local H3 generation on a Mac and can tolerate the current code quality.