Heartmula

HeartMuLa: генерация песен в духе Suno из текста и тегов.

Метаданные навыка

Справочник: полный SKILL.md

HeartMuLa — генерация музыки с открытым исходным кодом

Обзор

HeartMuLa — семейство открытых базовых моделей для музыки (Apache-2.0), генерирующих полные песни по тексту и тегам с поддержкой нескольких языков. По возможностям сопоставима с Suno среди открытых решений. В состав входят:

• HeartMuLa — музыкальная языковая модель (3B/7B) для генерации по тексту и тегам
• HeartCodec — музыкальный кодек на 12.5 Гц для высококачественной реконструкции звука
• HeartTranscriptor — транскрипция текста песен на базе Whisper
• HeartCLAP — модель выравнивания аудио и текста

Когда использовать

• Пользователь хочет сгенерировать музыку или песни по текстовому описанию
• Пользователю нужна открытая замена Suno
• Пользователю нужна локальная или офлайн-генерация музыки
• Пользователь спрашивает про HeartMuLa, heartlib или генерацию музыки ИИ

Требования к железу

• Минимум: 8 ГБ VRAM с --lazy_load true (модели грузятся и выгружаются по очереди)
• Рекомендуется: от 16 ГБ VRAM для комфортной работы на одном GPU
• Несколько GPU: используй --mula_device cuda:0 --codec_device cuda:1, чтобы распределить нагрузку между видеокартами
• Модель 3B с lazy_load выходит на пик около 6.2 ГБ VRAM

Установка

1. Клонирование репозитория

cd ~/  # или нужная директория
git clone https://github.com/HeartMuLa/heartlib.git
cd heartlib

2. Создание виртуального окружения (нужен Python 3.10)

uv venv --python 3.10 .venv
. .venv/bin/activate
uv pip install -e .

3. Устранение конфликтов зависимостей

ВАЖНО: по состоянию на февраль 2026 закреплённые зависимости конфликтуют с более новыми пакетами. Примени эти исправления:

# Обновляем datasets (старая версия несовместима с текущим pyarrow)
uv pip install --upgrade datasets

# Обновляем transformers (нужно для совместимости с huggingface-hub 1.x)
uv pip install --upgrade transformers

4. Патчинг исходного кода (нужен для transformers 5.x)

Патч 1 — исправление кэша RoPE в src/heartlib/heartmula/modeling_heartmula.py:

В методе setup_caches класса HeartMuLa добавь переинициализацию RoPE после блока reset_caches (try/except) и перед блоком with device::

# 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)

Зачем: from_pretrained сначала создаёт модель на meta-устройстве; Llama3ScaledRoPE.rope_init() пропускает построение кэша на meta-тензорах и больше не пересобирает его после загрузки весов на реальное устройство.

Патч 2 — исправление загрузки HeartCodec в src/heartlib/pipelines/music_generation.py:

Добавь ignore_mismatched_sizes=True во ВСЕ вызовы HeartCodec.from_pretrained() (их два: ранняя загрузка в __init__ и ленивая загрузка в свойстве codec).

Зачем: буферы initted у VQ-кодбука имеют форму [1] в чекпоинте и [] в модели. Данные те же — просто скаляр против 0-мерного тензора. Можно безопасно игнорировать.

5. Загрузка чекпоинтов модели

cd heartlib  # корень проекта
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'

Все три можно качать параллельно. Суммарный объём — несколько гигабайт.

GPU / CUDA

HeartMuLa по умолчанию работает на CUDA (--mula_device cuda --codec_device cuda). Дополнительная настройка не нужна, если у пользователя есть NVIDIA GPU с установленной поддержкой PyTorch CUDA.

• Установленный torch==2.4.1 уже включает поддержку CUDA 12.1 из коробки
• torchtune может показывать версию 0.4.0+cpu — это лишь метаданные пакета, реально он использует CUDA через PyTorch
• Чтобы убедиться, что задействован GPU, ищи в выводе строки про «CUDA memory» (например, “CUDA memory before unloading: 6.20 GB”)
• Нет GPU? Можно запустить на CPU с --mula_device cpu --codec_device cpu, но генерация будет крайне медленной (одна песня — потенциально 30–60+ минут против ~4 минут на GPU). Режим CPU к тому же требует много RAM (от ~12 ГБ свободно). Если у пользователя нет NVIDIA GPU, посоветуй облачный GPU-сервис (бесплатный тариф Google Colab с T4, Lambda Labs и т.п.) или онлайн-демо на https://heartmula.github.io/.

Использование

Базовая генерация

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

Формат входных данных

Теги (через запятую, без пробелов):

piano,happy,wedding,synthesizer,romantic

или

rock,energetic,guitar,drums,male-vocal

Текст песни (используй структурные теги в квадратных скобках):

[Intro]

[Verse]
Your lyrics here...

[Chorus]
Chorus lyrics...

[Bridge]
Bridge lyrics...

[Outro]

Основные параметры

Производительность

• RTF (Real-Time Factor) ≈ 1.0 — песня на 4 минуты генерируется примерно за 4 минуты
• Выход: MP3, 48 кГц, стерео, 128 кбит/с

Подводные камни

1. НЕ используй bf16 для HeartCodec — это портит качество звука. Бери fp32 (по умолчанию).
2. Теги могут игнорироваться — известная проблема (#90). Текст обычно перевешивает; поэкспериментируй с порядком тегов.
3. Triton недоступен на macOS — ускорение GPU работает только на Linux/CUDA.
4. Несовместимость с RTX 5080 отмечена в issues апстрима.
5. Из-за закреплённых зависимостей нужны ручные обновления и патчи, описанные выше.

Ссылки

• Репозиторий: https://github.com/HeartMuLa/heartlib
• Модели: https://huggingface.co/HeartMuLa
• Статья: https://arxiv.org/abs/2601.10547
• Лицензия: Apache-2.0