diff --git a/docs/minimax-h3.md b/docs/minimax-h3.md new file mode 100644 index 00000000..90c51fcb --- /dev/null +++ b/docs/minimax-h3.md @@ -0,0 +1,211 @@ +# MiniMax-H3 + +edge-dit.cpp supports MiniMax-H3 video + audio generation through the standalone +component-loading path. The implementation follows the MiniMax-H3 interface used +by `stable-diffusion.cpp`: one diffusion checkpoint, Qwen3-VL text/vision encoder, +video VAE, and optional audio VAE. + +## Model files + +MiniMax-H3 runs with four model components. The diffusion checkpoint changes by +mode; the encoder and VAEs are shared. + +| Component | File name | Source | +|---|---|---| +| Qwen3-VL text/vision encoder | `qwen3vl_32b_minimax_h3-Q4_K_M.gguf` | [leejet/MiniMax-H3-GGUF](https://huggingface.co/leejet/MiniMax-H3-GGUF) | +| Video VAE | `minimax_h3_video_vae_fp16.safetensors` | [Comfy-Org/MiniMax-H3](https://huggingface.co/Comfy-Org/MiniMax-H3) | +| Audio VAE | `minimax_h3_audio_vae_fp32.safetensors` | [Comfy-Org/MiniMax-H3](https://huggingface.co/Comfy-Org/MiniMax-H3) | + +### FL2VA checkpoint + +| Component | File name | Source | +|---|---|---| +| Diffusion model | `minimax_h3_fl2va-Q4_K_M.gguf` | [leejet/MiniMax-H3-GGUF](https://huggingface.co/leejet/MiniMax-H3-GGUF) | + +Supported modes: + +| Mode | Inputs | Output | +|---|---|---| +| T2VA | Text prompt | Video + audio | +| I2VA | Text prompt + first frame image | Video + audio | +| FL2VA | Text prompt + first frame image + last frame image | Video + audio | + +### Ref2VA checkpoint + +| Component | File name | Source | +|---|---|---| +| Diffusion model | `minimax_h3_ref2va_pruned-Q4_K_M.gguf` | [leejet/MiniMax-H3-GGUF](https://huggingface.co/leejet/MiniMax-H3-GGUF) | + +Supported reference inputs: + +| Input | CLI flag | Notes | +|---|---|---| +| Reference image | `--ref-image ` | Repeatable. Presented as `` to Qwen3-VL. | +| Reference video | `--ref-video ` | Repeatable. Directory of image frames sorted lexicographically; treated as 24 fps. | +| Paired video audio | `--ref-video-audio ` | Repeatable. The Nth WAV is paired with the Nth `--ref-video`. | +| Standalone audio | `--ref-audio ` | Repeatable. Independent audio reference, not attached to a video. | + +The reference inputs can be combined freely within Ref2VA. Ref2VA cannot be used +with `--image` or `--end-img` in the same request. + +MiniMax-H3 control frames are not supported for either checkpoint. + +## Common parameters + +MiniMax-H3 is a 24 fps audio-video model. The usual full-resolution setting is: + +```bash +-W 864 -H 480 --fps 24 --video-frames 56 --cfg-scale 1.0 --diffusion-fa --rng cpu +``` + +The frame count must satisfy `17k + 5` (for example `5`, `22`, `39`, `56`). The +examples below use 56 frames and 20 steps. + +Use `--video-format mp4` for H.264/AAC MP4 output when `ffmpeg` is available. +Without `--audio-vae`, the model can still generate video, but no generated audio +is decoded or muxed. + +## FL2VA usage + +### Text to video + audio + +```bash +ed-cli --video \ + --diffusion-model minimax_h3_fl2va-Q4_K_M.gguf \ + --vae minimax_h3_video_vae_fp16.safetensors \ + --audio-vae minimax_h3_audio_vae_fp32.safetensors \ + --llm qwen3vl_32b_minimax_h3-Q4_K_M.gguf \ + -p "A cat surfs on an ocean wave with upbeat surf-rock music." \ + --cfg-scale 1 -W 864 -H 480 --fps 24 --video-frames 56 --steps 20 \ + --diffusion-fa --rng cpu --video-format mp4 \ + -o minimax_h3_t2va.mp4 +``` + +### First-frame image to video + audio + +```bash +ed-cli --video \ + --diffusion-model minimax_h3_fl2va-Q4_K_M.gguf \ + --vae minimax_h3_video_vae_fp16.safetensors \ + --audio-vae minimax_h3_audio_vae_fp32.safetensors \ + --llm qwen3vl_32b_minimax_h3-Q4_K_M.gguf \ + --image first_frame.png \ + -p "Animate the provided first frame into a cinematic shot with matching sound." \ + --cfg-scale 1 -W 864 -H 480 --fps 24 --video-frames 56 --steps 20 \ + --diffusion-fa --rng cpu --video-format mp4 \ + -o minimax_h3_i2va.mp4 +``` + +### First + last frame to video + audio + +```bash +ed-cli --video \ + --diffusion-model minimax_h3_fl2va-Q4_K_M.gguf \ + --vae minimax_h3_video_vae_fp16.safetensors \ + --audio-vae minimax_h3_audio_vae_fp32.safetensors \ + --llm qwen3vl_32b_minimax_h3-Q4_K_M.gguf \ + --image first_frame.png --end-img last_frame.png \ + -p "Create a smooth transition from the first frame to the last frame with natural audio." \ + --cfg-scale 1 -W 864 -H 480 --fps 24 --video-frames 56 --steps 20 \ + --diffusion-fa --rng cpu --video-format mp4 \ + -o minimax_h3_fl2va.mp4 +``` + +## Ref2VA usage + +When using references, write the prompt so it explicitly mentions the reference +slots, such as ``, `