AEmotionStudio/heartmula-models

HeartMuLa · Æmotion Studio Mirror

Consolidated mirror of the HeartMuLa lyrics-to-music model family (upstream GitHub, paper, demo). Used by MAESTRO (Æ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	~15.8 GB	Recommended mula (fp32). Best lyrics controllability + overall quality.
heartmula-3b-rl/	HeartMuLa/HeartMuLa-RL-oss-3B-20260123	~15.8 GB	RL-refined mula (fp32). Stronger style/tag adherence.
heartmula-3b-base/	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	~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 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:

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.
• 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

@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 for the MAESTRO DAW. Refresh the mirror with python backend/scripts/mirror_heartmula_to_aemotion.py.