🎵 Ethera (AI Music Composer)

Ethera is an elegant, open-source web interface for HeartMuLa, a state-of-the-art music generation model.

It provides a modern, "Glassmorphism" UI to compose high-fidelity music tracks with fine-grained control over duration, style, and voice modes.

🎥 Demo

Watch Demo Video

✨ Features

• Text-to-Music: Compose full songs from lyrics and style tags.
• Voice Control: Switch between Male, Female, and Instrumental modes.
• Duration Control: Generate clips from 1 second up to 4 minutes.
• Real-time Progress: "Composing..." modal with animated status.
• Local Privacy: Runs entirely on your own GPU.

---

🚀 Installation & Setup

Prerequisites

• OS: Windows or Linux
• GPU: NVIDIA RTX 30XX / 40XX series (8GB+ VRAM recommended)
• Python: 3.10 or higher
• CUDA: Toolkit 12.1+

1. Clone the Repository

git clone https://github.com/YOUR_USERNAME/Ethera.git
cd Ethera

2. Install Dependencies

Set up a Python virtual environment:

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux
python3 -m venv .venv
source .venv/bin/activate

Install the HeartMuLa library (Critical Step!) and dependencies:

# 1. Install HeartLib directly from source
pip install git+https://github.com/HeartMuLa/heartlib.git

# 2. Install Ethera backend dependencies
pip install -r backend/requirements.txt

3. Download Models (Required)

Ethera relies on the HeartMuLa-oss-3B model. You must download the weights manually as they are too large for GitHub.

Option A: Automated Download (Recommended) Run the following commands (requires huggingface-cli installed via pip):

# Create checkpoints directory
mkdir ckpt

# Download Model & Codec
hf download --local-dir './ckpt/HeartMuLa-oss-3B' 'HeartMuLa/HeartMuLa-oss-3B'
hf download --local-dir './ckpt/HeartCodec-oss' 'HeartMuLa/HeartCodec-oss'

Option B: Manual Download

1. Visit the HeartMuLa-oss-3B HuggingFace Page.
2. Download all files and place them in ckpt/HeartMuLa-oss-3B/.
3. Visit the HeartCodec-oss HuggingFace Page.
4. Download all files and place them in ckpt/HeartCodec-oss/.

Your folder structure should look like this:

Ethera/
├── ckpt/
│   ├── HeartMuLa-oss-3B/  (contains .safetensors/.bin)
│   └── HeartCodec-oss/    (contains .safetensors/.bin)
├── backend/
└── ...

4. Run Ethera

Start the backend server:

python -m uvicorn backend.fastapi_app:app --host 0.0.0.0 --port 8000

Then open your browser to: http://localhost:8000

---

❤️ Credits & Acknowledgements

Ethera is built upon the incredible work of the HeartMuLa research team.

• Model: HeartMuLa: A Family of Open Sourced Music Foundation Models
• Paper: arXiv:2601.10547
• Authors: Dongchao Yang et al.

Please cite their paper if you use this for research:

@misc{yang2026heartmulafamilyopensourced,
      title={HeartMuLa: A Family of Open Sourced Music Foundation Models}, 
      author={Dongchao Yang et al.},
      year={2026},
      eprint={2601.10547},
      archivePrefix={arXiv},
      primaryClass={cs.SD}
}