mcpField
H
heartmula

heartmula

github.com/nousresearchクリエイティブ・メディア258.1k226 回インストール今日更新
リポジトリ

heartmula について

heartmulaは、HeartMuLaのオープンソース音楽モデル群を使い、歌詞とタグから楽曲を生成するスキルです。ローカル生成を想定し、音声再構成、歌詞の書き起こし、音声とテキストの対応付けも扱います。

主な機能

  1. 01歌詞とタグから楽曲を生成
  2. 02多言語での音楽生成
  3. 03HeartCodecによる音声再構成
  4. 04HeartTranscriptorによる歌詞の書き起こし
  5. 05HeartCLAPによる音声とテキストの対応付け

活用シーン

  1. 01指定した歌詞から楽曲を作成
  2. 02説明的なタグで音楽生成を誘導
  3. 03音声内の歌詞を書き起こし
  4. 04音声をテキストの説明と照合

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/nousresearch/hermes-agent --skill heartmula

インストール後、Claude Code で/heartmulaを入力して読み込まれたか確認します。

詳細

HeartMuLa - オープンソースの音楽生成

概要

HeartMuLaは、歌詞やタグを条件として音楽を生成する、多言語対応のオープンソース音楽基盤モデルファミリー（Apache-2.0）です。歌詞とタグからフルサイズの楽曲を生成します。オープンソース版のSunoに匹敵します。以下が含まれます。

  • HeartMuLa - 歌詞とタグから生成する音楽言語モデル（3B/7B）
  • HeartCodec - 高忠実度の音声再構成を実現する12.5Hzの音楽コーデック
  • HeartTranscriptor - Whisperベースの歌詞文字起こしモデル
  • HeartCLAP - 音声とテキストのアライメントモデル

使用する場面

  • テキストの説明から音楽や楽曲を生成したい場合
  • オープンソースのSuno代替を探している場合
  • ローカルまたはオフラインで音楽を生成したい場合
  • HeartMuLa、heartlib、またはAI音楽生成について質問された場合

ハードウェア要件

  • 最小要件：--lazy_load true（モデルを順番に読み込み・アンロード）を使用し、VRAM 8GB
  • 推奨要件：1台のGPUで快適に使うにはVRAM 16GB以上
  • マルチ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()呼び出し（__init__内の先行読み込みと、codecプロパティ内の遅延読み込みの2か所）に、ignore_mismatched_sizes=Trueを追加します。

理由：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で実行できますが、生成は非常に遅くなる見込みです（GPUでは約4分の楽曲1曲の生成に、30～60分以上かかる場合があります）。CPUモードでは大量のRAM（空き容量約12GB以上）も必要です。NVIDIA GPUがない場合は、クラウドGPUサービス（T4搭載のGoogle Colab無料プラン、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_ms240000最大長（ミリ秒）（240s = 4 min）
--topk50Top-k サンプリング
--temperature1.0サンプリング温度
--cfg_scale1.5分類器なしガイダンスのスケール
--lazy_loadfalse必要に応じてモデルを読み込み／アンロードします（VRAM を節約します）
--mula_dtypebfloat16HeartMuLa のデータ型（bf16 を推奨）
--codec_dtypefloat32HeartCodec のデータ型（品質を重視する場合は fp32 を推奨）
パフォーマンス
  • RTF（リアルタイム係数）≈ 1.0 — 4 分の曲の生成に約 4 分かかります
  • 出力：MP3、48kHz ステレオ、128kbps

注意点

  1. HeartCodec に bf16 を使用しないでください — 音質が低下します。fp32（デフォルト）を使用してください。
  2. タグが無視される場合があります — 既知の問題です（#90）。歌詞が優先される傾向があるため、タグの順序を試してください。
  3. macOS では Triton を利用できません — GPU アクセラレーションは Linux/CUDA のみです。
  4. RTX 5080 との非互換性が上流の問題で報告されています。
  5. 依存関係のバージョン固定の競合を解決するには、上記の手動アップグレードとパッチ適用が必要です。

リンク

コメント

Markdown 対応