HeartMuse is an intuitive web-based interface for creating high-quality AI-generated music completely locally on your machine. It combines the power of HeartMuLa (state-of-the-art open-source music generation model) with intelligent lyrics generation using local LLMs, giving you complete creative control without relying on cloud services.
# 1. Clone and install
git clone https://github.com/strnad/heartmuse.git
cd heartmuse
./install.sh # Linux/macOS
# or: install.bat # Windows
# 2. Run
./run.sh # Linux/macOS
# or: run.bat # WindowsOpen http://localhost:7860 and start creating!
That's it! The installer automatically creates a virtual environment, clones the HeartMuLa library, and installs all dependencies. AI models download automatically on first generation.
HeartMuse features a modular, field-by-field generation system that adapts to your creative workflow. Every field has its own "Generate/Enhance" checkbox, giving you granular control over what AI generates and what you write yourself.
| Field | What It Does | Generate/Enhance Checkbox |
|---|---|---|
| Description | Your creative brief for the song | AI can expand vague ideas into detailed descriptions |
| Title | Song name | AI suggests catchy, thematic titles |
| Lyrics | Full song text with sections | AI writes/extends verses, choruses, bridges |
| Tags | Music production tags for HeartMuLa | AI suggests genre, mood, instruments, tempo |
Each checkbox is independent - mix and match any combination:
- All four checked - AI generates everything from scratch
- Only lyrics checked - AI writes lyrics, you control title and tags
- Title + tags checked - You write lyrics, AI handles metadata
- Nothing checked - Use exactly what you entered, no AI changes
The magic happens when you provide partial content:
+----------------------------------+--------------------------------+
| You provide: | AI understands: |
+----------------------------------+--------------------------------+
| Description: "upbeat summer" | -> Uses as creative direction |
| Title: (empty) | -> Will generate |
| Lyrics: "Feel the sunshine" | -> Context for generation |
| Tags: (empty) | -> Will generate |
| |
| Checkboxes: [x] Title [x] Tags [ ] Lyrics |
| |
| Result: AI generates title and tags that match YOUR lyrics |
| and description. Your lyrics stay untouched. |
+-------------------------------------------------------------------+
Unchecked fields with values become context - AI reads them but won't modify them. This ensures coherent results that respect your creative input.
When extending existing lyrics, HeartMuse offers two levels of protection:
| Syntax | Protection Level | Use Case |
|---|---|---|
"exact text" |
100% locked - never changed, character-for-character | Your signature lines, hooks |
regular text |
Preserved - meaning kept, minor polish allowed | Draft verses you want improved |
Example:
[chorus]
"This exact line will never change!"
This line might get slight improvements
Result: The quoted line is untouchable. The unquoted line may be refined while keeping its meaning.
When "Generate/Enhance" is checked for lyrics that already have content:
- AI adds new sections (verses, bridge, outro)
- AI completes unfinished sections
- AI preserves everything you wrote
- AI never deletes your content
- AI never rewrites existing sections from scratch
Set your target song length, and AI adjusts lyrics accordingly:
| Duration | AI Behavior |
|---|---|
| Under 60s | Short and punchy - 1-2 sections |
| 60-120s | Standard structure - verse, chorus, verse |
| Over 120s | Extended - multiple verses, bridge, outro |
Leave all fields empty and click "Generate Text" - AI creates a completely original song concept:
- Invents a unique theme and story
- Writes complete lyrics with proper structure
- Suggests a fitting title
- Recommends appropriate musical tags
Each generation is different - use this for inspiration or when you want to be surprised!
Input: (everything empty, all checkboxes checked)
Output: Complete original song - title, lyrics, tags, ready for music generation
Input: Your complete lyrics in the Lyrics field
[ ] Description [ ] Lyrics [x] Title [x] Tags
Output: AI suggests a perfect title and musical tags that match YOUR lyrics
Input: Lyrics: "[chorus]\nDancing in the moonlight"
[x] Lyrics checked
Output: AI keeps your chorus and adds verses, bridge, outro around it
Input: Lyrics:
[chorus]
"We are the champions, my friend"
"And we'll keep on fighting till the end"
[verse]
(something about struggle and victory)
[x] Lyrics checked
Output: Quoted chorus: 100% unchanged
Verse placeholder: AI writes full lyrics about struggle and victory
Input: Description: "sad piano song"
[x] Description checked
Output: Description expanded to: "A melancholic piano ballad with introspective
lyrics about lost love, featuring gentle arpeggios and emotional vocal
delivery in a minor key"
Round 1: Generate title + lyrics from description
Round 2: Read lyrics, uncheck lyrics, add specific tags manually
Round 3: Generate music with your curated combination
- Ollama backend - everything runs on your computer, no data leaves your machine
- Or OpenAI API - for those who prefer cloud models
- Switch with one click - choose your backend based on the situation
Forget manual model downloads, path configuration, and dependency hell:
./install.sh -> Done!
HeartMuse handles everything:
- Creates an isolated Python environment
- Clones and installs HeartMuLa library
- Installs all dependencies automatically
- Downloads models on first use (from Hugging Face)
- Configures optimal settings for your hardware
Create a .env file (or copy .env.example):
# LLM Backend (Ollama = local, OpenAI = cloud)
LLM_BACKEND=Ollama
# For Ollama
OLLAMA_MODEL=glm-4.7-flash
# For OpenAI
# OPENAI_API_KEY=sk-...
# Music generation parameters
MUSIC_MAX_LENGTH_SEC=120# 1. Install Ollama from https://ollama.ai
# 2. Download a model
ollama pull glm-4.7-flash
# 3. Start (if not running automatically)
ollama serve+------------------+ +------------------+ +------------------+
| Your Input | --> | LLM (Ollama/ | --> | HeartMuLa |
| + checkboxes | | OpenAI) | | Music Gen |
+------------------+ | | | |
| Generates: | | Creates: |
| - Title | | - Audio file |
| - Lyrics | | - High-quality |
| - Tags | | music |
+------------------+ +------------------+
- NVIDIA GPU with 16GB+ VRAM (e.g., RTX 4080, RTX 3090, RTX 4090)
- Support for 12GB GPUs is planned
For GPUs with limited VRAM:
- Lazy loading (default) - reduces VRAM footprint
- "Unload Model" button - frees memory between generations
- Shorter song length - reduce
MUSIC_MAX_LENGTH_SEC
| Problem | Solution |
|---|---|
| "Out of memory" | Reduce song length, use "Unload Model" |
| Ollama not connecting | Verify ollama serve is running |
| Models not downloading | Check internet connection |
HeartMuse builds on the excellent work by the HeartMuLa team:
- HeartMuLa/heartlib - Music generation model
- HeartCodec - High-quality audio codec
Bitcoin: bc1qgsn45g02wran4lph5gsyqtk0k7t98zsg6qur0y
MIT License - see LICENSE
The HeartMuLa library has its own license - refer to the HeartMuLa repository.
Made with HeartMuLa | Developed with assistance from Claude Code
Create music with AI, own your creativity