H3-metal: Native MiniMax-H3 Inference for Apple Silicon

h3-metal is a specialized inference engine designed to bring MiniMax-H3 capabilities directly to Mac computers utilizing Apple Silicon.

🛠 Development Roadmap

The project is being developed through a series of "vertical slices" to ensure functional stability at every stage.

Current Progress

• Deterministic host/model metadata
• Portable Metal block parity
• Prompt encoding
• End-to-end Prompt-to-video/audio
• First/last-frame conditioning
• Ordered Ref2VA (Image/Video/Audio)
• General optimization $\rightarrow$ Currently focusing on incremental Metal performance and memory tuning for M3 Max and M5 Max chips.

---

🚀 Getting Started

Prerequisites

To build and run the model, ensure the following are present:

1. A Hugging Face snapshot located at ./MiniMax-H3.
2. FFmpeg and FFprobe installed and available in your system PATH.

Compilation and Inspection

Use the following command to compile the project:

make -j8

To verify the model's layout and identify the active Metal device without loading weights or creating media, run:

./h3 --info -d ./MiniMax-H3

---

💻 Usage Modes

1. Interactive Session

By omitting the -p flag, you enter an Iris-style interactive environment:

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

Why use interactive mode? The system keeps the BF16 prompt conditioning, the prepared DiT, and the video decoder resident in memory. This means if you change the seed but keep the prompt, you don't have to avoid reloading and re-encoding everything.

Interactive Command Reference

Conditioning & References

You can anchor your video using specific frames:

!first opening.png $\rightarrow$ Sets the starting frame. !last ending.png $\rightarrow$ Sets the final frame.

For general Ref2VA conditioning, use !ref-image PATH. These are processed as an ordered list:

• The first image becomes Picture 1.
• The second becomes Picture 2, and so on.
• Note: The actual filenames are ignored by the model.

Example Prompt:

"Make the person shown in Picture 1 wave to the camera."

Reference Management:

• !refs: List all current references.
• !ref-remove N: Delete a specific entry.
• !refs clear: Wipe all references.

⚠️ Constraint: You cannot combine !ref-image references with !first or !last anchors.

---

⚡ Performance & Optimization

Generating a "Fast" Video

To create a quick, validated result, use the balanced preset. This generates 22 frames at 24 fps, resulting in a duration of: $\text{Duration} = \frac{22 \text{ frames}}{24 \text{ fps}} \approx 0.92 \text{ seconds}$

./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 \
 --show \
 -o outputs/fox-fast.mp4

Parameter Breakdown

• --steps 20: The standard number of denoising passes.
• --reuse 2: Instead of 20 fresh velocities, it computes 11 and extrapolates the rest.
• --layers 45: Utilizes 45 out of 50 transformer blocks to reduce $\text{Time} \downarrow$ and $\text{Unified Memory} \downarrow$.

Visual Previews

The engine supports graphical protocols for Kitty, Ghostty, iTerm2, WezTerm, and Konsole.

• Mechanism: It loads a resident preview VAE to show a middle-video frame after every Euler transition.
• Retina Display: Defaults to $2\times$ zoom for macOS Retina screens. Use --zoom 1 for standard HiDPI displays.
• Overhead: Enabling --show adds preview decoding time and requires approximately $10 \text{ GiB}$ of additional temporary memory.

Thermal & Iteration Tips

• --profile is purely for telemetry and doesn't change the generation logic.
• The first run is slower due to filesystem caching and model loading.
• Warning: This workload is highly sensitive to thermal throttling. When benchmarking, alternate between different variants while the hardware is warming up.

Ultra-Fast Iteration

For the fastest possible turnaround, request a very low number of passes:

./h3 --profile -d ./MiniMax-H3 -p "A red fox..." --width 512 --height 512 --frames 22 --steps 4 --layers 50 --reuse 1 --show -o outputs/fox-four-step.mp4

• --steps N defines the exact number of passes.
• Passes between 4 and 7 follow a specific "low-budget" schedule; increasing the count in this range progressively enhances motion and detail.
• Tip: Always keep --reuse 1 when using such small step budgets.