On-device, in pure MLX
MiniMax Music 3,
in pure MLX.
Dependency budget
One runtime dependency.
The runtime imports mlx and nothing else. A small local tokenizer reads the checkpoint's own Qwen2 BPE vocabulary; Hugging Face tokenizers checks its output during development and ships in the dev group, never in the runtime.
MLX reads safetensors directly, checkpoint paths are local-first, and WAV output uses the standard library. A package is added when runtime code actually imports it and the implementation shows why MLX or the standard library will not do.
Generation path
The whole checkpoint never has to be resident.
Unified memory does not make residency free. Each stage owns its weights for exactly as long as it needs them, then evaluates its durable output and drops them. Scroll the stages; the meter holds what is actually loaded.
Resident now
0.00 GiB
-
01
Prompt
Lyrics and a structured caption become conditional and unconditional token IDs. The tokenizer reads the checkpoint's exact Qwen2 BPE vocabulary. Nothing large is loaded yet.
0 GiB resident Qwen2 BPE -
02
Autoregressive
A Qwen3 global language model predicts one semantic codebook token per frame and carries long-range musical structure. A local depth decoder predicts seven residual codebooks, each conditioned on the global token and on the codes already emitted for that frame.
The stage keeps the fused hidden states, not only the codes. Discrete tokens alone cannot drive synthesis.
25 frames/s 8 codebooks 16,384 + 7 × 1,024 17.19 GiB resident -
03
Acoustic
A condition encoder projects the autoregressive hidden states into acoustic conditioning. A flow-matching diffusion transformer predicts Flow-VAE latents, advanced by an Euler solver.
Long inputs are synthesized in overlapping windows and recombined so the seams do not land audibly.
30 Euler steps 200-frame window 100-frame hop 9.15 GiB resident -
04
Decode
A DAC-style waveform decoder turns latents into native 44.1 kHz stereo. Windows are cropped and concatenated at full rate.
44.1 kHz stereo 0.20 GiB resident -
05
Output
A WAV file and its generation metadata. The current profile is native 44.1 kHz stereo PCM16. The reference 32 kHz serving profile is a separate, explicit output and is still being brought to parity -- the two are never quietly conflated.
0 GiB resident 44.1 kHz PCM16 today
MLX evaluation is lazy, which makes the ordering load-bearing: releasing a Python reference before the handoff arrays are evaluated is incorrect, because pending work can still hold the previous stage's weights. Every weight-owning stage materialises its durable output before teardown, and the release is verified by memory telemetry rather than left to garbage collection.
Stage handoff
What crosses between the phases is larger than the codes.
Acoustic synthesis consumes fused frame hidden states, shaped [1, frames, 8 × 4096]. They are durable stage state rather than a reason to keep the autoregressive weights loaded, and they are substantial even in BF16.
At the 9,000-frame maximum — six minutes at twenty-five frames a second — the handoff alone is larger than the waveform decoder it eventually feeds.
Python API
One request object, one local checkpoint.
The pipeline keeps only the checkpoint manifest and the tokenizer between requests. Model weights are loaded, evaluated, measured, and released one stage at a time.
# Dense is the correctness baseline; selective-q8 is experimental.
from mlx_minimax_music3 import GenerationRequest, Music3Pipeline
pipeline = Music3Pipeline("weights/mlx-dense/MiniMax-Music3")
result = pipeline.generate(
GenerationRequest(
caption="Warm acoustic folk, intimate vocal, "
"gentle fingerpicked guitar.",
lyrics="[verse]\nMorning light across the room",
audio_duration=10.0,
seed=0,
),
output="outputs/song.wav",
)
print(result.metadata.checkpoint_profile)
print(result.metadata.memory_reports)Every run reports the profile it used and the peak and active memory of each stage, so residency is something you can read back rather than something you have to trust.
Writing refuses to clobber an existing file unless overwrite=True is explicit. Lyrics must carry more than structure tags — for a vocal-free request, instrumental_lyrics() adds the content the model expects.
Where this stands
It runs end to end. What is left is parity.
Lyrics and a structured caption go in; a 44.1 kHz stereo WAV comes out, on one Mac, with no PyTorch anywhere in the path. Components are checked against the reference implementation rather than assumed.
| What | State |
|---|---|
| Lyrics and caption to stereo WAV, end to end | Running |
| Component parity against the reference | Validated |
| Phase-scoped residency with memory telemetry | Running |
| Local checkpoint conversion and manifests | Running |
| Overall music-quality parity | Tuning |
| Long-form generation | Tuning |
| Selective-q8 profile | Experimental |
| 32 kHz reference output profile | In progress |
Checkpoint
26.56 GiB that never ships with the package.
Model files are local runtime inputs. They do not belong in Git, in a wheel, or in a source distribution, and installing this package neither downloads them nor grants rights to them.
| Component | Runtime role | GiB |
|---|---|---|
| language_model/ | Qwen3-based global autoregressive model | 15.99 |
| rvq_depth_decoder/ | Seven residual acoustic codebooks | 1.20 |
| condition_encoder/ | Hidden-state fusion and acoustic projection | 0.09 |
| transformer/ | Flow-matching diffusion transformer | 9.06 |
| vocoder/ | Flow-VAE / DAC-style waveform decoder | 0.20 |
| tokenizer/ · scheduler/ | Prompt tokenization and Euler solver config | 0.01 |
| Root metadata | Component index, config, model card, license | <0.01 |
| Total | Pinned to one official revision | 26.56 |
Profile · dense
Correctness and parity baseline
Language model and RVQ decoder at published BF16. Acoustic components and the solver at published FP32.
Profile · q8
Lower-memory runtime
Only allowlisted MLX affine 8-bit linear layers. Every excluded module keeps its dense dtype.
Always FP32
Sampling logits, classifier-free guidance, top-k filtering, softmax, probability normalisation, flow integration, and waveform clamping accumulate in FP32 even when their inputs arrive from a lower-precision component. Precision is never inferred from a directory name, and weights are never quantized during inference.
Every converted checkpoint carries a manifest recording the official source revision, the mapping version, component files, tensor digests, and a per-module precision declaration. The loader builds dense or quantized module topology from that manifest before it loads a single array. Unknown mapping versions and implicit fallbacks are hard errors, not warnings.
Questions
The six that get asked first.
Does it need PyTorch or CUDA?
No. The only runtime dependency is MLX. PyTorch, Diffusers, Transformers, Accelerate, Torchaudio, Librosa, and huggingface_hub are excluded from the runtime entirely.
Can I generate music with it today?
Yes, through the Python API, with the alpha caveats stated plainly: dense components are validated and waveform execution runs end to end, but overall music quality, quantized quality, and long-form generation are still being brought to parity. There is no command-line interface.
What hardware does it need?
A Mac with Apple silicon. The checkpoint is 26.56 GiB and the autoregressive phase holds about 17.19 GiB at once, so a large-memory configuration is the realistic target. Phase-scoped residency means the peak is one phase, not the whole checkpoint.
Does installing it download weights?
No. Weights are never in the repository, the wheel, or the source distribution. Checkpoint paths are local and explicit, and the download is selective and resumable by design.
What sample rate comes out?
Today the output is native 44.1 kHz stereo PCM16. The reference 32 kHz serving profile is a separate explicit profile and is still in progress. The two are never silently conflated.
Is this affiliated with MiniMax?
No. This is an independent port, not affiliated with or endorsed by MiniMax. Source is MIT; the model weights are distributed separately under the MiniMax-Music3 Community License.