heartlib README

The project's README from github.com/HeartMuLa/heartlib. As one markdown file: README.md.

Demo 🎶  |  📑 Paper
HeartMuLa-oss-3B-happy-new-year 🤗  |  HeartMuLa-oss-3B-happy-new-year


HeartMuLa: A Family of Open Sourced Music Foundation Models

HeartMuLa is a family of open sourced music foundation models including:

  1. HeartMuLa: a music language model that generates music conditioned on lyrics and tags with multilingual support covering almost all languages.
  2. HeartCodec: a 12.5 hz music codec with high reconstruction fidelity;
  3. HeartTranscriptor: a whisper-based model specifically tuned for lyrics transcription; Check this page for its usage.
  4. HeartCLAP: an audio–text alignment model that establishes a unified embedding space for music descriptions and cross-modal retrieval.

Below shows the experiment result of our oss-3B version compared with other baselines.


🔥 Highlight

Our latest internal version of HeartMuLa-7B achieves comparable performance with Suno in terms of musicality, fidelity and controllability.

📰 News

Join on Discord! join discord


🧭 TODOs


🛠️ Local Deployment

⚙️ Environment Setup

We recommend using python=3.10 for local deployment.

Clone this repo and install locally.

git clone https://github.com/HeartMuLa/heartlib.git
cd heartlib
pip install -e .

Download our pretrained checkpoints from huggingface or modelscope using the following command:

# if you are using huggingface
hf download --local-dir './ckpt' 'HeartMuLa/HeartMuLaGen'
hf download --local-dir './ckpt/HeartMuLa-oss-3B' 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year'
hf download --local-dir './ckpt/HeartCodec-oss' HeartMuLa/HeartCodec-oss-20260123


# if you are using modelscope
modelscope download --model 'HeartMuLa/HeartMuLaGen' --local_dir './ckpt'
modelscope download --model 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year' --local_dir './ckpt/HeartMuLa-oss-3B'
modelscope download --model 'HeartMuLa/HeartCodec-oss-20260123' --local_dir './ckpt/HeartCodec-oss'

After downloading, the ./ckpt subfolder should structure like this:

./ckpt/
├── HeartCodec-oss/
├── HeartMuLa-oss-3B/
├── gen_config.json
└── tokenizer.json

▶️ Example Usage

To generate music, run:

python ./examples/run_music_generation.py --model_path=./ckpt --version="3B"

By default this command will generate a piece of music conditioned on lyrics and tags provided in ./assets folder. The output music will be saved at ./assets/output.mp3.

FAQs

  1. How to specify lyrics and tags?

    The model will load lyrics from the txt file --lyrics link to (by default ./assets/lyrics.txt). If you would like to use your own lyrics, just modify the content in ./assets/lyrics.txt. If you would like to save your lyrics to another path, e.g. my_awesome_lyrics.txt, remember to input arguments --lyrics my_awesome_lyrics.txt.

    For tags it's basically the same.

  2. CUDA out of memory?

    If you have multi-GPUs (e.g. 2 4090s), we recommend placing the params of HeartMuLa and HeartCodec separately on different devices. You can do it by typing --mula_device cuda:0 --codec_device cuda:1

    If you are running on a single GPU, use --lazy_load true so that modules will be loaded on demand and deleted once inference completed to save GPU memory.

All parameters:

[Intro]

[Verse]
The sun creeps in across the floor
I hear the traffic outside the door
The coffee pot begins to hiss
It is another morning just like this

[Prechorus]
The world keeps spinning round and round
Feet are planted on the ground
I find my rhythm in the sound

[Chorus]
Every day the light returns
Every day the fire burns
We keep on walking down this street
Moving to the same steady beat
It is the ordinary magic that we meet

[Verse]
The hours tick deeply into noon
Chasing shadows,chasing the moon
Work is done and the lights go low
Watching the city start to glow

[Bridge]
It is not always easy,not always bright
Sometimes we wrestle with the night
But we make it to the morning light

[Chorus]
Every day the light returns
Every day the fire burns
We keep on walking down this street
Moving to the same steady beat

[Outro]
Just another day
Every single day

Regarding tags, check this issue for reference. Our different tags are comma-separated without spaces as illustrated below:

piano,happy,wedding,synthesizer,romantic

⚖️ License

This repository is licensed under the Apache 2.0 License.


📚 Citation

@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 [email protected]

Welcome to join us through discord or Wechat group.

Scan the QR code on the left to join our Wechat group. If it expires, feel free to raise an issue to remind us of updating.

If the number of group members exceeds 200, joining the group via directly scanning the QR code is restricted by WeChat. In this case, scan our team member's QR code on the right and send a request writing HeartMuLa Group Invite. We will invite you into the group manually.

heartlib (HeartMuLa/heartlib)

Searching Database…

Что это такое?HeartMuLa — это семейство открытых музыкальных foundation-моделей для генерации музыки по тексту песни и тегам, вместе с которыми поставляются сопутствующие модели: кодек, модель транскрипции и модель аудио-текстового поиска.
Это одна модель или набор моделей?Семейство из четырёх: основная генератор музыки HeartMuLa плюс сопутствующие модели HeartCodec, HeartTranscriptor и HeartCLAP.
Как её запустить?В README нет команд установки — там ссылка на отдельную страницу использования, где объясняется, как запускать модели.
Что должно быть установлено, чтобы я мог сгенерировать песню?Основа — окружение Python, так как репозиторий написан на Python; в README список требований внутри не приведён, вместо этого указана страница использования.
Она правда такая же хорошая, как Suno?В README утверждается, что последняя внутренняя версия HeartMuLa-7B сравнима с Suno по музыкальности, качеству звука и управляемости; опубликованные результаты бенчмарков относятся к открытой версии oss-3B.
Тут есть приложение или API, или мне нужно встраивать это в свой пайплайн?Это репозиторий моделей для разработчиков и исследователей — вы запускаете модели в своём окружении; о приложении или хостинге ничего не упоминается.
А может ли она генерировать песни на моём языке?Да — HeartMuLa работает по тексту песни и тегам с многоязычной поддержкой почти всех языков, так что тексты не на английском входят в её возможности.
Чем на самом деле занимаются HeartCodec, HeartTranscriptor и HeartCLAP?HeartCodec — это кодек с частотой 12.5 Гц, восстанавливающий аудио с высокой точностью; HeartTranscriptor — модель на базе whisper, заточенная под распознавание текста песен; HeartCLAP объединяет музыку и текстовые описания в одном пространстве эмбеддингов для кросс-модального поиска.
То есть я могу скачать 7B или только модель поменьше?Опубликованные результаты касаются открытой версии oss-3B, а сравнимая с Suno HeartMuLa-7B описана как их последняя внутренняя версия — то есть открыто в репозитории доступна именно модель уровня 3B.
Creator
HeartMuLa
Size
10.2 MB
Stars
3.8K
Updated
CommitOct 08
Age
9mo
Commits · 90 Days