Run H3 on Mac from zero with pure C + Metal — MiniMax H3 tutorial
Without Python, PyTorch, or ComfyUI, compile h3.c on Apple Silicon, validate the model, and generate a first MP4 with audio.
Audience: Apple Silicon users who can use Terminal and do not want to build an NVIDIA or ComfyUI stack.
Hardware: An M-series Mac with enough unified memory and storage. Start at 512×512 and 22 frames; speed and usable memory vary widely by chip.
Prerequisites
- macOS, Git, and Xcode Command Line Tools
- FFmpeg and FFprobe callable from Terminal
- A complete MiniMax-H3 Hugging Face snapshot in a MiniMax-H3 directory
- Memory-heavy applications closed and enough time reserved for the first load
Steps
- Run xcode-select --install in Terminal; macOS will say when it is already present. Install FFmpeg with Homebrew, then verify both ffmpeg and ffprobe.
- Clone antirez/h3.c and enter the repository. Keep the code separate from the weight files; this guide expects the complete model at ./MiniMax-H3.
- Download the complete MiniMaxAI/MiniMax-H3 Hugging Face snapshot into ./MiniMax-H3. Preserve filenames and do not download only the apparent main checkpoint.
- Run make -j8, then create outputs. If compilation fails, confirm the active compiler is Apple clang and repair Command Line Tools before changing build flags.
- Run ./h3 --info -d ./MiniMax-H3. It validates model layout and prints the Metal device without mapping every weight or generating media. Resolve missing files here.
- Run the balanced 512×512, 22-frame, 20-step example first. The first invocation pays model-loading and filesystem-cache costs, so its total time is not a stable benchmark.
- Keep --show only when the terminal supports graphical protocols and unified memory is sufficient. Remove it under memory pressure because preview adds about 10 GiB of temporary model residency.
- Confirm outputs/fox-fast.mp4 plays with audio. Repeat the same command; the second run is a more useful performance comparison.
- For interactive work, run ./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6. Use !status, !seed random, !seconds 2, and !save output.mp4 to control the session.
- Use !first opening.png and !last ending.png for boundary frames, or !ref-image person.png for a general reference. Ref2VA references cannot be mixed with !first or !last; clear the old mode first.
Commands
xcode-select --install
brew install ffmpeg
git clone https://github.com/antirez/h3.c && cd h3.c
hf download MiniMaxAI/MiniMax-H3 --local-dir MiniMax-H3
make -j8 && mkdir -p outputs
./h3 --info -d ./MiniMax-H3
./h3 --profile -d ./MiniMax-H3 -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur, soft footsteps and wind." --width 512 --height 512 --frames 22 --steps 20 --layers 45 --reuse 2 -o outputs/fox-fast.mp4
./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6
make test
Caveats
- h3.c evolves quickly; verify weight layout, CLI flags, and performance claims against the current README.
- --show is an optional preview, not a generation requirement; it adds decode time and about 10 GiB of temporary memory.
- Four steps are useful for very fast previews but lose detail and motion quality versus 20; do not compare them as equal-quality runs.
- Apple Silicon uses unified memory. Low free memory, swapping, and thermal throttling can make a run far slower than public benchmarks.
View original source · antirez · 2026-08-23