Heartmula

HeartMuLa: генерация песен из текста и тегов (аналог Suno).

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

Источник	Встроенный (установлен по умолчанию)
Путь	skills/media/heartmula
Версия	1.0.0
Платформы	linux, macos, windows
Теги	music, audio, generation, ai, heartmula, heartcodec, lyrics, songs
Связанные навыки	audiocraft

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

к сведению

Ниже приведено полное описание навыка, которое VibeOS загружает при его активации. Агент видит эти инструкции, когда навык активен.

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

Обзор

HeartMuLa — это семейство моделей генерации музыки с открытым исходным кодом (лицензия Apache-2.0), которые создают музыку на основе текста и тегов с поддержкой нескольких языков. Генерирует полноценные песни из текста и тегов. Сравнимо с Suno для open-source. Включает:

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

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

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

Требования к оборудованию

• Минимум: 8 ГБ VRAM с --lazy_load true (последовательная загрузка/выгрузка моделей)
• Рекомендуется: 16+ ГБ VRAM для комфортного использования одной видеокарты
• Несколько GPU: используйте --mula_device cuda:0 --codec_device cuda:1 для распределения между GPU
• Модель 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 после блока try/except reset_caches и перед блоком with device::

# Повторная инициализация кэшей RoPE, пропущенных при загрузке на meta-устройство
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 кодовой книги имеют форму [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]
Ваш текст здесь...

[Chorus]
Текст припева...

[Bridge]
Текст бриджа...

[Outro]

Ключевые параметры

Параметр	По умолчанию	Описание
--max_audio_length_ms	240000	Максимальная длина в мс (240 с = 4 мин)
--topk	50	Top-k сэмплирование
--temperature	1.0	Температура сэмплирования
--cfg_scale	1.5	Масштаб классификатор-free guidance
--lazy_load	false	Загрузка/выгрузка моделей по требованию (экономит VRAM)
--mula_dtype	bfloat16	Тип данных для HeartMuLa (рекомендуется bf16)
--codec_dtype	float32	Тип данных для HeartCodec (рекомендуется fp32 для качества)

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

• 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 в upstream issues.
5. Конфликты фиксации зависимостей требуют ручных обновлений и патчей, описанных выше.

Ссылки

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