Music Generation Modes in ACE-Step UI: Simple vs. Custom Explained

ACE-Step UI provides two distinct music generation modes—Simple Mode for description-driven automatic creation and Custom Mode for full manual control over lyrics, style, BPM, and other audio parameters.

The fspecii/ace-step-ui open-source repository implements a React-based interface that exposes these dual workflows for the ACE-Step music generation model. Understanding these music generation modes helps you choose between rapid prototyping with minimal input or granular artistic control over every aspect of your generated track.

Simple Mode: Description-Driven Generation

Simple Mode operates as a "describe-and-generate" workflow. You provide only a short text description of the desired song—such as "an upbeat pop song about summer adventures"—and the model automatically determines all other parameters including lyrics, style tags, tempo, and key signature.

In components/CreatePanel.tsx (lines 136-144), the mode state is managed through a boolean hook:

const [customMode, setCustomMode] = useState(true);

When customMode is set to false, the interface renders the simplified Simple panel, hiding all advanced parameter fields and displaying only the description textarea. As documented in the README (lines 80-86), this mode delegates all artistic decisions to the underlying model.

Custom Mode: Full Parameter Control

Custom Mode exposes every available generation parameter for fine-grained artistic direction. This includes direct lyric input, style tags, duration in seconds, BPM settings, key signature selection, and audio-cover strength controls.

The UI activates Custom Mode when customMode is true. In this state, CreatePanel.tsx renders the full parameter form with all advanced options visible (lines 140-144). According to the README documentation (lines 87-97), Custom Mode provides complete control over the musical output, allowing you to specify exact lyrical content and stylistic boundaries that the model must follow.

How the UI Switches Between Modes

The mode toggle is implemented as a boolean state managed in CreatePanel.tsx. The interface includes dedicated buttons that update the customMode state:

// Inside CreatePanel.tsx – toggle button (simplified)
<button
  className={customMode ? 'active' : ''}
  onClick={() => setCustomMode(false)}   // Simple Mode
>
  Simple
</button>
<button
  className={!customMode ? 'active' : ''}
  onClick={() => setCustomMode(true)}    // Custom Mode
>
  Custom
</button>

Clicking Simple sets customMode to false, collapsing the interface to show only the description field. Selecting Custom sets customMode to true, expanding the form to reveal all generation parameters. This state drives the conditional rendering logic that determines which input fields appear in the creation panel.

Backend Implementation and API Handling

Both modes utilize the same backend endpoint (/api/generate), but the payload structure differs based on the selected mode. In App.tsx (lines 765-791), the generation request wrapper adds mode-specific tags:

tags: params.customMode ? ['custom'] : ['simple']

When customMode is true, the request includes the custom tag; when false, it receives the simple tag. The server route in server/src/routes/generate.ts receives this payload and processes the request accordingly:

const tags = params.customMode ? ['custom'] : ['simple'];
// The `taskType` is orthogonal and lives inside `params.taskType`

The customMode flag determines which parameters the backend expects and validates.

Practical Code Examples

Sending Generation Requests

When calling the generation API, the customMode boolean determines which parameters are required:

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

// Simple mode – only description
await generateApi({
  customMode: false,
  songDescription: 'An upbeat pop song about summer adventures',
  // other fields are omitted because the UI will fill defaults
});

// Custom mode – full control
await generateApi({
  customMode: true,
  lyrics: '[Verse] ...',
  style: 'pop, energetic, synth',
  duration: 120,
  bpm: 128,
  keyScale: 'C major',
  // …plus any of the advanced options from the UI
});

Both requests target the same endpoint, but the backend interprets the customMode flag to determine processing logic.

Switching Modes in React Components

To programmatically control the generation mode from within the React component tree:

import { useState } from 'react';

const ModeToggle = () => {
  const [customMode, setCustomMode] = useState(false);
  
  return (
    <div className="mode-selector">
      <button 
        onClick={() => setCustomMode(false)}
        disabled={!customMode}
      >
        Simple Mode
      </button>
      <button 
        onClick={() => setCustomMode(true)}
        disabled={customMode}
      >
        Custom Mode
      </button>
    </div>
  );
};

Summary

• Simple Mode provides rapid music generation through descriptive prompts alone, with the customMode flag set to false in components/CreatePanel.tsx.
• Custom Mode enables complete artistic control over lyrics, style, tempo, and key, activated when customMode is true.
• Both modes share the /api/generate endpoint in server/src/routes/generate.ts, differentiated by tags added in App.tsx (lines 765-791).
• The UI conditionally renders input fields based on the boolean state defined in components/CreatePanel.tsx (lines 136-144).

Frequently Asked Questions

Can I switch between Simple and Custom modes after starting a generation?

No, the mode is determined at the moment the generation request is sent through the customMode parameter. Once the API call initiates with generateApi, the mode tag is attached and the backend processes the request according to that initial selection. To change modes, you must cancel the current operation and submit a new request with the updated customMode value.

Do Simple and Custom modes use different API endpoints?

No, both modes utilize the same /api/generate endpoint defined in server/src/routes/generate.ts. The distinction occurs through the customMode boolean in the request payload and the corresponding tags (['custom'] or ['simple']) added in App.tsx. The backend logic branches based on this flag rather than routing to separate endpoints.

What parameters are required when using Custom Mode?

Custom Mode requires you to specify the generation parameters that Simple Mode auto-populates, including lyrics, style, duration, bpm, and keyScale. The CreatePanel.tsx component renders input fields for these values when customMode is true. While some fields may have default values, the mode expects explicit artistic direction for optimal results.

Is there a performance difference between Simple and Custom modes?

The performance characteristics depend on the complexity of the generated audio rather than the mode itself. Simple Mode may sometimes produce shorter or simpler outputs based on the model's interpretation of your description, while Custom Mode allows you to specify longer durations and more complex structures that require additional processing time. Both modes handle the initial request with identical latency in the App.tsx handler.

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