What Controls Are Available in Custom Mode for Music Generation in ACE-Step UI

Custom Mode exposes 25+ granular controls—including audio selection, lyric input, style description, vocal configuration, LoRA adapters, musical parameters, and advanced diffusion settings—all managed through React state in CreatePanel.tsx and packed into a GenerationParams payload for the backend.

The ACE-Step UI provides two distinct workflows for AI music creation: Simple Mode for quick generation and Custom Mode for advanced users who need precise control. When you activate Custom Mode in the creation panel, the interface renders a comprehensive control surface that maps directly to the GenerationParams interface sent to the generation API. This article details every available control, its corresponding React state variable, and its implementation location in the fspecii/ace-step-ui repository.

Activating Custom Mode Architecture

Custom Mode is toggled via the customMode state boolean defined in main/components/CreatePanel.tsx (line 1334). When this flag is set to true, the component conditionally renders the full control suite instead of the simplified Simple Mode interface. All parameter values are eventually aggregated into the GenerationParams object inside the handleGenerate function (lines 988-1010), which always includes customMode: true to instruct the backend to respect user-defined values rather than applying simplified defaults.

Audio Selection and Content Controls

The Audio Selection section (lines 1380-1485) manages style transfer and cover generation through four state variables:

• audioTab: Switches between reference and source selection views
• referenceAudioUrl / referenceAudioTitle: Files or library items for style transfer
• sourceAudioUrl / sourceAudioTitle: Audio sources for cover generation mode

For content creation, the Lyrics section (lines 1449-1492) provides the lyrics string state for raw text input and an instrumental boolean that, when enabled, suppresses vocal generation entirely and hides vocal-specific controls.

Style Description and Track Metadata

The Style Description control (lines 1603-1642) accepts free-form musical direction via the style state variable. The optional enhance boolean triggers LLM-driven style enrichment to expand brief descriptions into detailed generation prompts. The Title field (lines 1666-1674) uses simple title state to identify your generated track in the library.

Vocal Language and Gender Configuration

When not in instrumental mode, the panel exposes Vocal Language & Gender controls (lines 1699-1738). The vocalLanguage state accepts ISO language codes (e.g., en, ja, zh), while vocalGender optionally forces male or female vocal characteristics regardless of the base model's default voice.

LoRA Adapter Controls

The optional LoRA Panel (lines 1741-1818) provides model fine-tuning capabilities through four coordinated states:

• loraPath: File path to the LoRA adapter
• loraLoaded: Boolean indicating successful load status
• loraEnabled: Toggle to activate/deactivate without unloading
• loraScale: Strength multiplier (typically 0.0 to 1.0)

These controls allow you to blend custom-trained adapters into the base ACE-Step generation pipeline.

Musical Parameters

Fundamental musical attributes are controlled through the Music Parameters section (lines 1840-1885), which utilizes the EditableSlider component from main/components/EditableSlider.tsx:

• bpm: Integer beats-per-minute (typically 60-180)
• keyScale: Musical key signature (e.g., "C major")
• timeSignature: Meter configuration (e.g., "4/4")

Advanced Generation Settings

The collapsed Advanced Settings panel (lines 1900-2135) exposes 16 additional parameters for fine-grained control:

Timing and Output:

• duration: Track length in seconds
• batchSize: Parallel generation count
• bulkCount: Sequential variation count
• audioFormat: Output file format selection

Diffusion Configuration:

• inferenceSteps: Number of diffusion denoising steps
• guidanceScale: Classifier-free guidance strength
• shift: Diffusion schedule shift parameter
• inferMethod: Deterministic versus stochastic inference selection

LLM and Seeding:

• lmBackend: Language model inference backend
• lmModel: Specific model checkpoint for lyrics/captions
• seed: Fixed random seed for reproducibility
• randomSeed: Boolean to enable random seeding
• thinking: Chain-of-thought reasoning toggle

Expert Language Model Parameters

Expanded via the LM Parameters section (lines 2157-2230), these five controls specifically tune the 5 Hz lyric generation model:

• lmTemperature: Controls randomness in token selection
• lmCfgScale: Guidance scale for lyric adherence
• lmTopK: Token filtering by probability mass
• lmTopP: Nucleus sampling threshold
• lmNegativePrompt: Excluded concepts for lyric generation

Implementing Custom Mode in Code

When users click Generate, the handleGenerate function constructs the complete parameter payload. Here is how these controls flow from UI state to API call:

import { generateApi } from '../services/api';
import { GenerationParams } from '../types';
import { useAuth } from '../context/AuthContext';

// Inside CreatePanel.tsx handleGenerate (lines 988-1010)
const handleGenerate = async () => {
  const params: GenerationParams = {
    customMode: true,
    referenceAudioUrl,
    sourceAudioUrl,
    lyrics: instrumental ? '' : lyrics,
    style,
    enhance,
    title,
    vocalLanguage,
    vocalGender,
    bpm,
    keyScale,
    timeSignature,
    loraEnabled,
    loraScale,
    inferenceSteps,
    guidanceScale,
    lmTemperature,
    lmTopK,
    // ... additional parameters
  };

  // API implementation in main/services/api.ts
  await generateApi.createSong(params, authToken);
};

The generateApi.createSong method posts this payload to the backend, where the ACE-Step pipeline reads the customMode: true flag to apply your specific parameter choices rather than simplified defaults.

Summary

• Mode Toggle: customMode boolean switches between Simple and Custom workflows in CreatePanel.tsx
• Audio & Lyrics: Controls for reference/source audio URLs, lyric text, and instrumental mode toggle
• Style & Metadata: Free-form style description with LLM enhancement and track title fields
• Vocal Settings: Language selection (ISO codes) and gender forcing when not in instrumental mode
• LoRA Integration: Load, enable, and scale LoRA adapters for model fine-tuning
• Musical Parameters: BPM, key signature, and time signature controls using EditableSlider
• Advanced Controls: Duration, batch size, inference steps, guidance scale, diffusion shift, and LLM backend selection
• Expert LM Tuning: Temperature, CFG scale, top-k/top-p filtering, and negative prompting for the lyric model
• Payload Assembly: All values aggregate into GenerationParams and send via generateApi.createSong

Frequently Asked Questions

What is the difference between Simple Mode and Custom Mode in ACE-Step UI?

Simple Mode uses backend defaults with minimal user input, while Custom Mode exposes the full parameter surface defined in main/components/CreatePanel.tsx. When customMode is set to true, the UI renders 25+ additional controls for audio selection, vocal configuration, LoRA adapters, and diffusion parameters that are packed into the GenerationParams object sent to the generation API.

How do I enable LoRA adapters in Custom Mode?

Navigate to the LoRA Panel in the Custom Mode interface (lines 1741-1818), where you can specify a loraPath to load your adapter file. Once loaded, use the loraEnabled toggle to activate the adapter without unloading it, and adjust the loraScale slider to control the blending strength between the base model and your fine-tuned weights.

Can I use reference audio and custom lyrics simultaneously in Custom Mode?

Yes. The referenceAudioUrl (for style transfer) and lyrics states are independent controls located in different sections of CreatePanel.tsx (lines 1380-1485 and 1449-1492 respectively). You can provide a reference audio to influence the instrumental style while simultaneously entering custom lyrics in the text field, provided you have not enabled the instrumental toggle.

What do the Expert LM Parameters control?

The LM Parameters section (lines 2157-2230) configures the 5 Hz lyric and caption generation model through lmTemperature (randomness), lmCfgScale (guidance strength), lmTopK/lmTopP (token filtering), and lmNegativePrompt (content exclusion). These settings specifically affect how the language model generates or refines lyrics based on your style description, separate from the audio diffusion parameters.

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