ACE Song Timeline Conditioning (Nukun)

The classic ACE-Step complaint: one prompt, one coherent but flat 60-second wall of music. Verse doesn't sound different from chorus, the bridge is missing, the whole thing is a vibe rather than a song. ACE Song Timeline Conditioning (Nukun) is the structural fix. It turns your sectioned lyrics into time-regional ACE-Step 1.5 conditioning, so each section of the song only conditions its own slice of the audio. This is the execution half of the pack's ACE pipeline - the ACE Song Variation Director (Nukun) plans the arrangement, this node renders it.

How it works

The trick is that ACE-Step 1.5's conditioning carries audio_codes - the token sequence for the audio. This node reads those codes out of an already-generated conditioning, divides them up among your song sections, then re-encodes each section's tags and lyrics as a regional conditioning that is masked to its time window. The math is friendly: 5 audio codes per second, 5 latents per audio code, so 25 latents per second of song. Each section's region gets a cosine crossfade into its neighbors (transition_seconds, default 1s), so you get a real fade between verse and chorus, not a brick wall.

Two parts of the mechanism matter for beginners. First, section durations aren't magic: the node allocates the available audio codes proportionally to each section's lyric word count (weighted by max(1, words/12)), floored at minimum_section_seconds (default 4s). Second, a single-section lyric is treated as a pass-through - no regional encoding, base conditioning at full strength - so you can drop this node in early and it won't fight you.

Inputs that matter

• base_conditioning - this is the load-bearing one. It must be an ACE-Step 1.5 conditioning that carries generated audio_codes. The error message tells you exactly what to do: "requires generated ACE-Step 1.5 audio_codes; enable generate_audio_codes and place the node after ACEtricks compression." So this node sits downstream of the ACEtricks encode step, not before it.
• clip - the ACE-Step 1.5 text encoder, used to encode each section's tag block and lyrics.
• tags and lyrics - the fixed style tags, and lyrics with [Verse]/[Chorus]-style headers. Section detection handles headers or falls back to stanza detection, max 32 sections.
• plan_json - optional, and the thing that makes the two-node pipeline click. Feed it the Director's plan_json and it takes precedence over the lyrics box, so you don't copy-paste the rewritten text.
• base_strength (0.35) vs region_strength (1.0) - the background song-conditioning volume vs. each section's emphasis. Leave region_strength high.
• duration_overrides - exact per-section lengths, one per line: S01=8 or A01=6. The node rounds to the 5-codes-per-second grid and warns you if you asked for something un-roundable.

Outputs

conditioning is what you care about - it wires into the sampler's positive path. The other three are diagnostics and reproducibility: timeline_json (a full per-section timeline with start/end in seconds, code indices, and latent indices), report (what got allocated, warnings included), and duration_seconds.

Install and gotchas

Same pack as the Director, so one install covers both:

cd ComfyUI/custom_nodes
git clone https://github.com/OnekoSL/Nukun_ComfyUI_Nodes.git

Restart ComfyUI. No heavy dependencies beyond what ComfyUI already ships - this node is pure torch math plus the CLIP encode path, so no Ollama, no extra models.

The failure modes are mostly placement. If base_conditioning was already regionalized (has mask/area metadata) you get a hard "already regionalized" error - feed it the raw encoded conditioning, not one you've already fiddled with. If your duration_overrides don't add up to the available audio codes, it refuses rather than silently inventing time. And remember the honest caveat from the wider ACE-Step picture: instrumentals respond beautifully to this structure; vocals are still the model's weak suit, and conditioning fixes arrangement, not pronunciation. If a word is being pronounced wrong, that's a lyrics-timing problem you fix at the encode stage, not here.