heartmula

HeartMuLa 是一套开源音乐生成基础模型家族（Apache-2.0 许可），可根据歌词与标签生成音乐，并支持多语言。官方描述其为开源领域可对标 Suno 的方案，能够从歌词加标签生成完整歌曲。

用途

HeartMuLa 用于从文本（歌词 + 标签）生成音乐/歌曲。适合以下场景：用户希望根据文字描述生成音乐或歌曲；用户希望寻找开源的 Suno 替代品；用户希望在本地或离线环境进行音乐生成；用户询问 HeartMuLa、heartlib 或 AI 音乐生成相关话题。

组件构成

模型家族包含四个部分：

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

硬件要求

最低：8GB 显存，配合 --lazy_load true（按顺序加载/卸载模型）。
推荐：16GB 以上显存，适合单 GPU 舒适使用。
多 GPU：使用 --mula_device cuda:0 --codec_device cuda:1 将模型拆分到不同 GPU。
3B 模型配合 lazy_load 的显存峰值约 6.2GB。

安装步骤

克隆仓库：

cd ~/  # or desired directory
git clone https://github.com/HeartMuLa/heartlib.git
cd heartlib

创建虚拟环境（需要 Python 3.10）：

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

修复依赖兼容性问题。资料指出，截至 2026 年 2 月，固定的依赖版本与较新包存在冲突，需进行以下升级：

# 升级 datasets（旧版本与当前 pyarrow 不兼容）
uv pip install --upgrade datasets

# 升级 transformers（huggingface-hub 1.x 兼容所需）
uv pip install --upgrade transformers

为 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 device 上创建模型；Llama3ScaledRoPE.rope_init() 在 meta 张量上会跳过缓存构建，权重加载到真实设备后不会再重建。

补丁 2 —— 修复 HeartCodec 加载，位于 src/heartlib/pipelines/music_generation.py：为所有 HeartCodec.from_pretrained() 调用（共 2 处：init 中的急加载和 codec 属性中的惰性加载）添加 ignore_mismatched_sizes=True。

原因：检查点中 VQ codebook 初始化缓冲的形状为 [1]，而模型中是 []，数据相同，只是标量与 0 维张量之别，忽略即可。

下载模型检查点：

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'

三个下载可并行进行，总大小为若干 GB。

GPU / CUDA

HeartMuLa 默认使用 CUDA（--mula_device cuda --codec_device cuda）。如果用户拥有 NVIDIA GPU 且已安装支持 CUDA 的 PyTorch，则无需额外设置。安装的 torch==2.4.1 自带 CUDA 12.1 支持。torchtune 可能报告版本为 0.4.0+cpu，这只是包元数据，实际上仍通过 PyTorch 使用 CUDA。可通过输出中的 “CUDA memory” 行（例如 “CUDA memory before unloading: 6.20 GB”）确认 GPU 正在被使用。

无 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，最大长度（毫秒），240000 = 4 分钟。
--topk：默认 50，Top-k 采样。
--temperature：默认 1.0，采样温度。
--cfg_scale：默认 1.5，无分类器引导（classifier-free guidance）系数。
--lazy_load：默认 false，按需加载/卸载模型（节省显存）。
--mula_dtype：默认 bfloat16，HeartMuLa 的数据类型（推荐 bf16）。
--codec_dtype：默认 float32，HeartCodec 的数据类型（推荐 fp32 以保证质量）。

性能

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

已知限制与注意事项

不要对 HeartCodec 使用 bf16，会降低音频质量，应使用 fp32（默认）。
标签可能被忽略，这是已知问题（#90）。歌词往往占主导；可尝试调整标签顺序。
macOS 上不可用 Triton，GPU 加速仅限 Linux/CUDA。
上游问题中报告了 RTX 5080 不兼容。
依赖固定版本的冲突需要按上述步骤手动升级并打补丁。

链接

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