joemattie/MiniMax-Music3-GGUF

MiniMax-Music3 GGUF for audio.cpp

Component GGUF package of MiniMaxAI/MiniMax-Music3 for local inference with audio.cpp, the ggml-based audio inference engine.

What this is for

MiniMax-Music3 generates full songs (vocals plus arrangement, 44.1 kHz stereo, up to six minutes) from a music description caption and lyrics. The official release runs through the diffusers MiniMaxMusic3ModularPipeline in Python; this package exists so the model can run natively on consumer GPUs through audio.cpp's C++/CUDA runtime, with no Python or PyTorch at inference time.

The files here were produced while porting MiniMax-Music3 to audio.cpp as the minimax_music3 community model family (PR #241). The port reimplements the whole pipeline against these GGUFs: the Qwen3-8B autoregressive stage that emits one semantic code per 40 ms frame with classifier-free guidance, the 4-layer RVQ depth decoder that fills seven residual codebooks per frame, the 36-layer flow-matching transformer that denoises Flow-VAE latents over overlapping 200-frame windows, and the DAC-style vocoder that renders stereo audio. Every component was validated against the diffusers reference implementation (exact tokenizer ids, exact greedy depth-decoder rollouts, 0.9998+ logit correlation on the language model, 0.99998 on the flow transformer); the parity harness lives in tests/minimax_music3/ in the audio.cpp tree.

This repo is the download source the minimax_music3 model spec points at (files are nested under MiniMax-Music3-GGUF/ to match the audio.cpp installer layout), so the native web UI's one-click installer works against it directly. It doubles as the interim distribution point until the package is mirrored into the official audio-cpp/audio.cpp-gguf catalog.

Files

File	Component	Precision
lm_q8_0.gguf	global Qwen3-8B language model (lm_head sliced to the sampleable rows)	Q8_0, default
lm_q4_k.gguf	alternative global LM for smaller VRAM budgets	Q4_K
depth_decoder_f16.gguf	RVQ depth decoder	F16
dit_f16.gguf	flow-matching transformer	F16
condition_encoder_f32.gguf	condition encoder	F32
vocoder_f16.gguf	Flow-VAE decoder (torch weight norm folded at conversion)	F16
tokenizer/	Qwen2 tokenizer sidecars	-

Conversion choices worth knowing about:

• The language model's 200k-row output head is sliced to the 16385 rows the sampler can ever pick (the audio end token plus the 16384 semantic codes), saving about 1.5 GB.
• The DiT and depth decoder are stored F16 rather than the checkpoint's BF16: the CUDA BF16 matmul path is several times slower than F16 on Ampere, the weights fit F16's range with a wide margin (max magnitude about 3.2), and component parity is equal or better.
• Everything converts from the upstream repo's diffusers-format safetensors with scripts/minimax_music3/convert_gguf.py in the audio.cpp tree; the qwen_7B/ legacy packaging and the training-time .pth files upstream are not needed.

Usage

Requires an audio.cpp build that includes the minimax_music3 family (PR #241); CUDA is the supported backend.

hf download joemattie/MiniMax-Music3-GGUF --include "MiniMax-Music3-GGUF/*" --local-dir models

build/linux-cuda-release/bin/audiocpp_cli \
  --task gen --family minimax_music3 \
  --model models/MiniMax-Music3-GGUF/lm_q8_0.gguf \
  --backend cuda --threads 8 \
  --text "$CAPTION" --request-option lyrics="$LYRICS" \
  --request-option duration_seconds=60 --seed 42 --out song.wav

--text carries the music description caption (genre, mood, vocals, instrumentation, arrangement); lyrics carries the lyrics with [verse] / [chorus] structure tags on their own lines. Pass lm_q4_k.gguf as --model to select the smaller LM variant. The model also appears in the audio.cpp native web UI (audiocpp_server --ui) under Music generation.

On one RTX 3090, 32 seconds of audio renders in about 67 seconds (RTF about 2.1), with VRAM peaking around 14 GB. Full options, conversion commands, parity tables, and performance notes: docs/community_models/minimax_music3.md.

License

The weights are a converted (quantized and restructured) derivative of MiniMaxAI/MiniMax-Music3 and remain subject to the MiniMax-Music3 Community License linked above. The conversion scripts and runtime are Apache-2.0 as part of audio.cpp.