How the Guidance Scale Parameter Shapes Music Generation in ACE-Step UI

The guidance scale parameter determines how strictly the ACE-Step diffusion model adheres to your text prompt, with higher values forcing faithful genre reproduction while lower values permit creative deviation.

The guidanceScale (also known as CFG scale) is the primary control for prompt adherence in the ACE-Step music generation pipeline. This article examines how this parameter propagates through the fspecii/ace-step-ui codebase and how different values affect the musical output.

What the Guidance Scale Parameter Controls

In diffusion-based music generation, the guidance scale implements classifier-free guidance (CFG) to balance conditional and unconditional sampling. According to the repository's implementation, this value typically ranges from 1 to 15, though the underlying DiT model can accept values up to approximately 20.

Low Guidance (1.0 – 4.0)

At low values, the model treats your prompt as a loose suggestion. The diffusion sampler prioritizes exploration over precision, producing highly diverse outputs that may deviate significantly from the requested genre or style. Use this range when you want surprising textures and experimental results.

Medium Guidance (5.0 – 9.0)

This range offers the default balance used by most ACE-Step UI users. The model follows the caption (for example, "bright synth pop") while retaining enough randomness to generate unique musical phrases. The slider in CreatePanel initializes to 9.0, placing users in this optimal zone by default.

High Guidance (10.0 – 15.0+)

High values force the sampler to stay extremely close to the prompt. Results become more deterministic and faithful to specific styles (such as "70s funk with slap-bass"), though they may lose subtle musical nuance and sound over-constrained. The standalone simple_generate.py script defaults to 10.0 when used independently.

Technical Implementation: From UI to Model

The guidanceScale value maintains a single source of truth as it travels from user interface to the DiT model, though defaults vary by layer to ensure graceful fallbacks.

Frontend Configuration

In components/CreatePanel.tsx, the React state manages the slider value. When users adjust the control, setGuidanceScale updates the state that will be serialized into the API request:

<Slider
  min={1}
  max={15}
  step={0.1}
  value={guidanceScale}
  onChange={setGuidanceScale}
  ariaLabel={t('guidanceScale')}
/>

API and Service Layer

The Express route in server/src/routes/generate.ts receives the JSON payload defined in types.ts (GenerationParams.guidanceScale) and forwards it to the service layer. In server/src/services/acestep.ts, the buildGradioArgs function packs the value as the 8th positional argument (index 7) for the Gradio /generation_wrapper call:

// Inside server/src/services/acestep.ts
const args = await buildGradioArgs(params);
console.log('Gradio args[7] (guidanceScale):', args[7]);

If the client omits the field, the backend falls back to 7.0 via params.guidanceScale ?? 7.0.

Python Execution

The server/scripts/simple_generate.py script receives the value via command line, overriding its default of 10.0. The argument ultimately reaches the AceStepHandler where it functions as the DiT classifier-free guidance scale, weighting conditional logits against unconditional ones during diffusion sampling.

Practical Code Examples

Adjusting the Slider in the UI

Modify the guidance scale in the React frontend to change the generation behavior:

// CreatePanel.tsx – guidance scale slider
<Slider
  min={1}
  max={15}
  step={0.1}
  value={guidanceScale}
  onChange={setGuidanceScale}
  ariaLabel={t('guidanceScale')}
/>

Calling the Generation API Directly

Make a direct API request with a high guidance value for strict style adherence:

import { generateApi } from '@/services/api';

await generateApi.startGeneration(
  {
    customMode: false,
    songDescription: 'Energetic synth-pop track',
    instrumental: false,
    guidanceScale: 12.0,          // Strong prompt adherence
    inferenceSteps: 10,
    batchSize: 1,
  },
  userToken,
);

Using the CLI Script

Generate experimental, loosely-guided music via the command line with a low guidance value:

python server/scripts/simple_generate.py \
  --prompt "chill lo-fi hip-hop beat" \
  --guidance-scale 4.5 \
  --infer-steps 8 \
  --audio-format mp3 \
  --output-dir ./outputs

Debugging the Gradio Arguments

Inspect the exact value passed to the Python layer during development:

// Inside server/src/services/acestep.ts
const args = await buildGradioArgs(params);
console.log('Gradio args[7] (guidanceScale):', args[7]);

Summary

• Guidance scale (also CFG scale) is the primary knob for controlling prompt fidelity versus creative diversity in ACE-Step UI.
• Low values (1-4) produce experimental, diverse outputs that may deviate from the prompt.
• Medium values (5-9) balance adherence and creativity, with the UI defaulting to 9.0.
• High values (10-15+) enforce strict prompt compliance, generating deterministic results that closely match the requested style.
• The parameter flows unchanged from CreatePanel.tsx through the API to buildGradioArgs, ultimately reaching simple_generate.py as the DiT classifier-free guidance weight.

Frequently Asked Questions

What is the default guidance scale in ACE-Step UI?

The React frontend initializes the slider to 9.0, while the backend service layer in acestep.ts falls back to 7.0 if the client omits the field. The standalone Python script (simple_generate.py) defaults to 10.0 when used independently via command line.

How does the guidance scale technically affect the diffusion process?

According to the implementation in fspecii/ace-step-ui, the value functions as the classifier-free guidance (CFG) scale within the DiT inference. It weights the conditional logits (driven by your text prompt) against unconditional logits during sampling. A higher weight forces the conditional logits to dominate, producing audio that strictly follows the prompt description.

Can I set the guidance scale above 15?

While the UI slider limits the range to 1–15, the underlying ACE-Step core supports values up to approximately 20. However, values above 15 typically produce diminishing returns and may result in over-constrained, less musically interesting outputs.

What happens if I omit the guidance scale in my API request?

The backend service in server/src/services/acestep.ts uses the nullish coalescing operator to default to 7.0 when the field is missing from the GenerationParams object: params.guidanceScale ?? 7.0. This ensures the generation pipeline receives a valid numeric value even when the client does not explicitly specify one.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}