deep-dive

Advanced Generation Parameters in ACE-Step UI: A Technical Deep Dive

April 29, 2026 fspecii/ace-step-ui ↗

ACE-Step UI exposes 19 advanced generation parameters—including custom diffusion timesteps, CFG interval scheduling, score scaling, and chain-of-thought toggles—that map directly to the backend GenerationParams interface in server/src/services/acestep.ts and are controlled via the Advanced Settings panel in main/components/CreatePanel.tsx.

The fspecii/ace-step-ui repository provides a React-based interface for the ACE-Step audio generation model, offering power users fine-grained control over the diffusion pipeline through its Advanced Settings section. These parameters are forwarded from the frontend to a Gradio-powered backend, allowing precise manipulation of sampling behavior, classifier-free guidance, and language model inference.

Core Advanced Parameters

The advanced generation parameters are defined in the GenerationParams interface at server/src/services/acestep.ts (lines 94-242) and surfaced in the UI through dedicated controls in CreatePanel.tsx. Below is the complete parameter reference organized by functional category.

Diffusion and Sampling Controls

These parameters directly modify the diffusion sampling schedule and noise injection strategy:

Classifier-Free Guidance (CFG) Configuration

These controls fine-tune when and how classifier-free guidance applies during the diffusion process:

Audio Output and Metadata

Control the format and auxiliary data returned with generated audio:

Language Model and Chain-of-Thought

These parameters configure the behavior of the internal language model (LM) responsible for lyric and metadata generation:

Experimental and Debug Features

Parameters for automated generation loops and debugging:

Data Flow: From UI to Backend

When a user modifies these settings in the Advanced Settings section of the Create Panel, the React state variables (e.g., customTimesteps, scoreScale) are collected into a single payload object. This object is typed as GenerationParams in server/src/services/acestep.ts and sent via the frontend API wrapper at main/services/api.ts (lines 36-79) to the /generation_wrapper Gradio endpoint.

The complete JSON payload structure sent to the backend includes both basic and advanced fields:

{
  "customMode": false,
  "instrumental": false,
  "vocalLanguage": "en",
  "duration": -1,
  "bpm": 0,
  "keyScale": "",
  "timeSignature": "",
  "inferenceSteps": 20,
  "guidanceScale": 7.0,
  "batchSize": 1,
  "randomSeed": true,
  "seed": -1,
  "audioFormat": "mp3",
  "inferMethod": "ode",
  "shift": 3.0,
  "customTimesteps": "",
  "scoreScale": 0.5,
  "cfgIntervalStart": 0.0,
  "cfgIntervalEnd": 1.0,
  "useAdg": false,
  "useCotMetas": true,
  "useCotCaption": true,
  "useCotLanguage": true,
  "autogen": false,
  "constrainedDecodingDebug": false,
  "allowLmBatch": true,
  "getScores": false,
  "getLrc": false,
  "lmBatchChunkSize": 8,
  "trackName": null,
  "completeTrackClasses": []
}

Programmatic Usage Example

To invoke the generation API with advanced parameters programmatically, construct a payload matching the GenerationParams interface and pass it to the songsApi.createSong method:

import { songsApi } from './services/api';

const generationPayload = {
  // Basic parameters
  customMode: true,
  songDescription: '',
  lyrics: '',
  style: '',
  title: 'My Experimental Track',
  ditModel: 'acestep-v15-turbo-shift3',
  instrumental: false,
  vocalLanguage: 'en',
  duration: 120,
  bpm: 120,
  keyScale: 'C',
  timeSignature: '4/4',
  
  // Advanced generation parameters
  customTimesteps: '0,10,20,30,40,50',
  scoreScale: 0.8,
  cfgIntervalStart: 0.2,
  cfgIntervalEnd: 0.9,
  shift: 4.0,
  inferMethod: 'sde',
  audioFormat: 'flac',
  useAdg: true,
  useCotMetas: true,
  useCotCaption: false,
  useCotLanguage: true,
  autogen: false,
  allowLmBatch: true,
  lmBatchChunkSize: 12,
  trackName: 'ambient',
  completeTrackClasses: ['ambient', 'drone'],
};

async function runGeneration() {
  const { song } = await songsApi.createSong(generationPayload, '<YOUR_JWT>');
  console.log('Generated song ID:', song.id);
}

runGeneration();

Each key in the payload corresponds one-to-one with the fields defined in server/src/services/acestep.ts, ensuring type-safe transmission from the React frontend to the Python Gradio backend.

Summary

  • 19 advanced parameters are available in ACE-Step UI, exposing deep control over the diffusion pipeline.
  • Diffusion controls include customTimesteps, shift, inferMethod (ODE/SDE), and scoreScale.
  • CFG tuning is handled via cfgIntervalStart, cfgIntervalEnd, and the useAdg adaptive flag.
  • Chain-of-Thought settings (useCotMetas, useCotCaption, useCotLanguage) configure the internal language model's reasoning capabilities.
  • Implementation follows a clear path: CreatePanel.tsx (UI state) → api.ts (HTTP client) → acestep.ts (backend typing) → Gradio wrapper.

Frequently Asked Questions

What is the difference between ODE and SDE inference methods in ACE-Step UI?

ODE (Ordinary Differential Equation) sampling is deterministic, producing the same output given identical seeds and parameters, which is ideal for reproducible results. SDE (Stochastic Differential Equation) sampling introduces randomness during the diffusion process, which can increase audio variety and perceived "creativity" at the cost of deterministic output.

How do the CFG Interval Start and End parameters work?

These parameters control when classifier-free guidance is active during the diffusion timeline. CFG Interval Start (default 0.0) specifies the fraction of total steps at which guidance begins, while CFG Interval End (default 1.0) determines when it stops. Setting these to values like 0.2 and 0.9 restricts guidance to the middle portion of generation, potentially reducing artifacts while maintaining prompt adherence.

What are the Chain-of-Thought parameters used for?

The Chain-of-Thought (CoT) toggles (useCotMetas, useCotCaption, useCotLanguage) enable intermediate reasoning steps in the internal language model. When enabled, the LM generates meta-information, rewrites captions for consistency, and performs language-level reasoning before producing the final audio, which improves lyric alignment and semantic coherence but may increase generation time.

How does the Custom Timesteps parameter override the default schedule?

The Custom Timesteps parameter accepts a comma-separated string of integers (e.g., "0,10,20,30,40,50") that replaces the default linear diffusion schedule. This allows expert users to implement custom noise schedules—such as quadratic spacing or specific checkpoint intervals—directly in the customTimesteps field defined at line 94 of server/src/services/acestep.ts.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →