Antimeter Music Director - Plan Validator & Router

This is the node doing the actual work in the pack's music chain, and the honest answer to a problem everyone hits when they bolt an LLM onto a diffusion graph: chat models write plans that should not be trusted. They invent tempos, hallucinate keys, occasionally refuse to output valid JSON, and - the classic - write lyrics into a request that said "no lyrics, please." The Antimeter Music Director - Plan Validator & Router exists to be the adult in the room. Keep it in the workflow; the pack's own docs say so.

What it does

It takes two forced STRING inputs: director_brief (the JSON packet from the User Brief node) and director_plan (whatever the local Qwen step produced). Then it parses the plan as JSON - it even tolerates prose with JSON embedded in it - cross-checks it against your brief, clamps every number into sane bounds, fills gaps with the blueprint defaults, and routes 16 outputs out. If a plan field is missing or out of range, the node doesn't throw; it substitutes a safe default and records that in WARNINGS.

The checks it actually runs, grounded in the source:

• Instrumental detection. If your request says "instrumental," "no vocals," "score," "background music" (it even catches the Ukrainian), it forces LYRICS to [Instrumental] and warns if the plan tried to smuggle lyrics in.
• Video duration lock. Set a video length in the brief and it enforces it - a plan that disagrees by more than a second gets overridden with a warning. This is what makes a track actually fit a 60-second video.
• Profile policing. fast_preview caps duration at 60 seconds and forces a single variation; the final profile locks a reproducible seed; A/B variations force an incrementing seed family.
• Bounds. Tempo is clamped 40–240 BPM (defaulting to 122 for Afro House, 120 otherwise), time signature is limited to 2/3/4/6, and the key is validated against the full set of 34 major/minor keys with a blueprint fallback.
• Missing fields. No music_prompt? It builds a safe blueprint prompt. No lyrics on a song request? It drops in a placeholder template. Both come with warnings.

The outputs that matter

MUSIC_PROMPT, LYRICS, SEED, DURATION_SECONDS, BPM, TIME_SIGNATURE, LANGUAGE, KEYSCALE, CFG_SCALE, TEMPERATURE, TOP_P, RECOMMENDED_STEPS, and VARIATION_COUNT all route straight into the ACE-Step checkpoint node - that's the "router" half of the name. VALIDATED_PLAN_JSON (a versioned, schema-1.0 document) feeds the Save MP3 node, and FINAL_GENERATION_CARD is the human-readable one-liner summary.

And WARNINGS - read it. It's the record of every assumption the node had to make, and the difference between a track you trust and one you're puzzled about later.

Installing it

Same as the rest of the pack:

cd ComfyUI/custom_nodes
git clone https://github.com/AntiMatterComfy/antimatter-nodes.git

Restart ComfyUI. The music nodes add no Python dependencies of their own - but the validator is useless without the Qwen plan step upstream and ACE-Step downstream, so expect to install ComfyUI-QwenVL, the ACE-Step 1.5 Turbo AIO checkpoint, and a local Qwen GGUF model to make this chain real.

Troubleshooting

• "Director plan is not valid JSON. Re-run Build Music Plan." This is the error to learn. It means the plan input isn't JSON - usually because you wired it before the LLM step, or the LLM came back with prose instead of a structured plan. Re-run the plan generation, or fix the prompt so the model emits clean JSON.
• You can't type into the inputs. Both are forceInput sockets, not text boxes. Beginners click, see no cursor, and assume the node is broken. Wire the brief and the plan in from upstream nodes.
• It self-heals rather than hard-fails. Missing fields become defaults with warnings instead of crashes - which is exactly why it belongs between an unreliable LLM and an expensive music generation pass.