README.md

---
license: other
license_name: minimax-music3-community
license_link: https://huggingface.co/MiniMaxAI/MiniMax-Music3/blob/main/LICENSE
base_model:
  - MiniMaxAI/MiniMax-Music3
base_model_relation: quantized
pipeline_tag: text-to-audio
library_name: mlx
tags:
  - mlx
  - apple-silicon
  - music-generation
  - text-to-music
  - text-to-audio
  - int8
---

# MiniMax-Music3 MLX

Experimental native Apple Silicon MLX inference for [MiniMax-Music3](https://huggingface.co/MiniMaxAI/MiniMax-Music3). This repository runs the complete autoregressive, flow-DiT, and DAV synthesis path locally on macOS without CUDA or ComfyUI.

This is an independent community port, not an official MiniMax release. PocketAI did not train, fine-tune, or quantize the model weights; the packaged weights are unchanged from the pinned Comfy-Org repack identified below. No endorsement is implied.

## Example

The following one-minute rock-and-roll song was generated locally by this repository at 30 flow steps and seed `20260815`.

<audio controls src="https://huggingface.co/PocketAiHub/MiniMax-Music3-MLX/resolve/main/examples/rock-and-roll-60s.wav"></audio>

[Download the WAV](https://huggingface.co/PocketAiHub/MiniMax-Music3-MLX/resolve/main/examples/rock-and-roll-60s.wav) · [Generation parameters and signal checks](examples/rock-and-roll-60s.json)

## Requirements

- Apple Silicon Mac
- macOS 14 or newer
- Python 3.11–3.13 recommended
- 32 GB unified memory minimum; 48 GB or more recommended
- Approximately 12 GB disk space for this repository

The acceptance render was produced as a 44.1 kHz, 16-bit stereo WAV. A 60-second song at 30 steps takes several minutes; exact speed depends on the Mac and available memory.

## Install

```bash
hf download PocketAiHub/MiniMax-Music3-MLX \
  --local-dir MiniMax-Music3-MLX

cd MiniMax-Music3-MLX
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Generate a song

Create `lyrics.txt`:

```text
[Verse]
Neon on the dashboard, midnight in the street
Engine keeps on rumbling to a backbeat

[Chorus]
Turn it up, let the good times roll
Fire in the speakers, thunder in your soul
```

Then run:

```bash
python generate.py \
  --prompt "High-energy rock and roll, gritty male vocal, crunchy guitars, boogie piano, live drums, punchy bass, 148 BPM" \
  --lyrics-file lyrics.txt \
  --seconds 60 \
  --steps 30 \
  --seed 20260815 \
  --output song.wav
```

For an instrumental, pass `--lyrics "[Instrumental]"`. Supported duration is 10–300 seconds and supported flow-step count is 1–30.

## What is included

| Component | File | Format |
|---|---|---|
| Global + local autoregressive model | `text_encoders/minimax_music3_text_encoder_pruned_int8_convrot.safetensors` | INT8 tensorwise + ConvRot |
| Flow diffusion transformer | `diffusion_models/minimax_music3_dit_int8_convrot.safetensors` | INT8 tensorwise + ConvRot |
| DAV waveform decoder | `vae/minimax_music3_dav.safetensors` | FP32 |
| Native runtime | `minimax_mlx_model.py` | MLX |
| Standalone CLI | `generate.py` | Python |

The weights are unchanged copies of the pinned [Comfy-Org MiniMax-Music-3 repack](https://huggingface.co/Comfy-Org/MiniMax-Music-3/tree/6444666eb6edfb2c7fcab5f8b81da8b84b4b17b6). Exact sizes and SHA-256 checksums are recorded in [`model_manifest.json`](model_manifest.json).

## Implementation notes

The runtime mirrors the MiniMax-Music3 implementation in [ComfyUI commit `efd4e951`](https://github.com/Comfy-Org/ComfyUI/commit/efd4e951a00e85bd92e79f1d685427912b0dad5e), including:

- Qwen-style global autoregressive generation with a KV cache
- Seven-codebook local RVQ depth decoding
- Classifier-free guided flow matching
- Tensorwise INT8 ConvRot linear layers evaluated with MLX quantized matmul
- DAV stereo waveform decoding

Long DAV decodes are processed using overlap-cropped safe-size chunks. Direct multi-million-sample MLX Conv1d execution produced incorrect channel collapse during testing; the chunked path is bit-for-bit identical to direct decoding at safe tensor sizes. The runtime also rejects outputs exhibiting the diagnosed stereo-collapse signature.

## Validation

The included one-minute example passed these signal checks:

| Check | Result |
|---|---:|
| Duration | 59.9888 seconds |
| Channel RMS | 0.1478 / 0.1501 |
| Channel peak | 0.9740 / 0.9900 |
| Stereo correlation | 0.7086 |
| Collapsed one-second blocks | 0% |
| Clipped samples | 0 |

Run the lightweight tests with:

```bash
python -m unittest tests/test_minimax_mlx_model.py
```

## Limitations

- Apple Silicon macOS only; this port does not target Intel Macs, Linux, Windows, CUDA, or CPU-only execution.
- Inference is memory-intensive and currently batch-size one.
- The port uses the pinned Comfy-Org INT8 artifact set rather than the upstream full-precision Diffusers layout.
- Prompts and section tags provide generative control, not strict guarantees. Lyrics, tempo, instrumentation, and song structure may vary.
- Seeded output is deterministic for the pinned runtime and MLX versions but is not expected to match PyTorch/ComfyUI sample-for-sample because sampling backends use different random-number generators.

## License and attribution

Model weights, this derivative package, and use of generated outputs are subject to the included [MiniMax-Music3 Community License](LICENSE), including its acceptable-use policy and commercial-use terms. MiniMax-Music3 builds on Qwen3-8B and software components described in the upstream license.

Please review the license before downloading, redistributing, or deploying this repository. Users are responsible for ensuring they have the necessary rights to prompts, lyrics, reference material, and generated content.