Agent skill · creative production · nousresearch
heartmula
HeartMuLa: Suno-like song generation from lyrics + tags.
Why this skill is useful
Provides specific installation steps and patches for using HeartMuLa, which are not commonly found in public documentation.
What it needs
Requires git, python, torch, torchtune installed locally. About 3k tokens when loaded. Last updated 2026-08-07. 226,679 stars on the source repository.
What this skill does
HeartMuLa - Open-Source Music Generation Overview HeartMuLa is a family of open-source music foundation models (Apache-2.0) that generates music conditioned on lyrics and tags, with multilingual support. Generates full songs from lyrics + tags. Comparable to Suno for open-source. Includes: HeartMuLa - Music language model (3B/7B) for generation from lyrics + tags HeartCodec - 12.5Hz music codec for high-fidelity audio reconstruction HeartTranscriptor - Whisper-based lyrics transcription HeartCLAP - Audio-text alignment model When to Use User wants to generate music/songs from text descriptions User wants an open-source Suno alternative User wants local/offline music generation User asks about HeartMuLa, heartlib, or AI music generation Hardware Requirements Minimum: 8GB VRAM with --lazyload true (loads/unloads models sequentially) Recommended: 16GB+ VRAM for comfortable single-GPU usage Multi-GPU: Use --muladevice cuda:0 --codecdevice cuda:1 to split across GPUs 3B model with lazyload peaks at ~6.2GB VRAM Installation Steps 1. Clone Repository 2. Create Virtual Environment (Python 3.10 required) 3. Fix Dependency Compatibility Issues IMPORTANT: As of Feb 2026, the pinned dependencies have conflicts with newer packages. Apply these fixes: 4. Patch Source Code (Required for transformers 5.x) Patch 1 - RoPE cache fix in src/heartlib/heartmula/modelingheartmula.py: In the setupcaches method of the HeartMuLa class, add RoPE reinitialization after the resetcaches try/except block and before the with device: block: Why: frompretrained creates model on meta device first; Llama3ScaledRoPE.ropeinit() skips cache building on meta tensors, then never rebuilds after weights are loaded to real device. Patch 2 - HeartCodec loading fix in src/heartlib/pipelines/musicgeneration.py: Add ignoremismatchedsizes=True to ALL HeartCodec.frompretrained() calls (there are 2: the eager load in init and the lazy load in the codec property). …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills nousresearch/heartmula