HeartMuLa Song Spec

Every song in this pack starts here. HeartMuLa Song Spec is the composition front-end of ComfyUI-MPC-HeartMuLa: it takes your raw creative intentions - lyrics, style tags, BPM, key, duration, and how the song should end - and turns them into the exact conditioning inputs HeartMuLa can actually understand. Nothing generates in this node; it's the brief. Which is exactly why it exists, because HeartMuLa is picky about how it gets told what to do.

Why the translation layer. Upstream HeartMuLa only conditions on two things: lyrics and a comma-separated tags string. There's no BPM field, no key picker, no duration control on the model. This node does the mapping for you, so you get to think in music terms instead of prompt-hacking. It lowercases and cleans your style tags, then appends derived tokens: 120bpm (from the BPM input), c major (from the key), and two quality-biasing tags the pack adds to every song - clear vocals and lyric forward - because the author found those push HeartMuLa toward singing what you wrote. If the duration is 120s or more it tags full song; 30s or less gets short song. The result is a tags string that tells the model what's what.

Inputs - the real ones. You'll touch five of them:

• lyrics - the actual words, multiline, [Verse]/[Chorus] markers welcome.
• style_tags - comma-separated genre/mood descriptors (anthemic,pop).
• bpm - 40–240, default 120.
• song_key - a dropdown of 30 keys (all 12 majors plus 18 minors).
• duration_seconds - 10–600, step 5.

Plus two for endings: ending_mode is none, outro, or tag ending, and ending_text holds what that ending should say. Here's a neat detail: with tag ending, the node appends an [Outro] block and repeats your last line - a small loop-friendly trick for tracks that should tag out cleanly.

Outputs. Five, and the first two are the ones the generator eats:

• lyrics - your lyrics with the ending block appended.
• tags - the effective, de-duplicated tag string.
• max_audio_length_ms - just duration_seconds × 1000, handed straight to the generator.
• metadata_json - BPM, key, duration, ending mode, and the effective tags/lyrics, all recorded for reproducibility.
• song_spec - a custom HEARTMULA_SPEC object bundling the whole thing, for the FromSpec variant nodes.

Wire lyrics and tags into HeartMuLa Generate Music, or song_spec into Generate From Spec / Lyrics Compliance From Spec. The included workflow routes the primitives, which imports cleanly.

Install. Part of the ComfyUI-MPC-HeartMuLa pack, so install the pack once. ComfyUI Manager → "Install via Git URL" → https://github.com/MPC2026/ComfyUI-MPC-HeartMuLa.git, or:

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 ComfyUI, search "HeartMuLa," and add the node. This one doesn't load any models by itself - the model folders only matter once you hit a generation node - so you can write the whole song brief before worrying about downloads.

Gotchas. The lyric text you put here is what the compliance node checks against, so if you edit lyrics downstream of the spec, the comparison drifts - keep the flow Song Spec → Generate → Compliance and it stays honest. And remember the upstream constraints: HeartMuLa lowercases text internally, so don't fight for capitalization, and exact lyric reproduction is model-limited. This node buys you a clean brief, not a guarantee the model sings it verbatim.