HeartMuLa Codec Loader

Every image workflow has a checkpoint loader and a VAE loader, and nobody writes articles about the VAE. HeartMuLa Codec Loader is the audio equivalent: an unglamorous, load-the-thing-and-hand-it-over node that you'll forget is in your graph until you delete it by accident and nothing decodes anymore.

HeartMuLa generates music as audio tokens - a sequence of codebook indices, not a waveform. The Music Generator produces those tokens; this loader supplies the HeartCodec neural codec that turns them back into sound at 48 kHz. It's a separate model from the generator (that's the HeartMuLa-oss-3B-* LLM, loaded by the HeartMuLa Loader), which is why there are two loader nodes staring at you instead of one.

What it does

Two inputs, one output:

• base_path - default HeartMuLa, i.e. ComfyUI/models/HeartMuLa/. There's a 📁 button that opens a folder browser so you don't have to type paths.
• codec_version - dropdown with the 2026 codec HeartCodec-oss-20260123 (default, and what you want) and the older HeartCodec-oss.

Output is a HEARTMULA_CODEC socket that feeds straight into HeartMuLa Audio Decoder. That's the entire job. The codec loads in fp32 regardless of the generator's bf16/fp32 choice - the README calls this out, and it's one reason the decode step is a chunk of VRAM you should budget for.

Models, the honest way

Like every HeartMuLa weight, the codec doesn't auto-download. You clone it into the same folder as the generator:

cd ComfyUI/models/HeartMuLa
git clone https://huggingface.co/HeartMuLa/HeartCodec-oss-20260123

The folder layout matters - the loader resolves models/HeartMuLa/<codec_version>, so the subfolder name has to match the dropdown value exactly. If it's wrong you get a FileNotFoundError naming the missing path, which at least tells you what to fix.

Installing the pack

If you don't have the pack yet:

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

Then restart ComfyUI - nodes show up under JK-HeartMuLa. It's a V3-API pack, so a reasonably recent ComfyUI is required. The requirements pull in the heartlib stack (torchao, torchtune, accelerate, vector-quantize-pytorch) plus the fork's additions (muq, librosa), so give pip install a minute.

Troubleshooting

The failure modes here are almost always "missing model folder," which the error message names directly. One worth knowing: the codec is moved onto the GPU for decode and back to CPU afterwards, so if you're watching VRAM and see a spike during the decode step, that's expected - it's the codec, not a leak. And if the decoder ever spits out silence, check the generator first: zero tokens decode to a silent 48 kHz clip by design, and that's a generation problem wearing a decode costume.