Refresh mirror README + LICENSE

LICENSE

@@ -0,0 +1,18 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 HeartMuLa Team (upstream weights, github.com/HeartMuLa/heartlib).
+   Mirror prepared by Æmotion Studio (https://huggingface.co/AEmotionStudio).
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -0,0 +1,142 @@
+---
+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/HeartCodec-oss
+- 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
+    ├── heartcodec-20260123/                     ← recommended codec
+    │   ├── HeartCodec-oss/
+    │   │   ├── config.json
+    │   │   ├── model-00001-of-00002.safetensors
+    │   │   ├── model-00002-of-00002.safetensors
+    │   │   └── model.safetensors.index.json
+    │   ├── README.md
+    │   └── LICENSE
+    └── heartcodec-base/                         ← original codec
+```
+
+## 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. 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. Stronger style/tag adherence. |
+| `heartmula-3b-base/` | [HeartMuLa/HeartMuLa-oss-3B](https://huggingface.co/HeartMuLa/HeartMuLa-oss-3B) | ~15.8 GB | Original mula release. Kept for reproducibility against the paper. |
+| `heartcodec-20260123/` | [HeartMuLa/HeartCodec-oss-20260123](https://huggingface.co/HeartMuLa/HeartCodec-oss-20260123) | ~6.7 GB | Recommended codec. Pair with any mula variant. |
+| `heartcodec-base/` | [HeartMuLa/HeartCodec-oss](https://huggingface.co/HeartMuLa/HeartCodec-oss) | ~6.7 GB | Original codec. Use only when reproducing older results. |
+
+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`.