FL HeartMuLa Model Loader

Every HeartMuLa workflow in this pack starts here, and nowhere else. FL HeartMuLa Model Loader is the node that downloads, caches, and loads the 3B-parameter music model that powers the other five nodes in the pack. No model, no conditioning, no sampling, no audio - it's the dependency everything else hangs off, so you'll wire one of these into almost every FL HeartMuLa graph you build.

How it works

On first run the loader pulls four things from Hugging Face into ComfyUI/models/heartmula/: the HeartMuLa-oss-3B weights (~6 GB), the HeartCodec-oss neural audio codec, and tokenizer.json plus gen_config.json. That's a real download on first use - the node prints what it's fetching, and it's worth grabbing a coffee.

Once loaded, the pipeline is cached in memory keyed by model version, device, dtype, and 4-bit flag. So subsequent runs are fast, but flip one of those options and it reloads from disk. If you want to force it anyway, there's force_reload. If you want to skip the load entirely, there isn't - this is the one node in the pack you can't bypass.

The inputs that matter

• model_version - 3B is the only released model, and it's the default. Pick 7B and the node doesn't download anything: it raises a friendly error that just says the 7B is "coming soon." A trap, basically. Leave it on 3B.
• memory_mode - auto detects VRAM and picks for you, which is the right call 99% of the time. normal skips all cleanup for max speed on 16 GB+ cards; low and ultra force aggressive cache flushing around sampling to squeeze onto 8–10 GB.
• use_4bit - the one that actually matters on modest hardware. Drops the 3B from roughly 12 GB to ~6 GB VRAM via bitsandbytes nf4 quantization. CUDA only: on Apple Silicon it prints a warning and silently falls back to full precision, which the README warns about too.
• precision - auto means fp16 on CUDA/MPS, fp32 on CPU. You almost never need to touch it; bf16 exists for CUDA but doesn't work on MPS.

Its single output, model, feeds the Conditioning, Sampler, and Decode nodes. That's the whole graph's spine.

Installation

The pack installs like any ComfyUI custom node:

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

Or, easier: ComfyUI Manager → search "FL HeartMuLa" → Install → restart. Then restart ComfyUI and add the node.

The requirements are chunky but nothing exotic: torch/torchaudio, torchtune, torchao, transformers, accelerate, vector-quantize-pytorch, soundfile, huggingface_hub, modelscope, and bitsandbytes (that last one is what makes 4-bit work - if you skip the pip step, expect the "disabling 4-bit quantization" warning). Weights land in ComfyUI/models/heartmula/, not your custom_nodes folder, so they survive node updates.

Common issues

• First run looks stuck - it's downloading ~6 GB. Watch the console for the snapshot_download progress.
• "7B Coming Soon" error - expected. Pick 3B.
• 4-bit does nothing - either bitsandbytes isn't installed or you're on MPS/CPU. Check the console warning.
• Slow to re-run after changing precision - that's the cache invalidation doing its job, not a bug.

It's a simple node with a heavy job. Get the model loaded once and the rest of the pack is genuinely pleasant to work with.