HeartMuLa Loader

Every HeartMuLa workflow starts here. RT HeartMuLa Loader is the node that reads the model weights off your disk, picks a quantization level and a precision, and hands the four handles (model, tokenizer, codec, gen config) to the sampler. It's also the node where most people's first run fails, because it's the one that actually needs the multi-gigabyte downloads to be sitting in exactly the right folder.

HeartMuLa, in case you've only seen the pack name, is a family of open multilingual text-to-music models - the 3B weights went Apache-2.0 in early 2026 after a brief and very public CC-BY-NC scare. It sings full songs with lyrics entirely on your hardware. Community consensus: the vocals are genuinely good and it almost never mangles your words, but it's slow and it ignores your genre tags unless you feed it the right format and crank CFG (more on that in the sampler and tags-builder articles). The loader can't fix slow - but it decides whether the thing fits on your card at all.

How it works

The loader registers HeartMuLa's own model classes from the bundled heartlib with the Hugging Face transformers AutoModel system, then loads three things from ComfyUI/models/HeartMuLa/:

• <model_name>/ - the 3B backbone (HeartMuLa-oss-3B or the newer RL-tuned HeartMuLa-RL-oss-3B-20260123)
• <codec_name>/ - the neural codec that turns tokens into audio (HeartCodec-oss-20260123 is the new default, HeartCodec-oss is the old one)
• gen_config.json + tokenizer.json at the base of that folder - from the HeartMuLaGen wrapper repo you cloned

Everything is loaded with from_pretrained, the codec goes to eval mode, and if compile_model is on and you're on CUDA, the backbone gets run through torch.compile. You get back model, tokenizer, codec, and gen_config, all four of which plug into RT HeartMuLa Sampler. Yes, the sampler expects all four - this is not a node you can skip a wire on.

The inputs that actually matter

The dropdown list looks like a spec sheet, but really only three choices decide your fate:

• quantization - 4bit is the default and the README's recommendation for anyone under ~16GB. It uses BitsAndBytes NF4 and is the difference between fitting and not. Here's the trap: 8bit is listed in the dropdown, but the current code only applies quantization when you pick 4bit - 8bit silently loads full precision, same as none. So if you pick 8bit expecting a middle ground, you'll get an OOM you didn't plan for. Pick 4bit or none and know which one you chose.
• codec_precision - defaults to fp32, which the author insists is critical for high-fidelity output: it prevents metallic hiss in cymbals and sibilants. It costs speed. bf16/auto are the lighter options. There's a separate mula_precision for the backbone (default bf16).
• compile_model - True burns 1–2 minutes on the first generation while it optimizes the graph, then runs 20–30% faster on every run after. Ideal if you're batch-producing, a waste if you're just testing one prompt.

device defaults to cuda; cpu exists but plan to wait a while.

Installing it (the real steps)

Install the pack once - every RT HeartMuLa node comes with it. Either search "ComfyUI-RT-HeartMuLa" in ComfyUI Manager, or:

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

The README says you can get away with just soundfile, torchtune, and torchao first - and that genuinely works for some people, but the codec needs vector_quantize_pytorch, so if the loader dies on import, go ahead and install the full requirements.txt. That's the fix, not a retry.

The part people actually trip on is models. The pack does not download weights for you. From ComfyUI/models/ (git-lfs installed first):

git lfs install
git clone https://huggingface.co/HeartMuLa/HeartMuLaGen HeartMuLa
cd HeartMuLa
git clone https://huggingface.co/HeartMuLa/HeartMuLa-RL-oss-3B-20260123
git clone https://huggingface.co/HeartMuLa/HeartCodec-oss-20260123

Common issues

• The loader raises an error that mentions "Missing: vector-quantize-pytorch" - that message is a catch-all: it fires whenever any heartlib dependency failed to import. Run pip install -r requirements.txt in the pack folder, not just the three "first try" deps.
• "Model not found"-style failures at from_pretrained - the folder layout above is strict. Double-check the subfolder names match the model_name/codec_name you selected, and that gen_config.json is in models/HeartMuLa/, not nested in a model subfolder.
• OOM at load - you're on none (or the fake 8bit). Drop to 4bit and bf16, which sits around 8–9GB; unquantized is more like 16GB+ for real.
• First run is painfully slow after enabling compile - that's expected, it's the graph optimization. Run a 20-second song first to check quality before committing to a long one, which is exactly what the README tells you to do.