How Simple Mode Works for Music Generation in ACE-Step UI

Simple Mode generates music by accepting a brief text description instead of detailed lyrics or style prompts, converting that description into a model caption while preserving access to tempo, key, and duration controls.

Simple Mode provides a streamlined interface for creating tracks in the ACE-Step UI open-source project. When enabled, it hides complex input fields and uses a single songDescription field to drive the generation pipeline. This approach simplifies the user experience while maintaining full access to the underlying AI music generation capabilities.

Simple Mode vs. Custom Mode

The ACE-Step UI offers two distinct generation workflows. Custom Mode exposes detailed controls for lyrics, style prompts, reference audio, and titles. Simple Mode condenses these into a single text field, making it ideal for users who want quick results from a short concept rather than fully structured inputs.

The mode toggle is controlled by the boolean customMode state variable. When customMode equals false, the interface switches to Simple Mode and reveals only the songDescription input field in the Create Panel.

The Simple Mode Execution Flow

UI Layer and State Management

In the React frontend, the Create Panel component manages the Simple Mode interface through the songDescription state variable. When customMode is set to false, all custom-mode fields—including lyrics, style inputs, and reference audio uploaders—are hidden from view.

The user interacts solely with the songDescription text field, which captures the conceptual description of the desired track.

Request Validation

Before processing, the server validates that Simple Mode requests contain the required description. In server/src/routes/generate.ts, the route handler enforces this requirement:

if (!customMode && !songDescription) {
  res.status(400).json({ error: 'Song description required for simple mode' });
  return;
}

This check ensures that the songDescription parameter is present when customMode is disabled, preventing empty prompts from reaching the generation service.

Parameter Construction

The TypeScript type system defines the Simple Mode contract in types.ts. The GenerationParams interface declares both customMode: boolean and songDescription?: string, establishing the optional yet conditionally required nature of the description field.

When building the request payload, the frontend sends these parameters alongside common music settings like BPM, key signature, duration, and the instrumental flag.

Building the Gradio Call

The critical transformation occurs in server/src/services/acestep.ts, where the service prepares the 50-argument array for the ACE-Step backend's Gradio endpoint. The first argument—the prompt—is constructed differently based on the mode:

const caption = params.style || 'pop music';
const prompt = params.customMode ? caption : (params.songDescription || caption);

In Simple Mode, the songDescription value supplants the style-based caption, becoming the primary text prompt that drives the music generation model.

Handling Musical Parameters

Simple Mode preserves access to generation parameters while forcing lyrical content to empty strings when appropriate. The service constructs the lyrics field as:

params.instrumental ? '' : (params.lyrics || '')

This ensures that non-instrumental Simple Mode generations receive empty lyrics rather than undefined values, while instrumental flags and tempo controls (BPM, key, duration) pass through unchanged.

Implementation Examples

Frontend Request Structure

To trigger Simple Mode from the client side, set customMode to false and provide the songDescription:

await fetch('/api/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    customMode: false,
    songDescription: 'Upbeat synth pop about sunrise',
    instrumental: false,
    bpm: 120,
    keyScale: 'C',
    duration: 30,
  }),
});

Server-Side Validation

The API route enforces Simple Mode requirements before delegation:

// From server/src/routes/generate.ts
if (!customMode && !songDescription) {
  res.status(400).json({ error: 'Song description required for simple mode' });
  return;
}
const params = {
  customMode,
  songDescription,
  // ...other fields passed through unchanged
};

Service Layer Processing

The ACE-Step service adapts the parameters for the Gradio wrapper:

// From server/src/services/acestep.ts
const caption = params.style || 'pop music';
const prompt = params.customMode ? caption : (params.songDescription || caption);
// prompt now contains the short description for Simple Mode

Summary

• Simple Mode uses songDescription as a streamlined alternative to full caption engineering in ACE-Step UI.
• The customMode boolean flag controls UI visibility and server-side validation logic.
• Server validation in server/src/routes/generate.ts requires songDescription when customMode is false.
• The service layer in acestep.ts maps the description directly to the Gradio prompt parameter.
• Musical parameters (BPM, key, duration) and instrumental flags function identically in both modes.

Frequently Asked Questions

What happens if I submit a Simple Mode request without a description?

The server returns a 400 error with the message "Song description required for simple mode." This validation occurs in server/src/routes/generate.ts before any processing begins.

Does Simple Mode support instrumental-only generation?

Yes. Simple Mode respects the instrumental flag and other musical parameters including BPM, key signature, and duration. When instrumental is enabled, the system passes an empty string for the lyrics field to the generation model.

How does Simple Mode differ from Custom Mode at the API level?

Both modes use the same /api/generate endpoint and underlying Gradio wrapper. The only difference is the source of the text prompt: Custom Mode uses the style field and explicit lyrics, while Simple Mode substitutes the songDescription field as the primary prompt caption.

Can I switch between modes after starting a generation job?

No. The customMode flag is evaluated at request time to determine validation rules and prompt construction. Each generation job is stateless; changing modes requires submitting a new request with the appropriate parameters.

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