HeartMuLa MuQ Model Loader

Every HeartMuLa weight in this pack makes you clone it into a models folder by hand. HeartMuLa MuQ Model Loader is the one exception: it loads OpenMuQ/MuQ-MuLan-large - a Tencent research model that turns a reference song into a style vector - and it's the only component here that auto-downloads from Hugging Face on first run, into your HF cache rather than ComfyUI/models. If you're new to the pack, it's also the node you can safely ignore until you actually want style transfer, because the style feature it feeds is explicitly experimental.

The single input tells the whole story about how this pack thinks about memory:

• device - cpu (default) or gpu. CPU runs the style embedding in ~2.5 GB of system RAM with zero VRAM cost. GPU is faster but holds ~2.5 GB of VRAM resident, and it isn't freed between runs unless you let the Style Embed node offload it.

Output is a JKHEARTMULA_MUQ socket that feeds HeartMuLa Style Embed. Under the hood it's a lazy module-level singleton - the model loads once per ComfyUI session and is then just moved between devices as needed, never reloaded from disk. That's why the default cpu is the sane choice: style embedding is a one-time-ish cost, and you don't want 2.5 GB of VRAM squatting next to the 19–20 GB the 3B music generator wants.

What it's actually for

The loader exists to serve the pack's headline feature: reference-audio style transfer. Pick a reference track, MuQ-MuLan averages it into a single 512-dim "genre/mood/instrumentation" vector, and that vector nudges generation toward the reference. Set expectations now, because the README does: this feature is research-grade, and tag-only generation usually sounds better. MuQ-MuLan deliberately strips voice and timbre from its embeddings, so it's a loose anchor, not a clone or an enhancer.

Install

The pack:

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

The requirements add muq and librosa on top of the usual heartlib stack - those are what power this node. Restart ComfyUI and it appears under JK-HeartMuLa; you'll want a recent V3-API ComfyUI.

Gotchas

First run downloads ~2.5 GB, so don't panic when it hangs - that's the model, not a crash. The README's recommended pairing is device = gpu on the loader with the Style Embed's free_vram_after toggle on, so you get fast embedding without holding VRAM through generation. And if you never connect this node to anything, nothing breaks: the Music Generator runs tag-only by design, because heartlib's default style vector is literally zeros. That's the most useful fact about the whole style system - it's opt-in, and the "off" state is exactly equivalent to plain generation.