--- title: HeartMuLa-oss-3B-8bit canonical_url: "https://www.modelscope.cn/models/mlx-community/HeartMuLa-oss-3B-8bit" md_url: "https://www.modelscope.cn/models/mlx-community/HeartMuLa-oss-3B-8bit.md" repository: mlx-community/HeartMuLa-oss-3B-8bit 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: quantized parameters: 1.7B tensor_type: - BF16 - U32 library_name: - mlx - safetensors - pytorch frameworks: - pytorch language: - en - zh downloads: 4 stars: 4 tags: - mlx - swift - music-generation - heartmula - 8-bit --- # HeartMuLa-oss-3B-8bit > HeartMuLa-oss-3B-8bit - mlx-community 在 ModelScope 开源的模型。HeartMuLa-oss-3B-8bit (MLX) mlx-community/HeartMuLa-oss-3B-8bit 是 ModelScope 魔搭社区上的 1.7B 参数机器学习模型，采用 apache-2.0 许可，基于 HeartMuLa/HeartMuLa-oss-3B-happy-new-year 构建。 - **Repository**: mlx-community/HeartMuLa-oss-3B-8bit - **License**: apache-2.0 - **Parameters**: 1.7B - **Base model**: HeartMuLa/HeartMuLa-oss-3B-happy-new-year - **Tags**: mlx, swift, music-generation, heartmula, 8-bit - **Downloads**: 4 - **Stars**: 4 - **Last updated**: 2026-11-02 Source: https://www.modelscope.cn/models/mlx-community/HeartMuLa-oss-3B-8bit --- # HeartMuLa-oss-3B-8bit (MLX) The language model of [HeartMuLa-oss-3B](https://huggingface.co/HeartMuLa/HeartMuLa-oss-3B-happy-new-year), quantised to 8 bits 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 default tier:** with [HeartCodec-oss-fp16](https://huggingface.co/mlx-community/HeartCodec-oss-fp16) it runs on a 24 GB Mac at about 3× real time. The 3B global LM (Llama-3.2 shape: 28 layers × 3072) predicts codebook 0 at 12.5 Hz; a 300M local decoder predicts codebooks 1–7. The 217 Linear layers inside both transformers are 8-bit (MLX affine, group 64), pre-quantised, so nothing is quantised at load. Embeddings, heads and norms are bf16. | file | size | |---|---| | `model.safetensors` (723 tensors: 217 quantised Linears as weight / scales / biases, the rest bf16) | 4.94 GB | | `tokenizer.json` (the Llama-3.2 BPE vocabulary, as HeartMuLaGen ships it), `gen_config.json` | 9.1 MB | | `config.json` (with the `quantization` block and an `mlx_heartmula` section) | 1.1 KB | | `LICENSE` (Apache-2.0), `NOTICE` | — | ## Use This repo is the LM half. The engine package pairs it with a codec repo and fetches both. ```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() // first, before any model runs (TF32 off; see the fp32 codec's card) let engine = MLXServeEngine() await engine.useModelStore(ModelStore(root: modelsRoot)) let id = try await engine.register(HeartMuLaPackage.registration, configuration: HeartMuLaConfiguration(quant: .int8, codec: .fp16), // the defaults 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: "folk, acoustic guitar, female vocal", lyrics: "[verse]\n…\n\n[chorus]\n…", durationSeconds: 120, seed: 7), package: id) as! MusicResponse // song.audio: 48 kHz stereo WAV, peak ≤ −1 dBFS; song.truncated: true when the 120 s cap, not the song, ended it ``` The caption is the model's only style input, read as comma-separated tags. `durationSeconds` is a cap (1–240 s, default 120): most songs end on their own when the lyrics run out. Reference audio, edits, planning, a score, BPM/key anchors and a vocal language are refused; `guidanceScale` is ignored. With the 8-bit LM, expect more songs to run to the cap than with bf16 (see below); pick [HeartMuLa-oss-3B-bf16](https://huggingface.co/mlx-community/HeartMuLa-oss-3B-bf16) if that matters more than 3 GB of memory. | 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 The bf16 source bundle is bit-equal to the release's own tensors cast to bf16. The Swift LM matches upstream heartlib on PyTorch-MPS: argmax 130/130 positions and identical sampled codes from recorded noise at fp32. This bundle's quantised tensors are bit-equal to `MLX.quantized` of the bf16 weights. 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.