# How the Guidance Scale Parameter Shapes Music Generation in ACE-Step UI
> Explore how the guidance scale parameter in ACE-Step UI influences music generation. Adjust values for faithful genre reproduction or creative deviation to shape your sound.
- Repository: [fspecii/ace-step-ui](https://github.com/fspecii/ace-step-ui)
- Tags: deep-dive
- Published: 2026-04-29
---
**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`](https://github.com/fspecii/ace-step-ui/blob/main/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`](https://github.com/fspecii/ace-step-ui/blob/main/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:
```tsx
```
### API and Service Layer
The Express route in [`server/src/routes/generate.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/generate.ts) receives the JSON payload defined in [`types.ts`](https://github.com/fspecii/ace-step-ui/blob/main/types.ts) (`GenerationParams.guidanceScale`) and forwards it to the service layer. In [`server/src/services/acestep.ts`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/services/acestep.ts), the `buildGradioArgs` function packs the value as the **8th positional argument** (index 7) for the Gradio `/generation_wrapper` call:
```typescript
// 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`](https://github.com/fspecii/ace-step-ui/blob/main/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:
```tsx
// CreatePanel.tsx – guidance scale slider
```
### Calling the Generation API Directly
Make a direct API request with a high guidance value for strict style adherence:
```typescript
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:
```bash
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:
```typescript
// 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`](https://github.com/fspecii/ace-step-ui/blob/main/CreatePanel.tsx) through the API to `buildGradioArgs`, ultimately reaching [`simple_generate.py`](https://github.com/fspecii/ace-step-ui/blob/main/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`](https://github.com/fspecii/ace-step-ui/blob/main/acestep.ts) falls back to **7.0** if the client omits the field. The standalone Python script ([`simple_generate.py`](https://github.com/fspecii/ace-step-ui/blob/main/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`](https://github.com/fspecii/ace-step-ui/blob/main/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.