К основному содержанию
скилл CX Codex

heartmula — скилл для Claude Code: что делает и как установить

Скилл для Claude Code запускает локальную генерацию песен из текста и тегов через HeartMuLa. Работает без облачного сервиса.

MIT 230 установок ★ 265 216 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add NousResearch/hermes-agent --skill heartmula -a claude-code
Открыть на GitHub

Что делает heartmula

heartmula описывает работу с HeartMuLa: модель создаёт полные песни по файлу с текстом и файлу с тегами. В набор входят HeartMuLa для генерации, HeartCodec для сборки аудио, HeartTranscriptor для транскрибации текста песен и HeartCLAP для сопоставления аудио с текстом. Результат сохраняется в MP3.

Скилл ведёт через установку heartlib, виртуальное окружение на Python 3.10, загрузку трёх чекпойнтов и запуск run_music_generation.py. В инструкции также есть обновления datasets и transformers, а для новых версий transformers нужны два патча исходников. Теги задаются через tags.txt, текст песни с секциями вроде [Verse] и [Chorus] — через lyrics.txt.

Для комфортной работы рекомендуется 16GB+ VRAM, а режим --lazy_load true позволяет запускать 3B-модель примерно с 8GB VRAM. На CPU генерация может занять 30-60+ минут, а на macOS Triton недоступен для GPU-ускорения. Это важно учесть до настройки окружения.

Какие задачи решает

  • создать песню из текста и тегов
  • подготовить heartlib и виртуальное окружение
  • загрузить чекпойнты HeartMuLa и HeartCodec
  • настроить генерацию через CUDA или CPU
  • сохранить результат в MP3

Примеры запросов агенту

  • Сгенерируй песню из lyrics.txt и tags.txt через HeartMuLa.
  • Подготовь heartlib, скачай нужные чекпойнты и запусти генерацию в ./assets/output.mp3.
  • Проверь, как включить --lazy_load true и использовать две видеокарты для HeartMuLa и HeartCodec.

Как установить heartmula

1Через Skills CLI (Vercel)

npx skills add NousResearch/hermes-agent --skill heartmula -a claude-code

2Вручную: положить файлы

~/.claude/skills/heartmula/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/heartmula/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о heartmula

Как установить heartmula в Claude Code?

Выполните npx skills add NousResearch/hermes-agent --skill heartmula -a claude-code, затем проверьте файл ~/.claude/skills/heartmula/SKILL.md.

Что делает heartmula?

Скилл помогает генерировать песни по lyrics и тегам через HeartMuLa, настраивать окружение, загружать модели и сохранять результат в MP3.

Какие требования нужны для работы heartmula?

Нужен Python 3.10 и установленный heartlib. Для запуска с GPU требуется NVIDIA с поддержкой CUDA в PyTorch; режим --lazy_load true рассчитан минимум на 8GB VRAM.

Исходный текст

SKILL.md · MIT
---
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]
metadata:
  hermes:
    tags: [music, audio, generation, ai, heartmula, heartcodec, lyrics, songs]
    related_skills: [songwriting-and-ai-music]
---

# 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:1` to split across GPUs
- 3B model with lazy_load peaks at ~6.2GB VRAM

## Installation Steps

### 1. Clone Repository
```bash
cd ~/  # or desired directory
git clone https://github.com/HeartMuLa/heartlib.git
cd heartlib
```

### 2. Create Virtual Environment (Python 3.10 required)
```bash
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:

```bash
# 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 transformers
```

### 4. 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:

```python
# 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
```bash
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.

## 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.1` includes CUDA 12.1 support out of the box
- `torchtune` may report version `0.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
```bash
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 true
```

### Input Formatting

**Tags** (comma-separated, no spaces):
```
piano,happy,wedding,synthesizer,romantic
```
or
```
rock,energetic,guitar,drums,male-vocal
```

**Lyrics** (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
1. **Do NOT use bf16 for HeartCodec** — degrades audio quality. Use fp32 (default).
2. **Tags may be ignored** — known issue (#90). Lyrics tend to dominate; experiment with tag ordering.
3. **Triton not available on macOS** — Linux/CUDA only for GPU acceleration.
4. **RTX 5080 incompatibility** reported in upstream issues.
5. 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

© Teknium (teknium1), Hermes Agent · MIT · NousResearch/hermes-agent

Похожие скиллы

Все скиллы по теме «ИИ и ML» →
elevenlabs-music-generation prime-skills Скилл elevenlabs-music-generation для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI запускает ElevenLabs Music через runcomfy CLI и возвращает стереодорожку 44.1 кГц. CX Codex +1 387 700установок ai-music prime-skills Скилл ai-music для Claude Code, Codex, Cursor и других агентов, который генерирует музыку через runcomfy CLI. Маршрутизирует между ElevenLabs Music ($0.0083/с) и ACE Step ($0.0002–0.0003/с) в зависимости от задачи. CX Codex +1 379 800установок faster-whisper ThePlasmak Скилл faster-whisper для Claude Code локально расшифровывает аудио и видео, определяет спикеров и создаёт субтитры без расходов на API. CX Codex +1 2 200установок music elevenlabs Генерирует треки, песни с вокалом и фоновую музыку через ElevenLabs Music API прямо из агента. CX Codex +1 15 600установок layer-audio layerai Скилл layer-audio настраивает промпты для генерации звуковых эффектов, музыки и озвучки через платформу Layer. Помогает избежать лишнего эха и каши в аудиодорожках. CX Codex +1 4 900установок videoagent-audio-studio wells Скилл videoagent-audio-studio маршрутизирует запросы на генерацию речи, музыки, шумовых эффектов и клонирование голоса к API ElevenLabs и fal.ai. Позволяет получать готовые аудиофайлы прямо в диалоге с ассистентом. CX Codex +1 4 000установок

Из того же набора61

Весь набор →
pdf Работает с PDF-файлами: создаёт, читает, объединяет, заполняет формы, извлекает текст и таблицы. CX Codex +1 283установок polymarket Получает из публичных REST API Polymarket данные о рынках, ценах, стаканах заявок и истории. Показывает, какие шансы рынок даёт событию. CX Codex +1 282установок inspecting-hermes-desktop-dom Скилл inspecting-hermes-desktop-dom читает DOM, CSS и консоль работающего Hermes Desktop через CDP. Пригодится, чтобы проверить, применился ли стиль и какое CSS-правило победило. CX Codex +1 263установок github Скилл github управляет задачами, пулл-реквестами, ревью и репозиториями через консольную утилиту gh. Помогает вести полный цикл от создания issue до слияния проверенного PR. CX Codex +1 245установок godmode Скилл godmode для Claude Code предлагает три способа обхода фильтров модели на уровне промпта: шаблоны, маскировку триггерных слов и опрос моделей через OpenRouter. CX Codex +1 214установок competitor-news-monitor Скилл competitor-news-monitor следит за заданными компаниями и присылает дайджест только по значимым событиям, со ссылками на первоисточники. CX Codex +1 204установок email-inbox-triage Скилл email-inbox-triage для Claude Code разбирает почту по приоритету и готовит черновики, ожидая одобрения перед отправкой. Сортирует потоки писем. CX Codex +1 178установок document-to-action-items Скилл document-to-action-items для Claude Code, Codex, Cursor и других агентов: достаёт из документов обязательства, дедлайны и задачи с привязкой к странице источника. Каждый пункт трассируется обратно до конкретного файла и раздела. CX Codex +1 173установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой