Heartmula
RedWoodOG/Hermes-Desktop
Set up and run HeartMuLa, the open-source music generation model family (Suno-like).
HeartMuLa: Suno-like song generation from lyrics + tags. An agent skill from Luciole-Studio/Misaka-Agent.
Install Heartmula
$ npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install Luciole-Studio/Misaka-Agent heartmula --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/Luciole-Studio/Misaka-Agent.git skills-src && mkdir -p .claude/skills && cp -r skills-src/misaka/core/skills/assets/optional/creative/heartmula .claude/skills/heartmula && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "heartmula" agent skill from https://github.com/Luciole-Studio/Misaka-Agent/tree/main/misaka/core/skills/assets/optional/creative/heartmula into .claude/skills/heartmula/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "heartmula", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/Luciole-Studio/Misaka-Agent/tree/main/misaka/core/skills/assets/optional/creative/heartmulaType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install Luciole-Studio/Misaka-Agent heartmula --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Luciole-Studio/Misaka-Agent.git skills-src && mkdir -p .agents/skills && cp -r skills-src/misaka/core/skills/assets/optional/creative/heartmula .agents/skills/heartmula && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "heartmula" agent skill from https://github.com/Luciole-Studio/Misaka-Agent/tree/main/misaka/core/skills/assets/optional/creative/heartmula into .agents/skills/heartmula/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "heartmula", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install Luciole-Studio/Misaka-Agent heartmula --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Luciole-Studio/Misaka-Agent.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/misaka/core/skills/assets/optional/creative/heartmula .cursor/skills/heartmula && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "heartmula" agent skill from https://github.com/Luciole-Studio/Misaka-Agent/tree/main/misaka/core/skills/assets/optional/creative/heartmula into .cursor/skills/heartmula/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "heartmula", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/Luciole-Studio/Misaka-Agent.git --path misaka/core/skills/assets/optional/creative/heartmula--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install Luciole-Studio/Misaka-Agent heartmula --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Luciole-Studio/Misaka-Agent.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/misaka/core/skills/assets/optional/creative/heartmula .gemini/skills/heartmula && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "heartmula" agent skill from https://github.com/Luciole-Studio/Misaka-Agent/tree/main/misaka/core/skills/assets/optional/creative/heartmula into .gemini/skills/heartmula/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "heartmula", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install Luciole-Studio/Misaka-Agent heartmulaInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/Luciole-Studio/Misaka-Agent.git skills-src && mkdir -p .github/skills && cp -r skills-src/misaka/core/skills/assets/optional/creative/heartmula .github/skills/heartmula && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "heartmula" agent skill from https://github.com/Luciole-Studio/Misaka-Agent/tree/main/misaka/core/skills/assets/optional/creative/heartmula into .github/skills/heartmula/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "heartmula", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install Luciole-Studio/Misaka-Agent heartmula --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/Luciole-Studio/Misaka-Agent.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/misaka/core/skills/assets/optional/creative/heartmula .opencode/skills/heartmula && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "heartmula" agent skill from https://github.com/Luciole-Studio/Misaka-Agent/tree/main/misaka/core/skills/assets/optional/creative/heartmula into .opencode/skills/heartmula/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "heartmula", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
heartmula- GitHub stars
- 171
- Used in
- 2 other repos
- Token cost
- ~1.6k tokens
- SKILL.md length
- 592 words
- Files
- 1
- Skills in repo
- 77
- Repo updated
- First seen
- Licence
- MIT
At a glance
HeartMuLa: Suno-like song generation from lyrics + tags. An agent skill from Luciole-Studio/Misaka-Agent.
- Works in 5 steps: Clone Repository → Create Virtual Environment (Python 3.10… → Fix Dependency Compatibility Issues → …
- Tasks that involve Music and audio generation
- SKILL.md covers Overview, When to Use, Hardware Requirements and Installation Steps, plus 4 more sections
- Calls uv, hf and git; reaches github.com
What it does
Heartmula is an agent skill from Luciole-Studio/Misaka-Agent. HeartMuLa: Suno-like song generation from lyrics + tags.
Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Media & Creative, covering Music and audio generation. It works with Suno and CUDA. The repository describes itself as: A multi-agent research system for the humanities and social sciences. The licence is MIT.
When your agent uses it
- Tasks that involve Music and audio generation
Example prompts
- “/heartmula”
Requirements
- Python 3
Workflow steps
5 steps, taken from the step headings in SKILL.md.
What it can do on your machine
Read from SKILL.md and the folder at commit 3bcf7a3. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
uvhfgitpython
From the folder's file list and the shell code blocks in SKILL.md.
Network
Hosts in commands or code, which the agent is likely to contact:
github.com
Also links to:
heartmula.github.iohuggingface.coarxiv.org
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Heartmula loads about 1.6k tokens when it runs. Until then it costs about 17 tokens; SKILL.md has 592 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from Luciole-Studio/Misaka-Agent at commit 3bcf7a3, republished under its MIT licence (© Luciole-Studio). 592 words, ~1,625 tokens.
Download SKILL.mdSave it as
.claude/skills/heartmula/SKILL.md (or your agent's skills folder).- name
- heartmula
- description
- HeartMuLa: Suno-like song generation from lyrics + tags.
- version
- 1.0.0
- author
- Teknium (teknium1), Hermes Agent
- license
- MIT
- platforms
- linux, macos, windows
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
--lazy_load true(loads/unloads models sequentially) - Recommended: 16GB+ VRAM for comfortable single-GPU usage
- Multi-GPU: Use
--mula_device cuda:0 --codec_device cuda:1to split across GPUs - 3B model with lazy_load peaks at ~6.2GB VRAM
Installation Steps
1. Clone Repository
cd ~/ # or desired directory
git clone https://github.com/HeartMuLa/heartlib.git
cd heartlib2. Create Virtual Environment (Python 3.10 required)
uv venv --python 3.10 .venv
. .venv/bin/activate
uv pip install -e .3. Fix Dependency Compatibility Issues
IMPORTANT: As of Feb 2026, the pinned dependencies have conflicts with newer packages. Apply these fixes:
# Upgrade datasets (old version incompatible with current pyarrow)
uv pip install --upgrade datasets
# Upgrade transformers (needed for huggingface-hub 1.x compatibility)
uv pip install --upgrade transformers4. Patch Source Code (Required for transformers 5.x)
Patch 1 - RoPE cache fix in src/heartlib/heartmula/modeling_heartmula.py:
In the setup_caches method of the HeartMuLa class, add RoPE reinitialization after the reset_caches try/except block and before the with device: block:
# Re-initialize RoPE caches that were skipped during meta-device loading
from torchtune.models.llama3_1._position_embeddings import Llama3ScaledRoPE
for module in self.modules():
if isinstance(module, Llama3ScaledRoPE) and not module.is_cache_built:
module.rope_init()
module.to(device)Why: from_pretrained creates model on meta device first; Llama3ScaledRoPE.rope_init() 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/music_generation.py:
Add ignore_mismatched_sizes=True to ALL HeartCodec.from_pretrained() calls (there are 2: the eager load in __init__ and the lazy load in the codec property).
Why: VQ codebook initted buffers have shape [1] in checkpoint vs [] in model. Same data, just scalar vs 0-d tensor. Safe to ignore.
5. Download Model Checkpoints
cd heartlib # project root
hf download --local-dir './ckpt' 'HeartMuLa/HeartMuLaGen'
hf download --local-dir './ckpt/HeartMuLa-oss-3B' 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year'
hf download --local-dir './ckpt/HeartCodec-oss' 'HeartMuLa/HeartCodec-oss-20260123'All 3 can be downloaded in parallel. Total size is several GB.
Show full SKILL.md (298 more words)Show less
GPU / CUDA
HeartMuLa uses CUDA by default (--mula_device cuda --codec_device cuda). No extra setup needed if the user has an NVIDIA GPU with PyTorch CUDA support installed.
- The installed
torch==2.4.1includes CUDA 12.1 support out of the box torchtunemay report version0.4.0+cpu— this is just package metadata, it still uses CUDA via PyTorch- To verify GPU is being used, look for "CUDA memory" lines in the output (e.g. "CUDA memory before unloading: 6.20 GB")
- No GPU? You can run on CPU with
--mula_device cpu --codec_device cpu, but expect generation to be extremely slow (potentially 30-60+ minutes for a single song vs ~4 minutes on GPU). CPU mode also requires significant RAM (~12GB+ free). If the user has no NVIDIA GPU, recommend using a cloud GPU service (Google Colab free tier with T4, Lambda Labs, etc.) or the online demo at https://heartmula.github.io/ instead.
Usage
Basic Generation
cd heartlib
. .venv/bin/activate
python ./examples/run_music_generation.py \
--model_path=./ckpt \
--version="3B" \
--lyrics="./assets/lyrics.txt" \
--tags="./assets/tags.txt" \
--save_path="./assets/output.mp3" \
--lazy_load trueInput Formatting
Tags (comma-separated, no spaces):
piano,happy,wedding,synthesizer,romanticor
rock,energetic,guitar,drums,male-vocalLyrics (use bracketed structural tags):
[Intro]
[Verse]
Your lyrics here...
[Chorus]
Chorus lyrics...
[Bridge]
Bridge lyrics...
[Outro]Key Parameters
| Parameter | Default | Description |
|---|---|---|
--max_audio_length_ms | 240000 | Max length in ms (240s = 4 min) |
--topk | 50 | Top-k sampling |
--temperature | 1.0 | Sampling temperature |
--cfg_scale | 1.5 | Classifier-free guidance scale |
--lazy_load | false | Load/unload models on demand (saves VRAM) |
--mula_dtype | bfloat16 | Dtype for HeartMuLa (bf16 recommended) |
--codec_dtype | float32 | Dtype for HeartCodec (fp32 recommended for quality) |
Performance
- RTF (Real-Time Factor) ≈ 1.0 — a 4-minute song takes ~4 minutes to generate
- Output: MP3, 48kHz stereo, 128kbps
Pitfalls
- Do NOT use bf16 for HeartCodec — degrades audio quality. Use fp32 (default).
- Tags may be ignored — known issue (#90). Lyrics tend to dominate; experiment with tag ordering.
- Triton not available on macOS — Linux/CUDA only for GPU acceleration.
- RTX 5080 incompatibility reported in upstream issues.
- The dependency pin conflicts require the manual upgrades and patches described above.
Links
- Repo: https://github.com/HeartMuLa/heartlib
- Models: https://huggingface.co/HeartMuLa
- Paper: https://arxiv.org/abs/2601.10547
- License: Apache-2.0
© Luciole-Studio, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in misaka/core/skills/assets/optional/creative/heartmula of Luciole-Studio/Misaka-Agent.
Open the folder on GitHubat commit 3bcf7a3
Used in 2 other repositories
We found 2 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 2 other GitHub owners. This page covers the copy in Luciole-Studio/Misaka-Agent, which our catalogue first saw on October 7, 2026.
Compare with similar skills
Heartmula next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Heartmula this skillLuciole-Studio/Misaka-Agent | 171 | 2 repos | ~1.6k | Automated safety check: Pass | MIT | |
| HeartmulaRedWoodOG/Hermes-Desktop | 177 | 2 repos | ~1.6k | Automated safety check: Pass | None | |
| AI Music And Soundsocial-media-skills/skills | 134 | — | ~1.9k | Automated safety check: Pass | MIT | |
| Prismer Songwriting And AI MusicPrismer-AI/PrismerCloud | 1.6k | 6 repos | ~2.9k | Automated safety check: Pass | MIT | |
| Audio Jinglesanqiufong/slides-from-anything | 132 | 1 repos | ~1.1k | Automated safety check: Pass | Apache-2.0 | |
| AudioCraft Audio GenerationOrchestra-Research/AI-Research-SKILLs | 13k | 8 repos | ~3.9k | Automated safety check: Pass | MIT |
Similar skills
AI Music And Sound
social-media-skills/skills
The AI music + sound-design skill for social -- original/licensed audio beds and sound design for Reels/TikToks/Shorts/videos.
Prismer Songwriting And AI Music
Prismer-AI/PrismerCloud
Songwriting craft and Suno AI music prompts. An agent skill from Prismer-AI/PrismerCloud.
Audio Jingle
sanqiufong/slides-from-anything
Audio generation skill — jingles, beds, voiceover, and sound effects.
AudioCraft Audio Generation
Orchestra-Research/AI-Research-SKILLs
Generates music from text descriptions with MusicGen and sound effects with AudioGen, using Meta's AudioCraft PyTorch library with melody and style conditioning.
Add Tts Model
vllm-project/vllm-omni
Integrate a new text-to-speech model into vLLM-Omni from HuggingFace reference implementation through production-ready serving with streaming and CUDA graph acceleration.
More from Luciole-Studio/Misaka-Agent
All 77 skills in this repoKanban Video Orchestrator
Luciole-Studio/Misaka-Agent
Plan and run multi-agent video production pipelines. An agent skill from Luciole-Studio/Misaka-Agent.
Ast Grep
Luciole-Studio/Misaka-Agent
AST-aware structural code search and rewrite via ast-grep. An agent skill from Luciole-Studio/Misaka-Agent.
Drug Discovery
Luciole-Studio/Misaka-Agent
Drug discovery: ChEMBL search, drug-likeness, interactions. An agent skill from Luciole-Studio/Misaka-Agent.
Fitness Nutrition
Luciole-Studio/Misaka-Agent
Workout planning, macros, and body metrics via wger/USDA. An agent skill from Luciole-Studio/Misaka-Agent.
Hyperframes
Luciole-Studio/Misaka-Agent
Render MP4/WebM videos from HTML compositions. An agent skill from Luciole-Studio/Misaka-Agent.
Osint Investigation
Luciole-Studio/Misaka-Agent
Follow the money via public records and sanctions data. An agent skill from Luciole-Studio/Misaka-Agent.
Related
Categories
Questions about Heartmula
What does Heartmula do?
HeartMuLa: Suno-like song generation from lyrics + tags. An agent skill from Luciole-Studio/Misaka-Agent. Heartmula is an agent skill from Luciole-Studio/Misaka-Agent. HeartMuLa: Suno-like song generation from lyrics + tags.
When should I use Heartmula?
Heartmula fits situations like: tasks that involve Music and audio generation.
How do I install Heartmula in Claude Code?
Run `npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a claude-code`. Or copy the skill folder (misaka/core/skills/assets/optional/creative/heartmula in Luciole-Studio/Misaka-Agent) into .claude/skills/heartmula in your project. Claude Code loads it when a task matches its description.
How do I install Heartmula in Codex?
Run `npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a codex`. Or copy the skill folder (misaka/core/skills/assets/optional/creative/heartmula in Luciole-Studio/Misaka-Agent) into .agents/skills/heartmula in your project. Codex loads it when a task matches its description.
Can I use Heartmula in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Luciole-Studio/Misaka-Agent --skill heartmula -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/heartmula, .gemini/skills/heartmula, .github/skills/heartmula and .opencode/skills/heartmula in your project.
What does Heartmula need to run?
Going by SKILL.md and its folder, Heartmula needs the command-line tools its instructions call (uv, hf, git and python). Our summary lists: Python 3.
Does Heartmula access the network?
SKILL.md names 4 domains. In commands or code: github.com; the agent is likely to contact it when it follows the instructions. As links in the text: heartmula.github.io, huggingface.co and arxiv.org. This is read from the text; nothing was executed.
Is Heartmula safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Heartmula use?
Heartmula is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Heartmula use?
About 1.6k tokens (SKILL.md is roughly 6.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Heartmula?
Skills that share tags, products or a category with Heartmula: Heartmula (RedWoodOG/Hermes-Desktop, 177 stars), AI Music And Sound (social-media-skills/skills, 134 stars), Prismer Songwriting And AI Music (Prismer-AI/PrismerCloud, 1.6k stars) and Audio Jingle (sanqiufong/slides-from-anything, 132 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Heartmula?
Luciole-Studio (a GitHub organization) maintains it in Luciole-Studio/Misaka-Agent, which has 171 GitHub stars. The repository holds 77 skills in this directory. The repository was last updated on October 8, 2026.
Source: Luciole-Studio/Misaka-Agent on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.