[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CQZSQ1VHYRCEZQB52RMFKB":3,"skill-same:01M7CQZSQ1VHYRCEZQB52RMFKB":61},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":41,"commitSha":42,"skillDirectory":43,"forksCount":14,"repositoryHtmlUrl":44,"repositoryHomepageUrl":6,"ownerHtmlUrl":45,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":46,"install":47,"resources":60},"01M7CQZSQ1VHYRCEZQB52RMFKB","heartmula",null,"HeartMuLa: Suno-like song generation from lyrics + tags.","thalhath2234\u002Ftimely-app","thalhath2234","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F69391707?v=4","01M7CQNWTHSAP0D50RQY6W9YZQ","Thalhath","01M7CQNWVQN600VKQXRGTWCDPH",0,"MIT","https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app\u002Fblob\u002Fdev\u002Fapps\u002Fagent\u002Fhermes\u002Foptional-skills\u002Fcreative\u002Fheartmula\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: heartmula\ndescription: \"HeartMuLa: Suno-like song generation from lyrics + tags.\"\nversion: 1.0.0\nauthor: Teknium (teknium1), Hermes Agent\nlicense: MIT\nplatforms: [linux, macos]\nmetadata:\n  hermes:\n    tags: [music, audio, generation, ai, heartmula, heartcodec, lyrics, songs]\n    related_skills: [songwriting-and-ai-music]\n---\n\n# HeartMuLa - Open-Source Music Generation\n\n## Overview\nHeartMuLa is a family of open-source music foundation models (Apache-2.0) that generates music conditioned on lyrics and tags, with multilingual support. Generates full songs from lyrics + tags. Comparable to Suno for open-source. Includes:\n- **HeartMuLa** - Music language model (3B\u002F7B) for generation from lyrics + tags\n- **HeartCodec** - 12.5Hz music codec for high-fidelity audio reconstruction\n- **HeartTranscriptor** - Whisper-based lyrics transcription\n- **HeartCLAP** - Audio-text alignment model\n\n## When to Use\n- User wants to generate music\u002Fsongs from text descriptions\n- User wants an open-source Suno alternative\n- User wants local\u002Foffline music generation\n- User asks about HeartMuLa, heartlib, or AI music generation\n\n## Hardware Requirements\n- **Minimum**: 8GB VRAM with `--lazy_load true` (loads\u002Funloads models sequentially)\n- **Recommended**: 16GB+ VRAM for comfortable single-GPU usage\n- **Multi-GPU**: Use `--mula_device cuda:0 --codec_device cuda:1` to split across GPUs\n- 3B model with lazy_load peaks at ~6.2GB VRAM\n\n## Installation Steps\n\n### 1. Clone Repository\n```bash\ncd ~\u002F  # or desired directory\ngit clone https:\u002F\u002Fgithub.com\u002FHeartMuLa\u002Fheartlib.git\ncd heartlib\n```\n\n### 2. Create Virtual Environment (Python 3.10 required)\n```bash\nuv venv --python 3.10 .venv\n. .venv\u002Fbin\u002Factivate\nuv pip install -e .\n```\n\n### 3. Fix Dependency Compatibility Issues\n\n**IMPORTANT**: As of Feb 2026, the pinned dependencies have conflicts with newer packages. Apply these fixes:\n\n```bash\n# Upgrade datasets (old version incompatible with current pyarrow)\nuv pip install --upgrade datasets\n\n# Upgrade transformers (needed for huggingface-hub 1.x compatibility)\nuv pip install --upgrade transformers\n```\n\n### 4. Patch Source Code (Required for transformers 5.x)\n\n**Patch 1 - RoPE cache fix** in `src\u002Fheartlib\u002Fheartmula\u002Fmodeling_heartmula.py`:\n\nIn the `setup_caches` method of the `HeartMuLa` class, add RoPE reinitialization after the `reset_caches` try\u002Fexcept block and before the `with device:` block:\n\n```python\n# Re-initialize RoPE caches that were skipped during meta-device loading\nfrom torchtune.models.llama3_1._position_embeddings import Llama3ScaledRoPE\nfor module in self.modules():\n    if isinstance(module, Llama3ScaledRoPE) and not module.is_cache_built:\n        module.rope_init()\n        module.to(device)\n```\n\n**Why**: `from_pretrained` creates model on meta device first; `Llama3ScaledRoPE.rope_init()` skips cache building on meta tensors, then never rebuilds after weights are loaded to real device.\n\n**Patch 2 - HeartCodec loading fix** in `src\u002Fheartlib\u002Fpipelines\u002Fmusic_generation.py`:\n\nAdd `ignore_mismatched_sizes=True` to ALL `HeartCodec.from_pretrained()` calls (there are 2: the eager load in `__init__` and the lazy load in the `codec` property).\n\n**Why**: VQ codebook `initted` buffers have shape `[1]` in checkpoint vs `[]` in model. Same data, just scalar vs 0-d tensor. Safe to ignore.\n\n### 5. Download Model Checkpoints\n```bash\ncd heartlib  # project root\nhf download --local-dir '.\u002Fckpt' 'HeartMuLa\u002FHeartMuLaGen'\nhf download --local-dir '.\u002Fckpt\u002FHeartMuLa-oss-3B' 'HeartMuLa\u002FHeartMuLa-oss-3B-happy-new-year'\nhf download --local-dir '.\u002Fckpt\u002FHeartCodec-oss' 'HeartMuLa\u002FHeartCodec-oss-20260123'\n```\n\nAll 3 can be downloaded in parallel. Total size is several GB.\n\n## GPU \u002F CUDA\n\nHeartMuLa uses CUDA by default (`--mula_device cuda --codec_device cuda`). No extra setup needed if the user has an NVIDIA GPU with PyTorch CUDA support installed.\n\n- The installed `torch==2.4.1` includes CUDA 12.1 support out of the box\n- `torchtune` may report version `0.4.0+cpu` — this is just package metadata, it still uses CUDA via PyTorch\n- To verify GPU is being used, look for \"CUDA memory\" lines in the output (e.g. \"CUDA memory before unloading: 6.20 GB\")\n- **No GPU?** You can run on CPU with `--mula_device cpu --codec_device cpu`, but expect generation to be **extremely slow** (potentially 30-60+ minutes for a single song vs ~4 minutes on GPU). CPU mode also requires significant RAM (~12GB+ free). If the user has no NVIDIA GPU, recommend using a cloud GPU service (Google Colab free tier with T4, Lambda Labs, etc.) or the online demo at https:\u002F\u002Fheartmula.github.io\u002F instead.\n\n## Usage\n\n### Basic Generation\n```bash\ncd heartlib\n. .venv\u002Fbin\u002Factivate\npython .\u002Fexamples\u002Frun_music_generation.py \\\n  --model_path=.\u002Fckpt \\\n  --version=\"3B\" \\\n  --lyrics=\".\u002Fassets\u002Flyrics.txt\" \\\n  --tags=\".\u002Fassets\u002Ftags.txt\" \\\n  --save_path=\".\u002Fassets\u002Foutput.mp3\" \\\n  --lazy_load true\n```\n\n### Input Formatting\n\n**Tags** (comma-separated, no spaces):\n```\npiano,happy,wedding,synthesizer,romantic\n```\nor\n```\nrock,energetic,guitar,drums,male-vocal\n```\n\n**Lyrics** (use bracketed structural tags):\n```\n[Intro]\n\n[Verse]\nYour lyrics here...\n\n[Chorus]\nChorus lyrics...\n\n[Bridge]\nBridge lyrics...\n\n[Outro]\n```\n\n### Key Parameters\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `--max_audio_length_ms` | 240000 | Max length in ms (240s = 4 min) |\n| `--topk` | 50 | Top-k sampling |\n| `--temperature` | 1.0 | Sampling temperature |\n| `--cfg_scale` | 1.5 | Classifier-free guidance scale |\n| `--lazy_load` | false | Load\u002Funload models on demand (saves VRAM) |\n| `--mula_dtype` | bfloat16 | Dtype for HeartMuLa (bf16 recommended) |\n| `--codec_dtype` | float32 | Dtype for HeartCodec (fp32 recommended for quality) |\n\n### Performance\n- RTF (Real-Time Factor) ≈ 1.0 — a 4-minute song takes ~4 minutes to generate\n- Output: MP3, 48kHz stereo, 128kbps\n\n## Pitfalls\n1. **Do NOT use bf16 for HeartCodec** — degrades audio quality. Use fp32 (default).\n2. **Tags may be ignored** — known issue (#90). Lyrics tend to dominate; experiment with tag ordering.\n3. **Triton not available on macOS** — Linux\u002FCUDA only for GPU acceleration.\n4. **RTX 5080 incompatibility** reported in upstream issues.\n5. The dependency pin conflicts require the manual upgrades and patches described above.\n\n## Links\n- Repo: https:\u002F\u002Fgithub.com\u002FHeartMuLa\u002Fheartlib\n- Models: https:\u002F\u002Fhuggingface.co\u002FHeartMuLa\n- Paper: https:\u002F\u002Farxiv.org\u002Fabs\u002F2601.10547\n- License: Apache-2.0\n","# HeartMuLa - Open-Source Music Generation\n\n## Overview\nHeartMuLa is a family of open-source music foundation models (Apache-2.0) that generates music conditioned on lyrics and tags, with multilingual support. Generates full songs from lyrics + tags. Comparable to Suno for open-source. Includes:\n- **HeartMuLa** - Music language model (3B\u002F7B) for generation from lyrics + tags\n- **HeartCodec** - 12.5Hz music codec for high-fidelity audio reconstruction\n- **HeartTranscriptor** - Whisper-based lyrics transcription\n- **HeartCLAP** - Audio-text alignment model\n\n## When to Use\n- User wants to generate music\u002Fsongs from text descriptions\n- User wants an open-source Suno alternative\n- User wants local\u002Foffline music generation\n- User asks about HeartMuLa, heartlib, or AI music generation\n\n## Hardware Requirements\n- **Minimum**: 8GB VRAM with `--lazy_load true` (loads\u002Funloads models sequentially)\n- **Recommended**: 16GB+ VRAM for comfortable single-GPU usage\n- **Multi-GPU**: Use `--mula_device cuda:0 --codec_device cuda:1` to split across GPUs\n- 3B model with lazy_load peaks at ~6.2GB VRAM\n\n## Installation Steps\n\n### 1. Clone Repository\n```bash\ncd ~\u002F  # or desired directory\ngit clone https:\u002F\u002Fgithub.com\u002FHeartMuLa\u002Fheartlib.git\ncd heartlib\n```\n\n### 2. Create Virtual Environment (Python 3.10 required)\n```bash\nuv venv --python 3.10 .venv\n. .venv\u002Fbin\u002Factivate\nuv pip install -e .\n```\n\n### 3. Fix Dependency Compatibility Issues\n\n**IMPORTANT**: As of Feb 2026, the pinned dependencies have conflicts with newer packages. Apply these fixes:\n\n```bash\n# Upgrade datasets (old version incompatible with current pyarrow)\nuv pip install --upgrade datasets\n\n# Upgrade transformers (needed for huggingface-hub 1.x compatibility)\nuv pip install --upgrade transformers\n```\n\n### 4. Patch Source Code (Required for transformers 5.x)\n\n**Patch 1 - RoPE cache fix** in `src\u002Fheartlib\u002Fheartmula\u002Fmodeling_heartmula.py`:\n\nIn the `setup_caches` method of the `HeartMuLa` class, add RoPE reinitialization after the `reset_caches` try\u002Fexcept block and before the `with device:` block:\n\n```python\n# Re-initialize RoPE caches that were skipped during meta-device loading\nfrom torchtune.models.llama3_1._position_embeddings import Llama3ScaledRoPE\nfor module in self.modules():\n    if isinstance(module, Llama3ScaledRoPE) and not module.is_cache_built:\n        module.rope_init()\n        module.to(device)\n```\n\n**Why**: `from_pretrained` creates model on meta device first; `Llama3ScaledRoPE.rope_init()` skips cache building on meta tensors, then never rebuilds after weights are loaded to real device.\n\n**Patch 2 - HeartCodec loading fix** in `src\u002Fheartlib\u002Fpipelines\u002Fmusic_generation.py`:\n\nAdd `ignore_mismatched_sizes=True` to ALL `HeartCodec.from_pretrained()` calls (there are 2: the eager load in `__init__` and the lazy load in the `codec` property).\n\n**Why**: VQ codebook `initted` buffers have shape `[1]` in checkpoint vs `[]` in model. Same data, just scalar vs 0-d tensor. Safe to ignore.\n\n### 5. Download Model Checkpoints\n```bash\ncd heartlib  # project root\nhf download --local-dir '.\u002Fckpt' 'HeartMuLa\u002FHeartMuLaGen'\nhf download --local-dir '.\u002Fckpt\u002FHeartMuLa-oss-3B' 'HeartMuLa\u002FHeartMuLa-oss-3B-happy-new-year'\nhf download --local-dir '.\u002Fckpt\u002FHeartCodec-oss' 'HeartMuLa\u002FHeartCodec-oss-20260123'\n```\n\nAll 3 can be downloaded in parallel. Total size is several GB.\n\n## GPU \u002F CUDA\n\nHeartMuLa uses CUDA by default (`--mula_device cuda --codec_device cuda`). No extra setup needed if the user has an NVIDIA GPU with PyTorch CUDA support installed.\n\n- The installed `torch==2.4.1` includes CUDA 12.1 support out of the box\n- `torchtune` may report version `0.4.0+cpu` — this is just package metadata, it still uses CUDA via PyTorch\n- To verify GPU is being used, look for \"CUDA memory\" lines in the output (e.g. \"CUDA memory before unloading: 6.20 GB\")\n- **No GPU?** You can run on CPU with `--mula_device cpu --codec_device cpu`, but expect generation to be **extremely slow** (potentially 30-60+ minutes for a single song vs ~4 minutes on GPU). CPU mode also requires significant RAM (~12GB+ free). If the user has no NVIDIA GPU, recommend using a cloud GPU service (Google Colab free tier with T4, Lambda Labs, etc.) or the online demo at https:\u002F\u002Fheartmula.github.io\u002F instead.\n\n## Usage\n\n### Basic Generation\n```bash\ncd heartlib\n. .venv\u002Fbin\u002Factivate\npython .\u002Fexamples\u002Frun_music_generation.py \\\n  --model_path=.\u002Fckpt \\\n  --version=\"3B\" \\\n  --lyrics=\".\u002Fassets\u002Flyrics.txt\" \\\n  --tags=\".\u002Fassets\u002Ftags.txt\" \\\n  --save_path=\".\u002Fassets\u002Foutput.mp3\" \\\n  --lazy_load true\n```\n\n### Input Formatting\n\n**Tags** (comma-separated, no spaces):\n```\npiano,happy,wedding,synthesizer,romantic\n```\nor\n```\nrock,energetic,guitar,drums,male-vocal\n```\n\n**Lyrics** (use bracketed structural tags):\n```\n[Intro]\n\n[Verse]\nYour lyrics here...\n\n[Chorus]\nChorus lyrics...\n\n[Bridge]\nBridge lyrics...\n\n[Outro]\n```\n\n### Key Parameters\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `--max_audio_length_ms` | 240000 | Max length in ms (240s = 4 min) |\n| `--topk` | 50 | Top-k sampling |\n| `--temperature` | 1.0 | Sampling temperature |\n| `--cfg_scale` | 1.5 | Classifier-free guidance scale |\n| `--lazy_load` | false | Load\u002Funload models on demand (saves VRAM) |\n| `--mula_dtype` | bfloat16 | Dtype for HeartMuLa (bf16 recommended) |\n| `--codec_dtype` | float32 | Dtype for HeartCodec (fp32 recommended for quality) |\n\n### Performance\n- RTF (Real-Time Factor) ≈ 1.0 — a 4-minute song takes ~4 minutes to generate\n- Output: MP3, 48kHz stereo, 128kbps\n\n## Pitfalls\n1. **Do NOT use bf16 for HeartCodec** — degrades audio quality. Use fp32 (default).\n2. **Tags may be ignored** — known issue (#90). Lyrics tend to dominate; experiment with tag ordering.\n3. **Triton not available on macOS** — Linux\u002FCUDA only for GPU acceleration.\n4. **RTX 5080 incompatibility** reported in upstream issues.\n5. The dependency pin conflicts require the manual upgrades and patches described above.\n\n## Links\n- Repo: https:\u002F\u002Fgithub.com\u002FHeartMuLa\u002Fheartlib\n- Models: https:\u002F\u002Fhuggingface.co\u002FHeartMuLa\n- Paper: https:\u002F\u002Farxiv.org\u002Fabs\u002F2601.10547\n- License: Apache-2.0\n",{"name":5,"author":24,"license":15,"version":25,"metadata":26,"platforms":38,"description":7},"Teknium (teknium1), Hermes Agent","1.0.0",{"hermes":27},{"tags":28,"related_skills":36},[29,30,31,32,5,33,34,35],"music","audio","generation","ai","heartcodec","lyrics","songs",[37],"songwriting-and-ai-music",[39,40],"linux","macos","dev","4d9b346961dd1d220a07fe4e6ed44b52daa57e0b","apps\u002Fagent\u002Fhermes\u002Foptional-skills\u002Fcreative\u002Fheartmula","https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app","https:\u002F\u002Fgithub.com\u002Fthalhath2234","2026-11-14 05:26:10",{"source":8,"skillName":5,"commands":48,"prompt":58,"zipAvailable":59},[49,52,55],{"tool":50,"command":51},"npx","npx skills add thalhath2234\u002Ftimely-app --skill heartmula",{"tool":53,"command":54},"bunx","bunx skills add thalhath2234\u002Ftimely-app --skill heartmula",{"tool":56,"command":57},"pnpm","pnpm dlx skills add thalhath2234\u002Ftimely-app --skill heartmula","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app\u002Fblob\u002Fdev\u002Fapps\u002Fagent\u002Fhermes\u002Foptional-skills\u002Fcreative\u002Fheartmula\u002FSKILL.md",true,[],[62,69,76,83,90,97],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":66,"categories":67,"keywords":68,"publishedAt":19},"01M7CRJRHHG68Q3XZX37TD85JB","timely","Test fixture standing in for the Timely skill (IDs, markdown dialect, workspace rule).","https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app\u002Fblob\u002Fdev\u002Fapps\u002Fagent\u002Ftests\u002Ffixtures\u002Fskills\u002Ftimely\u002FSKILL.md",[],[],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":75,"publishedAt":19},"01M7CRJPPNS8SKWVTDP3TJ9EHG","product-price-monitor","Test fixture override of the upstream product-price-monitor skill.","https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app\u002Fblob\u002Fdev\u002Fapps\u002Fagent\u002Ftests\u002Ffixtures\u002Fskills\u002Foverrides\u002Fproduct-price-monitor\u002FSKILL.md",[],[],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":19},"01M7CRJKRY4QH4RAA2MKHNZT04","blocked-page-recovery","Use when a fetch fails: 403\u002F429, paywall, WAF, bot wall.","https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app\u002Fblob\u002Fdev\u002Fapps\u002Fagent\u002Fhermes\u002Fskills\u002Fweb\u002Fblocked-page-recovery\u002FSKILL.md",[],[],{"skillNo":84,"name":85,"nameZh":6,"description":86,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":87,"categories":88,"keywords":89,"publishedAt":19},"01M7CRJG3JC6PRSTH3MW62KTH6","test-driven-development","TDD: enforce RED-GREEN-REFACTOR, tests before code.","https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app\u002Fblob\u002Fdev\u002Fapps\u002Fagent\u002Fhermes\u002Fskills\u002Fsoftware-development\u002Ftest-driven-development\u002FSKILL.md",[],[],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":19},"01M7CRJ8K3ACJYKSYDJWKJM6HV","systematic-debugging","4-phase root cause debugging: understand bugs before fixing.","https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app\u002Fblob\u002Fdev\u002Fapps\u002Fagent\u002Fhermes\u002Fskills\u002Fsoftware-development\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":98,"name":99,"nameZh":6,"description":100,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":19},"01M7CRJ3Q5QP1CVBG959M3A3BM","spike","Throwaway experiments to validate an idea before build.","https:\u002F\u002Fgithub.com\u002Fthalhath2234\u002Ftimely-app\u002Fblob\u002Fdev\u002Fapps\u002Fagent\u002Fhermes\u002Fskills\u002Fsoftware-development\u002Fspike\u002FSKILL.md",[],[]]