minimaxmusic.cpp

Local MiniMax Music 3 song generation server with browser UI, powered by GGML. Lyrics and a structured caption in, complete stereo 44.1kHz songs out. Runs on CPU, CUDA, Vulkan.

Download models

Grab one GGUF of each type from Hugging Face and drop them in the models/ folder:

https://huggingface.co/Serveurperso/MiniMax-Music3-GGUF/tree/main

The LM also ships in BF16 / Q6_K / Q5_K_M, the DiT in F32 / Q6_K / Q5_K_M / Q4_K_M, the depth decoder in BF16. The full quantized combo runs in about 9 GB of VRAM, the full native set in about 29 GB.

Alternative: ./models.sh downloads the default set automatically (needs pip install hf), ./models.sh --all everything.

Build

git clone --recurse-submodules https://github.com/ServeurpersoCom/minimaxmusic.cpp.git
cd minimaxmusic.cpp

Windows

To build from source, install Visual C++ Build Tools (select "Desktop development with C++" workload) and optionally the CUDA Toolkit and/or the Vulkan SDK.

buildcuda.cmd     # NVIDIA GPU
buildvulkan.cmd   # AMD/Intel GPU (Vulkan)
buildall.cmd      # all backends (CUDA + Vulkan + CPU, runtime loading)

Linux / macOS

./buildcuda.sh    # NVIDIA GPU
./buildvulkan.sh  # AMD/Intel GPU (Vulkan)
./buildcpu.sh     # CPU only (with BLAS)
./buildall.sh     # all backends (CUDA + Vulkan + CPU, runtime loading)

macOS auto-enables Metal and Accelerate BLAS with any of the above.

Convert

To build the GGUFs locally from the official checkpoints instead, download MiniMaxAI/MiniMax-Music3 into checkpoints/. Only the five component subfolders and the tokenizer are used; the rest of the repository (qwen_7B/, training checkpoints) can be skipped.

pip install hf gguf numpy
./checkpoints.sh  # downloads the needed subfolders of MiniMaxAI/MiniMax-Music3
./convert.py      # native GGUF, byte-exact dtypes from the source, skips existing
./quantize.sh     # every quant from the natives, idempotent

Run

./server.sh       # Linux / macOS
server.cmd        # Windows

Open http://localhost:8086 in your browser. The WebUI handles everything: write a structured caption, set lyrics and duration, generate, play, and download tracks.

Models are loaded on the first job (zero GPU at startup). By default the server runs the strict VRAM policy: the LM stage and the synthesis stage swap in and out per job, so the LM and the DiT never coexist. Pass --keep-loaded to keep every model resident instead; switching one quant in the UI then loads only that model, the others stay warm.

Server options

Usage: ./mm-server --models <dir> [options]

Required:
  --models <dir>         Directory of GGUF model files

Server:
  --host <addr>          Listen address (default: 127.0.0.1)
  --port <N>             Listen port (default: 8086)
  --max-batch <N>        LM batch limit (default: 1)
  --max-seq <N>          LM KV cache size (default: model context)

Debug:
  --no-fa                Disable flash attention
  --no-batch-cfg         Split CFG into two separate forwards (LM + DiT)
  --clamp-fp16           Clamp hidden states to FP16 range
  --dump <dir>           Dump intermediate tensors

# quick one-shot
./build/mm-synth \
    --models models \
    --caption "Melancholic synthwave, slow tempo, analog pads" \
    --lyrics "[verse]..." \
    --out song.mp3

# same request schema as the server
./build/mm-synth \
    --models models \
    --request /tmp/request.json

./build/mm-lm --models models --request song.json --out plan.json
./build/mm-synth --models models --request plan.json --out song.mp3

Technical documentation

docs/ARCHITECTURE.md covers the complete MM3Request JSON reference, the five model components, the autoregressive and flow matching inference recipe, quantization strategy, VRAM and model routing, the parity and cosine similarity test suites, and architecture internals.

Acknowledgements

Independent C++ implementation based on MiniMax Music 3 by MiniMax. All model weights are theirs, this is just a native backend. Structural template: acestep.cpp.

@misc{minimax2026music3,
	title={MiniMax Music 3},
	author={MiniMax},
	howpublished={\url{https://github.com/MiniMax-AI/MiniMax-Music3}},
	year={2026},
	note={GitHub repository}
}