moonbox-dev/HeartMuLa-oss-3B-MLX

HeartMuLa-oss-3B MLX

MLX builds of HeartMuLa-oss-3B, made by Moonbox for Apple Silicon Macs. Each precision is a folder; keep a folder's files together. Only the parts listed below are converted: the rest of the pipeline comes from the original repository unless the section below says otherwise.

Files

The last column is how far each build is from the original PyTorch model on the same inputs (see the section below for what was measured).

Precision	File	Size	sha256	Checked against the original
bf16	bf16/HeartCodec-decoder.safetensors	3.15 GB	ad015e8df31a	KL 0.0016 nats (p95 0.0033), top-1 agreement 94.9 % (codebook 0: 95.3 %)
bf16	bf16/gen_config.json	0.1 kB	2fc578fc8d84	KL 0.0016 nats (p95 0.0033), top-1 agreement 94.9 % (codebook 0: 95.3 %)
bf16	bf16/lm.safetensors	7.88 GB	4568613019ea	KL 0.0016 nats (p95 0.0033), top-1 agreement 94.9 % (codebook 0: 95.3 %)
bf16	bf16/quant.json	0.1 kB	7e02c8099f9c	KL 0.0016 nats (p95 0.0033), top-1 agreement 94.9 % (codebook 0: 95.3 %)
bf16	bf16/tokenizer.json	9.1 MB	79e3e522635f	KL 0.0016 nats (p95 0.0033), top-1 agreement 94.9 % (codebook 0: 95.3 %)
8bit	8bit/HeartCodec-decoder.safetensors	3.15 GB	ad015e8df31a	KL 0.0020 nats (p95 0.0040), top-1 agreement 94.4 % (codebook 0: 96.3 %)
8bit	8bit/gen_config.json	0.1 kB	2fc578fc8d84	KL 0.0020 nats (p95 0.0040), top-1 agreement 94.4 % (codebook 0: 96.3 %)
8bit	8bit/lm.safetensors	4.19 GB	66bd3a93af3f	KL 0.0020 nats (p95 0.0040), top-1 agreement 94.4 % (codebook 0: 96.3 %)
8bit	8bit/quant.json	0.1 kB	5770813a16e0	KL 0.0020 nats (p95 0.0040), top-1 agreement 94.4 % (codebook 0: 96.3 %)
8bit	8bit/tokenizer.json	9.1 MB	79e3e522635f	KL 0.0020 nats (p95 0.0040), top-1 agreement 94.4 % (codebook 0: 96.3 %)
6bit	6bit/HeartCodec-decoder.safetensors	3.15 GB	ad015e8df31a	KL 0.0066 nats (p95 0.0129), top-1 agreement 90.9 % (codebook 0: 93.3 %)
6bit	6bit/gen_config.json	0.1 kB	2fc578fc8d84	KL 0.0066 nats (p95 0.0129), top-1 agreement 90.9 % (codebook 0: 93.3 %)
6bit	6bit/lm.safetensors	3.20 GB	e5ef6e6e3576	KL 0.0066 nats (p95 0.0129), top-1 agreement 90.9 % (codebook 0: 93.3 %)
6bit	6bit/quant.json	0.1 kB	a14bebd77402	KL 0.0066 nats (p95 0.0129), top-1 agreement 90.9 % (codebook 0: 93.3 %)
6bit	6bit/tokenizer.json	9.1 MB	79e3e522635f	KL 0.0066 nats (p95 0.0129), top-1 agreement 90.9 % (codebook 0: 93.3 %)
4bit	4bit/HeartCodec-decoder.safetensors	3.15 GB	ad015e8df31a	below threshold (experimental): KL 0.090 nats (p95 0.180), top-1 agreement 67.7 % (codebook 0: 85.0 %)
4bit	4bit/gen_config.json	0.1 kB	2fc578fc8d84	below threshold (experimental): KL 0.090 nats (p95 0.180), top-1 agreement 67.7 % (codebook 0: 85.0 %)
4bit	4bit/lm.safetensors	2.22 GB	6c8d05f4c635	below threshold (experimental): KL 0.090 nats (p95 0.180), top-1 agreement 67.7 % (codebook 0: 85.0 %)
4bit	4bit/quant.json	0.1 kB	403b9d70d8e8	below threshold (experimental): KL 0.090 nats (p95 0.180), top-1 agreement 67.7 % (codebook 0: 85.0 %)
4bit	4bit/tokenizer.json	9.1 MB	79e3e522635f	below threshold (experimental): KL 0.090 nats (p95 0.180), top-1 agreement 67.7 % (codebook 0: 85.0 %)

How to run

HeartMuLa-oss-3B (a 3B music language model: lyrics + style tags to song, with the HeartCodec audio codec), converted for the MLX port in Moonbox's HeartMuLa engine. Each folder holds:

File	What
lm.safetensors	the LM (backbone, depth decoder, codebook heads); MLX affine-quantized, group 64, in 8bit / 6bit / 4bit
quant.json	which quantization the folder holds
HeartCodec-decoder.safetensors	the HeartCodec decoder (fp16)
tokenizer.json, gen_config.json	from HeartMuLa/HeartMuLaGen

The layout is the one audio/heartmula in Moonbox reads; that runtime isn't part of this repository. No fp16 build: the engine runs the LM in bf16.

How they were checked. Sampled songs differ from run to run, so every build scores the same codes instead: the float32 model generates 12 s for 2 prompts (seed 0, CFG 1.5), then each build predicts every frame teacher-forced (codebook 0 from the backbone, codebooks 1-7 from the depth decoder fed the true earlier codes, CFG as in generation). Reported: KL(float32 || build) of the guided distributions and top-1 agreement with float32. Pass: mean KL <= 0.01 nats and agreement >= 90 %. The MLX port itself was checked against the official PyTorch pipeline when the engine was written.

Precision	Size	KL vs float32 (mean / p95)	Top-1 agreement (all / codebook 0)	Status
bf16/	11.0 GB	0.0016 / 0.0033 nats	94.9 % / 95.3 %	passes
8bit/	7.3 GB	0.0020 / 0.0040 nats	94.4 % / 96.3 %	passes
6bit/	6.4 GB	0.0066 / 0.0129 nats	90.9 % / 93.3 %	passes
4bit/	5.4 GB	0.090 / 0.180 nats	67.7 % / 85.0 %	below threshold, experimental

How these were made

From HeartMuLa-oss-3B at revision d12ac79c6b: the original weights loaded in MLX and stored as bf16 or fp16, or quantized with MLX's affine quantization (8bit, 6bit, 4bit, group size 64; layers MLX can't quantize, such as convolutions and norms, stay bf16). Every build was checked against the original before upload; the sha256 column above is what the files must hash to.

License

Apache-2.0. These files are a derivative of the original model and carry its license: it is copied in this repository, and it governs your use of these files. The original model card follows unchanged.

---

Original model card

Model Details

Model Description

• Developed by: [HeartMuLa Team]
• License: [Apache 2.0]

Model Sources

• Github Repo: https://github.com/HeartMuLa/heartlib
• Paper: https://arxiv.org/abs/2601.10547
• Demo: https://heartmula.github.io/
• HeartMuLa-oss-3B: https://huggingface.co/HeartMuLa/HeartMuLa-oss-3B
• HeartCodec-oss: https://huggingface.co/HeartMuLa/HeartCodec-oss
• HeartTranscriptor-oss: https://huggingface.co/HeartMuLa/HeartTranscriptor-oss

Get Started

Check our github repo https://github.com/HeartMuLa/heartlib for a quickstart and local deployment of HeartMuLa.

Citation

If you find HeartMuLa useful, please cite:

@misc{yang2026heartmulafamilyopensourced,
      title={HeartMuLa: A Family of Open Sourced Music Foundation Models}, 
      author={Dongchao Yang and Yuxin Xie and Yuguo Yin and Zheyu Wang and Xiaoyu Yi and Gongxi Zhu and Xiaolong Weng and Zihan Xiong and Yingzhe Ma and Dading Cong and Jingliang Liu and Zihang Huang and Jinghan Ru and Rongjie Huang and Haoran Wan and Peixu Wang and Kuoxi Yu and Helin Wang and Liming Liang and Xianwei Zhuang and Yuanyuan Wang and Haohan Guo and Junjie Cao and Zeqian Ju and Songxiang Liu and Yuewen Cao and Heming Weng and Yuexian Zou},
      year={2026},
      eprint={2601.10547},
      archivePrefix={arXiv},
      primaryClass={cs.SD},
      url={https://arxiv.org/abs/2601.10547}, 
}

Contact

If you are interested in HeartMuLa, feel free to reach us at heartmula.ai@gmail.com