heartmula

HeartMuLa - 开源音乐生成

概述

HeartMuLa 是一系列开源音乐基础模型（Apache-2.0），可根据歌词和标签生成音乐，并支持多语言。可根据歌词和标签生成完整歌曲。在开源领域可与 Suno 媲美。包括：

• HeartMuLa - 音乐语言模型（3B/7B），可根据歌词和标签生成音乐
• HeartCodec - 12.5Hz 音乐编解码器，用于高保真音频重建
• HeartTranscriptor - 基于 Whisper 的歌词转录工具
• HeartCLAP - 音频与文本对齐模型

适用场景

• 用户想根据文本描述生成音乐或歌曲
• 用户想要开源的 Suno 替代方案
• 用户想在本地或离线生成音乐
• 用户询问 HeartMuLa、heartlib 或 AI 音乐生成

硬件要求

• 最低配置：8GB VRAM，需使用 --lazy_load true（按顺序加载和卸载模型）
• 推荐配置：16GB 或更大的 VRAM，以便舒适地使用单 GPU
• 多 GPU：使用 --mula_device cuda:0 --codec_device cuda:1，将任务分配到多个 GPU
• 3B 模型启用 lazy_load 时，VRAM 峰值约为 6.2GB

安装步骤

1. 克隆仓库

cd ~/  # or desired directory
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 年 2 月，固定版本的依赖项与较新软件包存在冲突。请应用以下修复：

# 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. 修补源代码（transformers 5.x 必需）

修补 1 - RoPE 缓存修复，位于 src/heartlib/heartmula/modeling_heartmula.py：

在 HeartMuLa 类的 setup_caches 方法中，找到 reset_caches 的 try/except 块，并在其后、with device: 块之前添加 RoPE 重新初始化代码：

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

在所有 HeartCodec.from_pretrained() 调用中添加 ignore_mismatched_sizes=True（共有 2 处：__init__ 中的即时加载，以及 codec 属性中的延迟加载）。

原因：VQ 码本的 initted 缓冲区在检查点中的形状为 [1]，而在模型中为 []。数据相同，只是分别为标量和 0 维张量。可以安全忽略。

5. 下载模型检查点

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'

这 3 个模型都可以并行下载。总大小为数 GB。

GPU / CUDA

HeartMuLa 默认使用 CUDA（--mula_device cuda --codec_device cuda）。如果用户已安装支持 PyTorch CUDA 的 NVIDIA GPU，则无需额外配置。

• 已安装的 torch==2.4.1 开箱即支持 CUDA 12.1
• torchtune 可能会显示版本为 0.4.0+cpu——这只是软件包元数据，实际仍通过 PyTorch 使用 CUDA
• 要确认正在使用 GPU，请查看输出中的 “CUDA memory” 行（例如 “CUDA memory before unloading: 6.20 GB”）
• 没有 GPU？ 可使用 --mula_device cpu --codec_device cpu 在 CPU 上运行，但生成速度会极慢（生成一首歌可能需要 30–60 分钟以上，而 GPU 上约需 4 分钟）。CPU 模式也需要大量内存（至少约 12GB 可用）。如果用户没有 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]

关键参数

参数	默认值	描述
--max_audio_length_ms	240000	最大时长，单位为毫秒（240 秒 = 4 分钟）
--topk	50	Top-k 采样
--temperature	1.0	采样温度
--cfg_scale	1.5	无分类器引导强度
--lazy_load	false	按需加载/卸载模型（节省 VRAM）
--mula_dtype	bfloat16	HeartMuLa 的数据类型（推荐 bf16）
--codec_dtype	float32	HeartCodec 的数据类型（为保证质量，推荐 fp32）

性能

• RTF（实时因子）≈ 1.0 — 生成一首 4 分钟的歌曲约需 4 分钟
• 输出：MP3、48kHz 立体声、128kbps

注意事项

1. 请勿对 HeartCodec 使用 bf16 — 这会降低音频质量。请使用 fp32（默认值）。
2. 标签可能会被忽略 — 已知问题（#90）。歌词往往占主导地位；可尝试调整标签顺序。
3. macOS 上无法使用 Triton — 仅 Linux/CUDA 支持 GPU 加速。
4. 上游问题中报告了 RTX 5080 不兼容。
5. 依赖版本固定存在冲突，需要按上述说明手动升级并打补丁。

链接

• 仓库：https://github.com/HeartMuLa/heartlib
• 模型：https://huggingface.co/HeartMuLa
• 论文：https://arxiv.org/abs/2601.10547
• 许可证：Apache-2.0