Modelpublic

scragnog/MiniMax-Music3-GGUF

sourceHugging Faceotherupdated 11d agoView on Hugging Face

5likes80kdownloads

Model Card

MiniMax-Music3 — GGUF

GGUF conversion of MiniMaxAI/MiniMax-Music3 for [HOT-Step CPP](https://github.com/scragnog/HOT-Step-CPP), a fully local desktop app for AI music generation with a native C++/GGML engine. As far as we know this is the first GGUF conversion of this model.

These files are downloaded automatically by HOT-Step's Model Manager when the MiniMax-Music3 backend is selected. They are not usable with llama.cpp alone: mm3-lm-*.gguf is structurally a Qwen3 GGUF, but music generation requires the full five-module pipeline (LM → RVQ depth decoder → condition encoder → flow-matching DiT → vocoder) implemented in HOT-Step's engine.

Split format (one GGUF per component)

Since 2026-08-14 the repo carries one file per pipeline component, so each can be picked at its own quantisation and swapped without re-downloading the others:

File family	Component	Quants
`mm3-lm-<quant>.gguf`	Global LM (8.59B, Qwen3 arch, 200k vocab incl. 16,384 semantic audio codes) + full tokenizer	f16 · q80 · Q6K · Q5KM/S · Q4KM/S · NVFP4 · MXFP4 · Q3KL/M/S · Q2_K
`mm3-dit-<quant>.gguf`	Flow-matching DiT (2.4B)	same ladder
`mm3-depth-<quant>.gguf`	RVQ depth decoder (0.6B)	same ladder (Q8_0 is the validated quality floor)
`mm3-cond-f16.gguf`	Condition encoder (25M)	f16 only — never quantised
`mm3-voc-f16.gguf`	Vocoder (54M)	f16 only — never quantised
`LICENSE`	MiniMax-Music3 Community License (governs the weights)	—

Suggested combos: quality = everything f16 (~24 GB VRAM); recommended = LM/DiT/depth q80 + f16 frontends (~13 GB); **balanced** = LM q80 + DiT Q4KM + depth q80 (~12 GB download, the split's headline mix); **fast on RTX 50-series** = LM/DiT NVFP4 + depth q80. Audio-code LMs degrade audibly below Q5 — the sub-Q5 LM files exist for experiments, not listening.

The legacy two-file layout (mm3-synth-<quant>.gguf bundling depth+cond+dit+voc) remains available for older HOT-Step versions; current versions load either, preferring split files.

Output: 44.1 kHz stereo, up to 5 minutes.

Training files (added 2026-08-31)

Two more files, needed only by HOT-Step's Training Studio when training an MM3 LoRA. Neither is loaded during generation, and neither is in the generation packs. Download them together as the Model Manager's MiniMax-Music3 Training pack.

File	Component	Why it is needed
`mm3-rvq-53kpooled-f32.gguf`	Audio → RVQ codes encoder (169M)	The codes stage turns your dataset's audio into the code streams the LM trains on
`mm3-enc-f16.gguf`	DAV audio encoder (44.1 kHz stereo → 128-channel flow latents)	Input stage of the same codes job
`mm3-lm-bf16.gguf`	The LM in its source BF16 precision (17.2 GB)	OPTIONAL, training only (added 2026-09-03). Picked as the training base it lets the trainer run the projection GEMMs on BF16 tensor cores (`--weights bf16`) instead of the F32 fallback every other base uses: 1.4x faster per step than q80 on a 5090 at matched crop, for ~9 GB more VRAM, so it wants a 40 GB+ card at the default crop. Not better than f16 for generation; render on q80 as always
`mm3-rec7-f16.gguf`	rec7 state encoder (audio → LM frame hiddens, 170M)	OPTIONAL — only the codes stage's "Cover-launder" option (dense-mix training fix, 2026-08-31). Carries the LM's two semantic table slices so laundering never runs the 8B. PurpleOrc's m3-rec7-encoder (MIT), converted with `convert-rvq-encoder.py --head --m3`

Training also wants mm3-depth-f16.gguf specifically. The quantised depth files that ship with the generation packs are for generation.

MiniMax never released the official audio tokeniser, so the RVQ encoder here is a community reimplementation: [PurpleOrc's open-rvq encoder](https://huggingface.co/PurpleOrc/open-rvq-encoder-minimax-music3-169m-53k), SimpleTuner's v4 architecture trained from scratch on a 53k-track multilingual corpus, converted to GGUF and mirrored here so the Model Manager has one place to fetch from. Its reported holdout scores and training code are on PurpleOrc's repo, which is the place to read before drawing conclusions about it.

Codes are encoder-specific. An adapter trained on this encoder's codes has to keep using this encoder at inference; swapping encoders means re-exporting every code cache.

Conversion provenance

Converted with HOT-Step's `engine/tools/convert-mm3.py` from the bf16/fp16 safetensors published by MiniMax (via the Comfy-Org repackage), then split per component with `engine/tools/split-mm3.py` (byte-exact tensor passthrough — a split file's tensors are bit-identical to the bundle's). Vocoder weight-norm folded at conversion; vocoder and DiT Fourier/RoPE bases pinned F32; all 911 tensors shape-validated. The HOT-Step implementation is parity-validated against the official diffusers reference (per-module correlation ≥ 0.9999 vs fp32; full-pipeline replay 0.9988). The split-model approach follows ServeurpersoCom/minimaxmusic.cpp, whose author kindly sanctioned reuse of his design.

Credits

All credit for the model belongs to [MiniMax](https://huggingface.co/MiniMaxAI). MiniMax-Music3 is their work — the architecture, the training, and the release. This repository contains nothing but a format conversion of their weights, and the Structured Caption format that drives the model is their design.

Thanks also to:

—[Pascal (ServeurpersoCom)](https://github.com/ServeurpersoCom) for acestep.cpp, the C++/GGML engine HOT-Step extends, and for minimaxmusic.cpp, whose per-component split design this repo's layout follows — kindly sanctioned for reuse.
—[ACE Studio / StepFun](https://huggingface.co/ACE-Step) for ACE-Step, the model HOT-Step is built around.
—[PurpleOrc](https://huggingface.co/PurpleOrc) for the open-rvq encoder mirrored here, and for offering it to the community in the first place; and to [bghira / SimpleTuner](https://github.com/bghira/SimpleTuner) for the v4 encoder architecture it was trained from.
—[The OpenMOSS Team](https://huggingface.co/OpenMOSS-Team) for MOSS-Music-8B-Instruct, which writes the Structured Captions that prompt this model — from listening to a reference track rather than from text. GGUF conversion: scragnog/MOSS-Music-8B-Instruct-GGUF.

License

The model weights are subject to the MiniMax-Music3 Community License (included here as LICENSE, per its notice-preservation requirement). Notable terms: prominent display of "MiniMax-Music3" in commercial products, separate authorization above US$20M annual revenue, acceptable-use policy, and clear disclosure of AI generation for publicly distributed outputs. The conversion adds no additional restrictions.