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

> Discover how Simple Mode generates music in ACE-Step UI. Transform text descriptions into music with tempo, key, and duration controls. Learn more now.

- Repository: [fspecii/ace-step-ui](https://github.com/fspecii/ace-step-ui)
- Tags: deep-dive
- Published: 2026-04-29

---

**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`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/generate.ts), the route handler enforces this requirement:

```ts
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`](https://github.com/fspecii/ace-step-ui/blob/main/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`](https://github.com/fspecii/ace-step-ui/blob/main/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:

```ts
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:

```ts
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`:

```tsx
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:

```ts
// 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:

```ts
// 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`](https://github.com/fspecii/ace-step-ui/blob/main/server/src/routes/generate.ts) requires `songDescription` when `customMode` is false.
- The service layer in [`acestep.ts`](https://github.com/fspecii/ace-step-ui/blob/main/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`](https://github.com/fspecii/ace-step-ui/blob/main/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.