HeartMuLa Generate From Spec

There are two ways to fire off HeartMuLa generation in this pack, and this is the one for people who like their graphs tidy. Instead of feeding the generator three separate primitive wires - lyrics, tags, duration - HeartMuLa Generate From Spec takes a single song_spec object from HeartMuLa Song Spec and does the same thing with one cable. Same runtime, same output, less spaghetti.

Why the two paths exist. The included workflow (heartmula_simple_song_workflow.json) uses HeartMuLa Generate Music with plain STRING/INT links, because that way the widget labels import cleanly across ComfyUI frontends. Generate From Spec is the custom-type convenience route: song_spec is a HEARTMULA_SPEC object that bundles the formatted lyrics, effective tags, and max_audio_length_ms into a single package, and the node carries the whole spec through to its metadata_json output. If you're hand-building a graph around Song Spec and don't care about maximum import portability, this is the one you reach for.

Inputs that matter. Only two will occupy you in practice:

• song_spec - the spec output of HeartMuLa Song Spec. Everything creative already happened upstream.
• seed - set a fixed value (0 or higher) to reproduce a song, or -1 for pure randomness.

The rest are the same generation controls you'd find on the sibling node: topk (default 50), temperature (1.0), cfg_scale (1.8), plus runtime_profile (auto is the sensible default), keep_model_loaded (true - hold the weights between runs so batches aren't glacial), auto_download_models (leave off), and filename_prefix (default heartmula_song) which names the wav file.

Outputs. Three, all useful:

• audio_output (AUDIO) - wire this into a preview or the compliance checker.
• filepath (STRING) - where the lossless .wav landed in your ComfyUI output folder. Good for grabbing it for the outside world.
• metadata_json (STRING) - model variants used, effective runtime profile, seed, and the entire song spec. This is your reproducibility trail.

What it runs on. This is the pack's wrapper around the official heartlib pipeline API - it doesn't reinvent HeartMuLa inference. The pack vendors a pinned copy of heartlib so startup never reaches for the network, and it auto-detects the best model+codec pair it finds under ComfyUI/models/HeartMuLa (it prefers the HeartMuLa-RL-oss-3B-20260123 + HeartCodec-oss-20260123 pair, then falls back down the list). On Apple Silicon, auto runs the model on MPS and the codec on CPU, with a CPU-only fallback if MPS chokes.

Install. Same as the rest of the pack: ComfyUI Manager → "Install via Git URL" → https://github.com/MPC2026/ComfyUI-MPC-HeartMuLa.git, or clone it:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/MPC2026/ComfyUI-MPC-HeartMuLa.git
cd ComfyUI-MPC-HeartMuLa
python -m pip install -r requirements.txt

Restart, search "HeartMuLa," and you're set. You still need the actual model folders under ComfyUI/models/HeartMuLa - generation won't start without a model+codec pair, and the node will tell you exactly which one is missing when you try.

Gotchas. HEARTMULA_SPEC is a custom type, so this node's inputs only resolve once the pack is loaded - that's true of any custom node type and not worth stressing about. Realistic expectations are the bigger thing: HeartMuLa quality is "ok" next to Suno, it wants a serious chunk of VRAM (roughly 16 GB on consumer cards without quantization), and lyric fidelity is model-limited. The compliance node exists precisely so you can measure that last one instead of hoping.