HeartMuLa Style Embed

Here's the pack's best-kept secret: HeartMuLa Style Embed is the feature this fork was built to add, and the author's own README tells you not to build your workflow around it. It extracts a 512-dim style embedding from a reference song and feeds it to the Music Generator, nudging the output toward that reference's genre, mood, and instrumentation. In the author's own testing, tag-only generation matched a reference's tempo, energy, and brightness better than any style-transfer setting did. So treat this node as a lab bench, not a production tool.

How it works

MuQ-MuLan (loaded by the HeartMuLa MuQ Model Loader) turns a whole reference clip into one global style vector. That's a different job from "clone this song": the model strips out voice and timbre, so you get the vibe of the reference, not a copy. The embedding is computed by splitting audio into ~10-second clips, encoding each, and averaging - which is why a longer reference doesn't just mean "more style," and why the normalize toggle matters.

The inputs that matter:

• enable (default on) - the kill switch. When off, it emits a zero embedding and skips all audio + MuQ work, which is identical to style_strength = 0. One toggle flips a workflow between styled and tag-only without rewiring.
• audio - drag an audio file onto the node or use the upload button (stored in ComfyUI's input/). The optional audio_input socket overrides it when connected, so you can feed it from Load Audio, Record Audio, a trimmed clip, or even the pack's own decoder output.
• style_strength (0–2, default 1.0) - scales influence. 0 = off, 1.0 = the calibrated natural level, >1 over-drives and can destabilize output (short, subdued tracks). Start at 1.0.
• normalize (default on) - re-normalizes the embedding to unit length before applying strength, so the same strength means the same thing regardless of reference length.
• free_vram_after (default on) - after embedding, offloads MuQ back to CPU and frees its VRAM so the 3B generator has room. Pair with the loader's device = gpu for fast embedding without holding VRAM through generation.

Output is a JKHEARTMULA_CMUQ socket that plugs into the Music Generator's optional cmuq input. The mechanism is clean: heartlib hardcodes a zero style vector for tag-only generation, and this node simply overwrites it with the reference embedding before sampling.

What it's good for (and isn't)

It's good when the reference conveys a vibe your tags can't easily name - "this exact lazy-90s-hip-hop energy" - and you want a loose anchor. It is not a voice clone, not a melody transfer, not a continuation engine, and it can't rescue a weak tag set. If the reference genre matches your tags, it adds little and can drift the sound away. Research-cli turns up essentially zero community discussion of MuQ-MuLan style transfer, which tells you everything about how often people bother - this corner is genuinely experimental.

Install

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

Restart ComfyUI; it's under JK-HeartMuLa. The MuQ model auto-downloads (~2.5 GB, into the HF cache) the first time the loader runs. One practical gotcha: core ComfyUI's Load Audio decodes with PyAV, which chokes on some malformed MP3s - if your reference errors there, drag it straight onto this node (its upload path uses the more tolerant librosa) or re-encode to WAV/FLAC. If your workflow's default has enable on and you don't want style, flip it off - the node was built for exactly that.