---
title: HeartMuLa-oss-3B-bf16
canonical_url: "https://www.modelscope.cn/models/mlx-community/HeartMuLa-oss-3B-bf16"
md_url: "https://www.modelscope.cn/models/mlx-community/HeartMuLa-oss-3B-bf16.md"
repository: mlx-community/HeartMuLa-oss-3B-bf16
last_updated: 2026-11-02
license: apache-2.0
model_type:
  - heartmula
architectures:
  - HeartMuLa
base_model:
  - HeartMuLa/HeartMuLa-oss-3B-happy-new-year
base_model_relation: finetune
parameters: 3.9B
tensor_type:
  - BF16
library_name:
  - mlx
  - safetensors
  - pytorch
frameworks:
  - pytorch
language:
  - en
  - zh
downloads: 4
stars: 0
tags:
  - mlx
  - swift
  - music-generation
  - heartmula
---

# HeartMuLa-oss-3B-bf16

> HeartMuLa-oss-3B-bf16 - mlx-community 在 ModelScope 开源的模型。HeartMuLa-oss-3B-bf16 (MLX)

mlx-community/HeartMuLa-oss-3B-bf16 是 ModelScope 魔搭社区上的 3.9B 参数机器学习模型，采用 apache-2.0 许可，基于 HeartMuLa/HeartMuLa-oss-3B-happy-new-year 构建。

- **Repository**: mlx-community/HeartMuLa-oss-3B-bf16
- **License**: apache-2.0
- **Parameters**: 3.9B
- **Base model**: HeartMuLa/HeartMuLa-oss-3B-happy-new-year
- **Tags**: mlx, swift, music-generation, heartmula
- **Downloads**: 4
- **Stars**: 0
- **Last updated**: 2026-11-02

Source: https://www.modelscope.cn/models/mlx-community/HeartMuLa-oss-3B-bf16

---

# HeartMuLa-oss-3B-bf16 (MLX)

The language model of [HeartMuLa-oss-3B](https://huggingface.co/HeartMuLa/HeartMuLa-oss-3B-happy-new-year) at bf16, for
[mlx-heartmula-swift](https://github.com/xocialize/mlx-heartmula-swift), a Swift-MLX port for Apple Silicon. HeartMuLa turns comma-separated style tags and lyrics with
section tags into a song with vocals (48 kHz stereo, up to 4 minutes). This is the full-precision LM tier. It is about as faithful to the lyrics as the default
[8-bit](https://huggingface.co/mlx-community/HeartMuLa-oss-3B-8bit) LM (PER 0.125 vs 0.132, inside the draw-to-draw noise) and
half as likely to run to the length cap, for 3 GB more memory.

The 3B global LM (Llama-3.2 shape: 28 layers × 3072, interleaved RoPE θ 500 000 with Llama-3 scaling) predicts codebook 0 at
12.5 Hz; a 300M local decoder (3 layers) predicts codebooks 1–7 through per-codebook heads. Every tensor is the release's
float32 value cast to bf16.

| file | size |
|---|---|
| `model-0000{1,2}-of-00002.safetensors` + index (289 tensors, bf16) | 7.88 GB |
| `tokenizer.json` (the Llama-3.2 BPE vocabulary, as HeartMuLaGen ships it), `gen_config.json` | 9.1 MB |
| `config.json` (with an `mlx_heartmula` section) | 0.7 KB |
| `LICENSE` (Apache-2.0), `NOTICE` | — |

## Use

Choose the bf16 LM in the configuration. The codec is a separate choice: the fp16 codec keeps the pair on a 32 GB Mac.

```swift
// Package.swift: .package(url: "https://github.com/xocialize/mlx-heartmula-swift", from: "0.1.1") → product "MLXHeartMuLa"
import MLXHeartMuLa
import MLXServeCore
import MLXToolKit

HeartMuLaPackage.configureProcess()
let engine = MLXServeEngine()
await engine.useModelStore(ModelStore(root: modelsRoot))
let id = try await engine.register(HeartMuLaPackage.registration,
                                   configuration: HeartMuLaConfiguration(quant: .bf16, codec: .fp16),
                                   id: "heartmula-oss-3b")
try await engine.prepare(.music, package: id)    // this repo + mlx-community/HeartCodec-oss-fp16
let song = try await engine.run(MusicRequest(caption: "piano pop, warm, female vocal", lyrics: "[verse]\n…",
                                             seed: 1001), package: id) as! MusicResponse
```

Without `durationSeconds` the cap is 120 s; the most it takes is 240 s. Reference audio, edits, planning, a score, anchors and
a vocal language are refused; `guidanceScale` is ignored.

| LM + codec | declared memory (resident + peak working set) | fits | render speed (M5 Max) |
|---|---|---|---|
| **8-bit + fp16 (the default)** | 8.5 + 5.5 GB | 24 GB Mac | 3.0× real time |
| bf16 + fp16 | 11.5 + 6.0 GB | 32 GB Mac | 2.5× |
| 8-bit + fp32 | 11.5 + 10.0 GB | 32 GB Mac | 2.3× |
| bf16 + fp32 | 14.5 + 10.0 GB | 48 GB Mac | 1.85× |

Memory is phys_footprint through MLXEngine at a 120 s song and a 240 s worst case; "fits" is the engine's 0.7 × RAM
admission rule. A 4-bit LM failed its lyric gate (PER 0.220) and is not published.

## Measured character

Read on the fleet's 12-song set (10 English, 2 Mandarin; two seed sets per tier) and in the operator's listening passes:

- **Lyrics are followed closely in English.** The lyric error rate (Whisper PER) is 0.125 with the bf16 LM and 0.132 with the
  8-bit LM (the PyTorch reference: 0.165).
- **Style tags steer it weakly.** CLAP style retrieval ranks its songs about 4.5 of 12 for their own tags, against about 2 for
  the other open music models measured. A higher CFG (3.0) does not help.
- **Voice gender drifts.** Most voices come out female whatever the tags ask: 1 of 6 male-voice prompts got a male voice.
- **Mandarin is weak and uneven.** The PyTorch reference read PER 0.457 in Mandarin (one verse lost) against 0.107 in
  English. The Swift bf16 takes did better on the two Mandarin songs, which is too few to call it fixed.
- **The 8-bit LM runs to the length cap twice as often as bf16** (10 of 24 songs against 5 of 24 at a 120 s cap). The lyrics are
  sung, then choruses repeat, and one song in 24 looped a single line until the cap.
- **Raw codec output can exceed full scale** (peaks to 1.37), so the Swift pipeline applies a single −1 dBFS limiter gain.

## Parity

Bit-equal to the release's tensors cast to bf16. At fp32 the Swift LM matches upstream heartlib on PyTorch-MPS (argmax 130/130
on two prompts, sampled codes identical from recorded noise); at bf16 its logits sit about 7e-3 relL2 from PyTorch's bf16
run, with the same sampled codes. Details: [MEASUREMENTS.md](https://github.com/xocialize/mlx-heartmula-swift/blob/main/MEASUREMENTS.md).

## Licence and attribution

Apache-2.0. HeartMuLa's generator repositories carry `license: apache-2.0` on their model cards but no LICENSE file. The grant
is the card statement plus heartlib's README of 2026-01-20, which moves "all related model weights" to Apache-2.0. This repo
ships heartlib's Apache-2.0 text as `LICENSE`, and a `NOTICE` with that grant chain and exactly what was changed. Not endorsed
by the HeartMuLa team or MuLa Labs. Paper: arXiv 2601.10547.