https://github.com/antirez/h3.c
The text was too long, so I asked Perplexity to write it for me. ㅎ
Anyway, I'm going to try running it on my M5 Air 32G tomorrow.
There are user experiences of people who have run it on M5 Air 32G on github issues.
antirez's h3.c, Introduction to MiniMax H3 Engine Running Directly on Mac with C+Metal
Recently released on GitHub, h3.c is a **native inference engine for the MiniMax H3 video and audio generation model**, created by antirez (Salvatore Sanfilippo), who is famous for Redis.[cite:26][cite:4]
The key point is that it runs H3 directly on Apple Silicon Macs using **pure C + Metal + a little Objective-C and Metal shaders**, without heavy stacks like Python, PyTorch, or ComfyUI.[cite:26][cite:5]
The first sentence of the official README defines this project as follows.
Native MiniMax-H3 inference for Apple Silicon.[cite:26]
In other words, the goal is to run MiniMax H3 on Mac "as directly, quickly, and accurately as possible".
What h3.c Does
MiniMax H3 is a **multimodal diffusion model that generates both video and audio simultaneously from text input**.[cite:4][cite:11]
h3.c runs this model on Mac in the following ways:
Text → Video + Sound
Generates both video and embedded audio simultaneously from a single-line prompt.[cite:5][cite:6]
First/Last Frame Anchor (FL2VA)
Enables "keyframe-based extension" generation where the model naturally connects between an opening still cut and an ending still cut image.[cite:26][cite:28]
Ref2VA Reference Mode
Allows you to input multiple images, existing videos, or audio clips in order as reference materials. You can then use tokens like
Interactive Iris Style CLI Session
Provides a terminal-based interactive session that allows for continuous experimentation by changing only the seed while keeping the same prompt and conditions. This is possible after loading the model once.[cite:5][cite:4]
The engine itself is released under the MIT license, allowing code modification, redistribution, and commercial use. However, it's important to note that **MiniMax H3 weights are distributed separately on Hugging Face under a different license**.[cite:4][cite:27]
Environment and Build
The required environment is simpler than you might think.
The basic build and information check process according to the README is as follows.[cite:26][cite:28]
git clone https://github.com/antirez/h3.c.git
cd h3.c
make -j8
mkdir -p outputs
./h3 --info -d ./MiniMax-H3
--info flag is used to check the entire model layout and the selected Metal device. It does not map all the weights or actually generate a video.
Actual Generation: Non-Interactive vs Interactive
Non-Interactive Single Generation
The combination introduced as "balance preset" in the README is roughly as follows.[cite:26][cite:6]
Resolution: 512×512
Frames: 22 (approximately 0.9 seconds)
Denoising steps: 20
Active DiT layers: 45
--reuse 2 (11 out of 20 steps are actual denoiser forward, the rest are extrapolated)
An example command is as follows.
./h3 --profile \
-d ./MiniMax-H3 \
-p "A red fox walks through fresh snow in a pine forest..." \
--width 512 --height 512 \
--frames 22 --steps 20 \
--layers 45 --reuse 2 \
--show \
-o outputs/fox-fast.mp4
--show allows you to preview intermediate frames and the final sequence in graphical terminals like Kitty/Ghostty/iTerm2/WezTerm/Konsole.
Interactive Sessions
Running without a prompt starts an Iris-style CLI session.
./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6
Entering a prompt string in this state will sequentially generate numbered video files, and you can use the following commands within the session:
!status – Prints the current session status.
!seed random – Changes the seed randomly.
!seconds 2 – Sets the length in seconds.
!show – Displays preview frames.
!save output.mp4 – Saves the current result to a file.
!cache – Caches the prepared state for reuse.
!first PATH, !last PATH – Sets first/last frame anchors.
!ref-image PATH – Adds a Ref2VA image reference.
This workflow is suitable for "repeatedly experimenting by changing only the seed while keeping the prompt conditions and DiT·VAE in memory."
Quality and Speed: Tuning Knobs
The README of h3.c is almost a tutorial on on-device inference tuning, detailing knobs that change quality and speed.
Here's a summary of some representative knobs:
Number of Denoising Steps (--steps)
4–7 steps
For a 512×512·22 frame clip, the 4-step path takes about 3.5 seconds on an M5 Max.
Running the same clip with a 29-pass reference path takes 26.4 seconds, described as "a mode optimized for preview/iterative experiments with reduced detail."
20 steps
50 steps
Number of Layers (--layers)
50 layers – Uses all DiT blocks, the most conservative quality standard.
45 layers – "Layer thinning" mode removes some middle layers based on gates, reducing compute and memory while maintaining a significant portion of quality.
40 layers – A more aggressive preview mode with large speed and memory savings but potential for greater quality degradation.
Full Denoiser Reuse vs. Core Reuse
Token Reduction (--token-reduction)
After the middle block, video tokens are grouped into pairs horizontally to reduce computation in the tail section and later restored to the original resolution. [cite:26][cite:6]
A representative example is the README figure of 39.13 seconds → 28.06 seconds (about 28% reduction) based on 512×512·50 blocks. [cite:12][cite:27]
However, since the composition and detailed details may change, it is left as an "option" rather than a default value. [cite:6][cite:27]
Internal Canvas Scaling (--render-width, --render-height)
Targeting 512×512, the internal DiT/VAE runs at 384×384 or 320×320 and is finally upscaled using vImage. [cite:26][cite:6]
According to README, the DiT time is reduced by about 33% and the VAE time by 18% for a 384 internal render, while the results of the real series are "clean and recognizable". [cite:26][cite:28]
Resolution and Length Constraints
MiniMax H3 allows only valid frame numbers in the form of 5 + 17n based on 24fps. [cite:11][cite:26]
Representative combinations summarized from README and external articles are as follows: [cite:26][cite:28]
22 frames – about 0.92 seconds
39 frames – about 1.63 seconds
56 frames – about 2.33 seconds
107 frames – about 4.46 seconds
243 frames – about 10.1 seconds
362 frames – about 15.1 seconds
The resolution has a width and height that are multiples of 32, and the product of the two must not exceed 768 × 1344. [cite:6][cite:11]
Valid canvas combinations repeatedly verified are 512×512, 768×768, 1344×768, 768×1344, 1024×768, 768×1024, and 256×256 native preview canvas. [cite:6][cite:27]
The 256×256 mode is a "fast preview" mode that automatically halves the RoPE coordinates. It has experimental results in README showing that it eliminates repetitive pattern artifacts in long fox renders while maintaining stable composition in portraits and figures. [cite:26][cite:27]
Performance and Memory: Actual Figures
Combining various articles and README, the performance and memory characteristics of h3.c are approximately as follows.
License and Legal Precautions
An important point is that the engine code and model licenses are separated.
The h3.c code itself is released under the MIT license, allowing modification, redistribution, and commercial use. [cite:4][cite:27]
However, MiniMax H3 weights are distributed under a separate license from Hugging Face, and there are analyses that include clauses restricting local distribution and commercial use in specific regions such as the EU, UK, US, and Korea. [cite:27][cite:28]
In other words, the legal responsibility of "the person who implemented the engine" and "the person who actually downloads the weights and runs them" is different, and it is necessary to carefully read and comply with the license in the relevant country even for research and testing purposes. [cite:27][cite:28]
Who Can Use This Project?
In the video/AI field, h3.c occupies a rather unique position.
It is not "a tool that allows you to create beautiful videos with just one button click on a prepared Web UI" for general users, but it is an extremely attractive project for the following people:
Mac-based creators and developers
Engineers interested in on-device inference optimization
If you want to study actual code and benchmarks for optimization patterns such as Metal 4/TensorOps, int8 quantization, RoPE/RMS fuse, activation alias, streamed text encoder.[cite:12][cite:27]
Developers who want to create their own video engine
If you want to design and control the video generation pipeline directly at the C/Metal level, rather than using node-based tools like ComfyUI, h3.c is an excellent reference implementation.[cite:4][cite:6]
Conversely, if you just want to quickly "extract pretty result videos," there's no need to go down to the Metal/C level. It's also worth considering that Web UIs and Python tools are still more convenient in terms of accessibility and plugin ecosystems.[cite:5][cite:14]
Personal Use Imagination
Assuming you have an M5 Max Mac with 96–128GB, here's a rough workflow for using h3.c personally.
Quickly align composition and movement with a 256×256 native preview
Verify character and camera work first in the fast preview mode with RoPE optimization.[cite:26][cite:27]
Use 512×512·20 steps·layer 45·reuse 2 as the default path
Turn token reduction and internal canvas reduction (384/320) on and off depending on the situation, finding the optimal point between quality and speed.[cite:6][cite:27]
Quality verification of the final shot with a 50-step oracle
Run the same prompt, resolution, and frame count once with 50 steps BF16/reference path to make sure that preview mode hasn't significantly messed up composition, body, or motion.[cite:26][cite:12]
Experiment with reference-based extension
Put existing live-action footage into --ref-silent-video and have H3 inherit only the motion, or put several character photos into a
In summary, h3.c is more of an experimental engine for pushing Mac on-device performance to the limit while dissecting the internals of a video generation model than a "ready-to-use video generation tool."[cite:11][cite:12]
From that perspective, there are many insights to be gained just by reading the README and code. Therefore, if you're interested in on-device LLM/video model optimization, it's worth taking a look at this project.[cite:12][cite:27]
▶ Original source: https://github.com/antirez/h3.c
