ACE-Step Format Sample

Every generation model rewards well-formed input, and ACE-Step is no exception - a messy prompt and half-written lyrics in get a messy song out. Format Sample is the pack's tidy-up step: you feed it a rough caption and rough lyrics, it runs them through the ACE-Step language model, and it hands back a structured formatted_caption, formatted_lyrics, and formatted_metadata JSON - ready to feed into Text to Music.

Think of it as prompt-engineering as a node. It's the difference between typing "song about driving" straight into Text to Music and sending in a caption that's been expanded into something the model can actually render, with lyrics that have consistent structure. It's also the right place to enforce constraints you care about: via user_metadata you can pass a JSON object like {"bpm": 120, "duration": 60} and the formatter will fold those into the output spec.

How it works

It loads the ACE-Step language model (the same acestep-5Hz-lm-* family the generation nodes use) and calls the underlying format_sample function with your caption, lyrics, and optional metadata. Notably, the DiT never runs - like Create Sample, this is a language-model-only node, so it's cheap and fast. The output metadata JSON includes the caption, lyrics, and detected bpm, duration, keyscale, language, and timesignature - effectively the full spec the generation node will consume.

The inputs that matter

• caption - your rough description. More detail in, more useful formatting out.
• lyrics - the raw lyrics to structure. Can be empty if it's an instrumental.
• user_metadata - optional JSON, {} by default. This is your constraint channel: {"bpm": 120, "duration": 60}.
• checkpoint_dir / lm_model_path / device - the standard model-loading trio.

Outputs: formatted_caption, formatted_lyrics, formatted_metadata - all strings, all wired into Text to Music's corresponding inputs.

Install

Nothing new for this node - it's part of the shared pack install:

git clone https://github.com/ACE-Step/ACE-Step-1.5.git
cd ACE-Step-1.5 && pip install -e .
cd ComfyUI/custom_nodes
git clone https://github.com/kana112233/ComfyUI-kaola-ace-step.git
cd ComfyUI-kaola-ace-step && pip install -r requirements.txt
huggingface-cli download ACE-Step/Ace-Step1.5 --local-dir ComfyUI/models/Ace-Step1.5

Restart ComfyUI after installing.

Where people get burned

The main gotcha is malformed JSON in user_metadata. The node silently swallows a parse error ({}), which means your carefully-entered BPM constraint just... doesn't apply, with no error message. Validate the JSON in an editor before pasting. Beyond that, the disappointment people hit is expecting formatting to fix a bad idea - it polishes language, it doesn't invent direction. A vague caption comes back as a more polished vague caption. Give it something to work with and this node becomes the quiet upgrade that makes your generations noticeably more consistent.