Improve model card: add arxiv metadata, description, and usage

README.md

@@ -1,46 +1,70 @@
 ---
-license: cc-by-nc-4.0
 language:
 - zh
 - en
 - ja
 - ko
 - es
+license: cc-by-nc-4.0
 pipeline_tag: text-to-audio
 tags:
 - music
 - art
+arxiv: 2601.10547
 ---
 
+# HeartMuLa: A Family of Open Sourced Music Foundation Models
 
-## Model Details
+[HeartMuLa](https://heartmula.github.io/) is a family of open-source Music Foundation Models designed to advance large-scale music understanding and generation across diverse tasks and modalities.
 
-### Model Description
+This repository contains the weights for **HeartMuLa-oss-3B**, an LLM-based song generation model capable of synthesizing high-fidelity music under rich, user-controllable conditions (e.g., textual style descriptions, lyrics, and reference audio).
 
-<!-- Provide a longer summary of what this model is. -->
+## Model Details
 
-- **Developed by:** [Ario Scale Global]
-- **License:** [CC-BY-NC 4.0]
+- **Developed by:** Ario Scale Global
+- **License:** CC-BY-NC 4.0
+- **Model Type:** LLM-based Music Generation
+- **Supported Languages:** English, Chinese, Japanese, Korean, Spanish, and more.
 
 ### Model Sources
 
-<!-- Provide the basic links for the model. -->
-
 - **Github Repo:** https://github.com/HeartMuLa/heartlib
-- **Paper:** https://arxiv.org/abs/2601.10547
+- **Paper:** [arXiv:2601.10547](https://arxiv.org/abs/2601.10547)
 - **Demo:** https://heartmula.github.io/
-- **HeartMuLa-oss-3B:** https://huggingface.co/HeartMuLa/HeartMuLa-oss-3B
-- **HeartCodec-oss:** https://huggingface.co/HeartMuLa/HeartCodec-oss
-- **HeartTranscriptor-oss:** https://huggingface.co/HeartMuLa/HeartTranscriptor-oss
 
+### HeartMuLa Family Checkpoints
+- **HeartMuLa-oss-3B:** [Base song generation model](https://huggingface.co/HeartMuLa/HeartMuLa-oss-3B)
+- **HeartCodec-oss:** [High-fidelity music codec tokenizer](https://huggingface.co/HeartMuLa/HeartCodec-oss)
+- **HeartTranscriptor-oss:** [Robust lyric recognition model](https://huggingface.co/HeartMuLa/HeartTranscriptor-oss)
 
 ## Get Started
 
-Check our github repo https://github.com/HeartMuLa/heartlib for a quickstart and local deployment of HeartMuLa.
+Check the official GitHub repository [HeartMuLa/heartlib](https://github.com/HeartMuLa/heartlib) for detailed setup and local deployment.
+
+### Installation
+
+```bash
+git clone https://github.com/HeartMuLa/heartlib.git
+cd heartlib
+pip install -e .
+```
+
+### Sample Usage
+
+To generate music conditioned on lyrics and style tags, run the following command after downloading the checkpoints:
+
+```bash
+python ./examples/run_music_generation.py --model_path=./ckpt --version="3B"
+```
+
+Parameters:
+- `--model_path`: Path to the pretrained model checkpoint.
+- `--lyrics`: Path to a text file containing lyrics (supports structure tags like `[Intro]`, `[Verse]`, `[Chorus]`).
+- `--tags`: Comma-separated style tags (e.g., `piano,happy,romantic`).
+- `--version`: The version of HeartMuLa (choose `3B`).
 
 ## Citation
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
 If you find HeartMuLa useful, please cite:
 
 ```bibtex
@@ -55,6 +79,5 @@ If you find HeartMuLa useful, please cite:
 }
 ```
 
-
 ## Contact
-If you are interested in HeartMuLa, feel free to reach us at heartmula.ai@gmail.com
+If you are interested in HeartMuLa, feel free to reach us at heartmula.ai@gmail.com