HeartMuLa Codec Loader

HeartMuLa ships two loaders, and everyone stares at the big one. The HeartMuLaLoader loads the 3B LLM that writes the song, gets all the attention, and absolutely cannot make a sound by itself. The HeartMuLaCodecLoader is the quiet one that loads HeartCodec - the model that turns the generator's tokens into an actual waveform. Miss it and your generation runs, finishes, and hands you... tokens. Nothing plays.

The two are deliberately split so you can keep the codec resident in memory while swapping the LLM between versions. That's the whole memory-management story the pack advertises: the heavy language model can come and go, the codec sticks around.

What it actually loads

Under the hood this calls HeartCodecModel.from_pretrained() on the folder you point it at, and it runs in plain fp32. That's a choice, not an oversight - the README says fp32 is kept "for maximum audio fidelity," which for an audio codec is the right call. It's the decode half of the generation pipeline: the LLM produces discrete tokens, and this codec is what maps them back to sound.

The inputs are a two-liner:

• base_path (STRING, default "HeartMuLa") - the folder holding your HeartMuLa files. It resolves against your ComfyUI models dir, so the default means ComfyUI/models/HeartMuLa/. There's a 📁 button on the node that opens a custom folder browser - use it, it's less typing and less typo.
• codec_version (COMBO) - HeartCodec-oss-20260123 (default) or HeartCodec-oss.

The output is a single codec socket (type HEARTMULA_CODEC) that plugs straight into the HeartMuLaAudioDecoder.

The version matching matters. The newer HeartCodec-oss-20260123 is the one to pair with the HeartMuLa-oss-3B-happy-new-year and RL-tuned models; the older HeartCodec-oss goes with the original HeartMuLa-oss-3B. Mix them and you'll get garbage or decode errors, not a nice error message telling you which one to use.

Installing and getting the weights

Grab the pack via ComfyUI Manager (search "HeartMuLa") or the usual way:

cd ComfyUI/custom_nodes
git clone https://github.com/BobRandomNumber/ComfyUI-HeartMuLa.git
pip install -r requirements.txt

That requirements file pulls in torchao, torchtune, accelerate, and vector-quantize-pytorch - heavy-ish deps, so expect a non-trivial first install. Then download the codec from the HeartMuLa org on HuggingFace and drop it where the node expects it:

ComfyUI/models/HeartMuLa/
├── HeartCodec-oss-20260123/
└── HeartCodec-oss/

You don't need the gen_config.json and tokenizer.json from the root for this node - those belong to the generator - but they need to live in that same HeartMuLa/ folder for the LLM loader, so grab them while you're there.

Common issues

The big one is a FileNotFoundError on load. The error prints the exact path it looked for (Codec folder not found at: ...), which is more helpful than it sounds - it's telling you the folder name doesn't match the combo box, or the model isn't where you think it is. Fix the folder layout, not the code.

Worth knowing before you start: this is the fiddly end of a model that originally shipped non-commercial and flipped to Apache 2.0 in early 2026, so commercial use is fine now. And generation end-to-end wants a real GPU - community numbers land around 12–16GB VRAM for a 60-second clip, and the fp32 codec is part of that bill. It's the easiest node in the pack to forget and the cheapest to get right. Load it, match the version, move on.