README.md

---
license: apache-2.0
language:
- en
- zh
- ja
- ko
- es
pipeline_tag: text-to-audio
library_name: heartlib
tags:
- music
- lyrics-to-music
- heartmula
- heartcodec
- mirror
base_model:
- HeartMuLa/HeartMuLa-oss-3B-happy-new-year
- HeartMuLa/HeartMuLa-RL-oss-3B-20260123
- HeartMuLa/HeartMuLa-oss-3B
- HeartMuLa/HeartCodec-oss-20260123
- HeartMuLa/HeartMuLaGen
---

# HeartMuLa · Æmotion Studio Mirror

Consolidated mirror of the **HeartMuLa** lyrics-to-music model family
([upstream GitHub](https://github.com/HeartMuLa/heartlib),
[paper](https://arxiv.org/abs/2601.10547),
[demo](https://heartmula.github.io/)). Used by
[MAESTRO](https://github.com/AEmotionStudio) (Æmotion Studio's open-source DAW)
for one-click downloads of any (mula, codec) pair from a single repo.

Last refresh: **2026-05-10**.

## Why a mirror?

Upstream distributes the model in three separate repos (a tokenizer/config
repo plus per-variant weight repos). MAESTRO's runner expects all of them
assembled on disk in heartlib's canonical `pretrained_path` layout, and
each user otherwise has to clone three repos and stitch them together by
hand. This mirror does the stitching once: each `checkpoints/<variant>/`
subfolder is **self-contained** — drop it in as `pretrained_path` and
`HeartMuLaGenPipeline.from_pretrained(...)` Just Works.

## Layout

```
AEmotionStudio/heartmula-models/
├── README.md                                    ← this file
├── LICENSE                                      ← Apache-2.0
└── checkpoints/
    ├── heartmula-3b-happy-new-year/             ← recommended mula
    │   ├── HeartMuLa-oss-3B/
    │   │   ├── config.json
    │   │   ├── model-00001-of-00004.safetensors
    │   │   ├── ...
    │   │   └── model.safetensors.index.json
    │   ├── tokenizer.json
    │   ├── gen_config.json
    │   ├── README.md                            ← upstream mula card
    │   └── LICENSE
    ├── heartmula-3b-rl/                         ← RL-refined mula
    ├── heartmula-3b-base/                       ← original mula
    ├── heartmula-3b-happy-new-year-bf16/        ← pre-converted bf16
    ├── heartmula-3b-rl-bf16/                    ← pre-converted bf16
    ├── heartmula-3b-base-bf16/                  ← pre-converted bf16
    └── heartcodec-20260123/                     ← codec
        ├── HeartCodec-oss/
        │   ├── config.json
        │   ├── model-00001-of-00002.safetensors
        │   ├── model-00002-of-00002.safetensors
        │   └── model.safetensors.index.json
        ├── README.md
        └── LICENSE
```

## Variants

| Subfolder | Source | Size | Description |
|---|---|---|---|
| `heartmula-3b-happy-new-year/` | [HeartMuLa/HeartMuLa-oss-3B-happy-new-year](https://huggingface.co/HeartMuLa/HeartMuLa-oss-3B-happy-new-year) | ~15.8 GB | Recommended mula (fp32). Best lyrics controllability + overall quality. |
| `heartmula-3b-rl/` | [HeartMuLa/HeartMuLa-RL-oss-3B-20260123](https://huggingface.co/HeartMuLa/HeartMuLa-RL-oss-3B-20260123) | ~15.8 GB | RL-refined mula (fp32). Stronger style/tag adherence. |
| `heartmula-3b-base/` | [HeartMuLa/HeartMuLa-oss-3B](https://huggingface.co/HeartMuLa/HeartMuLa-oss-3B) | ~15.8 GB | Original mula release (fp32). Kept for reproducibility against the paper. |
| `heartmula-3b-happy-new-year-bf16/` | (re-cast from fp32) | ~8 GB | Pre-converted bf16 of the recommended mula. Same runtime quality as the fp32 mirror — heartlib already loads at bf16 dtype either way. Half the download. |
| `heartmula-3b-rl-bf16/` | (re-cast from fp32) | ~8 GB | Pre-converted bf16 of the RL mula. |
| `heartmula-3b-base-bf16/` | (re-cast from fp32) | ~8 GB | Pre-converted bf16 of the base mula. |
| `heartcodec-20260123/` | [HeartMuLa/HeartCodec-oss-20260123](https://huggingface.co/HeartMuLa/HeartCodec-oss-20260123) | ~6.7 GB | Codec (fp32). Pairs with any mula variant. Heartlib explicitly warns against lower-precision codec output. |

Shared `tokenizer.json` (9 MB) + `gen_config.json` (~100 B) come from
[HeartMuLa/HeartMuLaGen](https://huggingface.co/HeartMuLa/HeartMuLaGen)
and are duplicated into every mula variant subfolder so each is
self-contained — codec subfolders don't need them.

## Usage

**Direct (heartlib)** — clone any one mula + one codec into a single
directory and pass that as `pretrained_path`:

```bash
hf download \
    --repo-id AEmotionStudio/heartmula-models \
    --include "checkpoints/heartmula-3b-happy-new-year/**" \
    --local-dir ./ckpt-mula

hf download \
    --repo-id AEmotionStudio/heartmula-models \
    --include "checkpoints/heartcodec-20260123/**" \
    --local-dir ./ckpt-codec

# Then merge the two into one pretrained_path before calling
# HeartMuLaGenPipeline.from_pretrained — see heartlib README.
```

**MAESTRO** — open the AI Workstation, switch to **Create**, click the
HeartMuLa card, then download the (mula, codec) pair the panel
recommends. The runner synthesizes the merged `pretrained_path`
automatically and routes it to heartlib.

## License

- **Code (heartlib):** Apache-2.0 — [github.com/HeartMuLa/heartlib](https://github.com/HeartMuLa/heartlib).
- **Weights:** Apache-2.0 — verified against each upstream's model card metadata.
- **This mirror:** redistributed under Apache-2.0 with attribution.

See `LICENSE` at the repo root + each variant's `LICENSE` for the full text.

## Citation

```bibtex
@misc{yang2026heartmulafamilyopensourced,
      title={HeartMuLa: A Family of Open Sourced Music Foundation Models},
      author={Dongchao Yang and others},
      year={2026},
      eprint={2601.10547},
      archivePrefix={arXiv},
      primaryClass={cs.SD}
}
```

## Maintainer

Mirror prepared by [Æmotion Studio](https://huggingface.co/AEmotionStudio)
for the [MAESTRO](https://github.com/AEmotionStudio) DAW. Refresh the
mirror with `python backend/scripts/mirror_heartmula_to_aemotion.py`.