Improve model card and add sample usage

README.md

@@ -1,48 +1,67 @@
 ---
-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
 ---
 
-# HeartMuLa
+# HeartMuLa: A Family of Open Sourced Music Foundation Models
 
+HeartMuLa is a family of open-source music foundation models designed to advance large-scale music understanding and generation across diverse tasks and modalities. It is 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).
+
+- **Project Page:** [https://heartmula.github.io/](https://heartmula.github.io/)
+- **Repository:** [https://github.com/HeartMuLa/heartlib](https://github.com/HeartMuLa/heartlib)
+- **Paper:** [HeartMuLa: A Family of Open Sourced Music Foundation Models](https://arxiv.org/abs/2601.10547)
+- **Demo:** [https://heartmula.github.io/](https://heartmula.github.io/)
 
 ## Model Details
 
-### Model Description
+The HeartMuLa framework consists of four major components:
+1. **HeartMuLa**: A music language model that generates music conditioned on lyrics and tags with multilingual support.
+2. **HeartCodec**: A low-frame-rate (12.5 Hz), high-fidelity music codec tokenizer that captures long-range musical structure.
+3. **HeartTranscriptor**: A robust lyric recognition model optimized for real-world music scenarios.
+4. **HeartCLAP**: An audio-text alignment model for music descriptions and cross-modal retrieval.
 
-<!-- Provide a longer summary of what this model is. -->
+## Installation
 
-- **Developed by:** [Ario Scale Global]
-- **License:** [CC-BY-NC 4.0]
+We recommend using `python=3.10` for local deployment. Clone the repository and install locally:
 
-### Model Sources
+```bash
+git clone https://github.com/HeartMuLa/heartlib.git
+cd heartlib
+pip install -e .
+```
 
-<!-- Provide the basic links for the model. -->
+## Sample Usage
 
-- **Github Repo:** https://github.com/HeartMuLa/heartlib
-- **Paper:** 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
+### Download Checkpoints
+First, download the pretrained checkpoints into a `./ckpt` folder as described in the [GitHub README](https://github.com/HeartMuLa/heartlib).
 
+### Inference
+To generate music conditioned on lyrics and tags, run the following command:
 
-## Get Started
+```bash
+python ./examples/run_music_generation.py --model_path=./ckpt --version="3B"
+```
+
+By default, this command generates a piece of music based on the lyrics and tags provided in the `./assets` folder. The output will be saved as `./assets/output.mp3`.
 
-Check our github repo https://github.com/HeartMuLa/heartlib for a quickstart and local deployment of HeartMuLa.
+**Key Parameters:**
+- `--model_path`: Path to the pretrained model checkpoint.
+- `--lyrics`: Path to the lyrics file (e.g., `./assets/lyrics.txt`).
+- `--tags`: Path to the tags file (e.g., `./assets/tags.txt`).
+- `--save_path`: Output audio file path.
+- `--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
@@ -57,6 +76,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