ACE-Step Wrangler
March 15, 2026 · View on GitHub
ACE-Step Wrangler is a DAW-style web UI for AceStep 1.5, an AI music generation model. It replaces the default Gradio interface with a dark, musician-friendly frontend.
Launching
uv run wrangler
On multi-GPU systems, Wrangler auto-selects the GPU with the most free VRAM. To override:
uv run wrangler --gpu 1 # use GPU 1
ACESTEP_GPU=1 uv run wrangler # equivalent via env var
Priority: --gpu flag > ACESTEP_GPU env > auto-select > CUDA default. The startup banner shows which GPU was chosen and how much VRAM is free.
Open http://localhost:7860 in your browser. AceStep must finish loading its models before the first generation — the first run after startup may take a minute.
Layout
The interface is a three-column layout with a persistent strip across the bottom.
| Column | Contents |
|---|---|
| Left | Style (Create), Rework controls, Analyze controls, or Train wizard — depends on the active mode |
| Centre | My Lyrics / AI Lyrics / Instrumental sub-tabs (Create & Rework), analysis content (Analyze), or training monitor (Train); result cards appear below after generation |
| Right | Controls — duration, quality, generate button (Create/Rework/Analyze) or Training Config (Train) |
| Bottom | Now Playing bar — always visible; waveform timeline appears above it in Rework mode |
Switch between Create, Rework, Analyze, and Train modes using the tab bar at the top of the centre panel.
Create Mode
Style Panel (left column)
Build a style description by combining tags and free text. The assembled prompt is shown in the Style prompt preview at the bottom of the panel.
- Genre / Mood tags — click to toggle; multiple selections are combined
- Key — root note + major/minor
- BPM — beats per minute; leave blank for the model to decide
- Time signature — 4/4, 3/4, 6/8, 5/4, 7/8
- Custom description — free-text override or addition; mixed with any active tags
Lyrics Panel (centre column)
Three sub-tabs — My Lyrics, AI Lyrics, and Instrumental — select what kind of content to generate. Each tab independently remembers its last generated song — you can have a different result in each and rework any of them.
My Lyrics (default)
Write or paste your own lyrics. Use [Section] headers on their own line to mark song structure:
[Verse 1]
Lines go here
[Chorus]
Lines go here
Actions in the toolbar:
- Language selector (EN / ZH / JA / …) — tells AceStep the vocal language
- Load lyrics — load lyrics from a
.txtor.lrcfile (you can also drag and drop onto the panel) - Clear — empty the textarea
A character count and a lyrics-too-long warning appear as you type. If the lyrics are likely too long for the chosen duration, adjust the Duration slider before generating.
AI Lyrics
Let AceStep's language model write the lyrics for you. The tab has two fields:
- Song description — describe the mood, topic, or style of the song you want (e.g. "upbeat summer anthem about road trips"). This is combined with your Style panel settings and sent to the model.
- Generated lyrics — a read-only display that fills in after generation. You can select and copy the text to paste into My Lyrics for editing.
The language selector controls which language the AI generates vocals in.
Instrumental
AceStep generates a purely instrumental track from your style settings — no lyrics are generated or expected.
Controls Panel (right column)
| Control | What it does |
|---|---|
| Duration | Target length of the output. Use Auto to estimate from your lyrics and tempo. |
| Strictly follow lyrics | Loose → model interprets freely; Strict → model tracks every syllable |
| Creativity | Restrained → stays close to the style prompt; Wild → more unexpected results |
| Quality | Raw → fast (fewer steps); Polished → slower, more refined |
| ▶ Generate | Submit the job. Keyboard shortcut: Ctrl/Cmd + Enter |
Per-Tab Results
While generating, an elapsed timer and a Cancel button appear in the bottom bar.
On completion, result cards appear at the bottom of the active tab's content area in the Lyrics panel. Each card has a custom audio player (with a save button for quick download) and download links for the audio file and a JSON metadata file.
Each tab holds its own result independently — you can generate from My Lyrics, switch to AI Lyrics, generate again, and switch back without losing either result. Switching to Rework auto-loads from whichever tab is active.
Now Playing Bar
A compact strip at the bottom of the screen shows which tab is currently playing and provides transport controls (Rewind, Play/Pause, Stop, scrubber, Save). It stays active across tab switches — start a song in AI Lyrics, switch to My Lyrics, and the Now Playing bar keeps tracking what is playing.
Rework Mode
Rework takes an existing audio file and transforms part or all of it.
Loading Audio
- Drag and drop an audio file onto the upload zone, or click Browse
- Or simply click the Rework tab — it auto-loads the last result from whichever lyrics tab (My Lyrics / AI Lyrics / Instrumental) is currently active
- Or use Load music in the Rework upload zone to load an existing audio file with an optional companion JSON. If the JSON is included, lyrics, style, BPM, duration, key, and other settings are restored from it.
Once loaded, the filename, duration, and an audio player appear. The output panel shows a waveform timeline of the audio.
Approach
Reimagine — generates a new creative take on the entire song. Region selection is disabled in this mode — dragging the waveform and clicking section labels have no effect. Use the Reimagine strength slider to control how closely the result resembles the original.
| Reimagine strength | Effect |
|---|---|
| Low (Subtle) | Stays close to the original structure and feel |
| High (Dramatic) | More departure from the source |
Fix & Blend — regenerates only the selected region while keeping everything else intact. This is the approach to use when you want to change a specific section. Best used on targeted sections rather than large portions of the song.
Set the region:
- Click and drag on the waveform to select a range (highlighted in amber)
- Drag the left/right handles to adjust an existing selection
- Click a section label (if lyrics were provided) to snap to that section; Shift-click to extend the selection
- Start/end timecodes are displayed right on the waveform at the selection edges
- Or type start/end times directly in the region inputs in the Rework panel
Style Direction
Describe what you want the result to sound like. Works for both approaches.
make it more jazzy with warm brass and less percussion
If you have lyrics in the Lyrics panel, they are sent to the model as guidance.
After Generation
The bottom bar stays on the waveform view with the reworked audio loaded. You can:
- Play the result using the audio player in the upload area or the waveform transport bar (both control the same audio)
- Select a new region and rework again immediately
- Download the result with Download audio / Download JSON
Analyze Mode
Analyze uses AceStep to inspect, extract, or manipulate individual stems within an audio file.
Loading Audio
Same as Rework — drag and drop, browse, or auto-load from the active lyrics tab. The Analyze panel has its own upload zone.
Operations
Four sub-modes, selected via buttons in the Analyze panel:
Extract — isolates a single stem (e.g. vocals, drums, bass) from the mix. Select the target track from the dropdown and click ▶ Extract. The result is a solo audio file of that stem.
Replace Track (Lego) — regenerates a single stem while keeping the rest of the mix intact. Select which track to replace, optionally provide style direction, and click ▶ Replace Track. Useful for swapping out a drum pattern or replacing a guitar part.
Complete — fills in missing tracks to complete an arrangement. Select which tracks to generate (multiple selections allowed) and click ▶ Complete. For example, add strings and keyboard to a track that only has vocals and guitar.
Analyze Track (Understand) — extracts metadata and structural information from the audio without generating new audio. Results appear in a dedicated analysis display.
Track Options
Available stems: Vocals, Backing Vocals, Drums, Bass, Guitar, Keyboard, Strings.
Train Mode
Train custom style adapters (LoRA/LoKR) from your own audio files, then use them immediately in generation.
Training Pipeline (left column)
A three-step pipeline processes your audio into training data:
- Scan — upload audio files (drag-and-drop or browse) and scan them to build a dataset
- Auto-label — uses AceStep's language model to generate captions and lyrics for each sample. A checkbox ("Training data is vocal stems") marks samples as a cappella when appropriate
- Preprocess — converts audio into the tensor format needed for training
Each step must complete before the next becomes available.
Training Monitor (centre column)
Once preprocessing is complete, the centre panel shows:
- Samples table — lists loaded audio files with labeling status
- Snapshots — save, load, or delete named dataset snapshots so you can resume later
- Training progress — status label, current loss, progress bar, and streaming log output
- Export — when training finishes, click "Export to loras/" to save the adapter where it's immediately available in the Style Adapter dropdown
Training Config (right column)
The right column switches from generation controls to training configuration:
| Setting | Options | Default |
|---|---|---|
| Adapter type | LoRA, LoKR | LoRA |
| Rank | 1–256 | 64 |
| Epochs | 1–1000 | 10 |
| Learning rate | Number | 0.0001 |
| Labeling model | Default, Small (0.6B), Medium (1.7B), Large (4B) | Default |
Click Start Training when ready. Training and generation are mutually exclusive — AceStep offloads model components during training, so the Generate button is disabled in other modes until training completes.
Playback Controls
Every audio player in the app uses the same transport controls.
| Control | Label | Behaviour |
|---|---|---|
| Rewind | ⟪ | Jumps to position 0. If the audio is playing, it keeps playing from the top. If paused, it just repositions without starting playback. |
| Play / Pause | ▶ / ⏸ | Toggles between play and pause. Shows ▶ when paused, ⏸ when playing. Resumes from the current position. |
| Stop | ⏹ | Pauses and saves the current position. Next Play resumes from there. Greyed out when nothing is playing. |
| Scrubber | ▬▬▬ | Click anywhere on the bar to seek to that position and immediately start playback. |
| Save | ⬇ | Downloads the audio file directly from the player bar. |
Additional behaviours:
- End of track — playback stops and position resets to 0 automatically
- Exclusive playback — starting any player pauses all other players
- Now Playing bar — the bottom strip tracks whichever player is active. Its transport controls mirror the currently playing source. The label shows which tab or mode the audio came from.
Project Save & Load
Save and restore your complete UI state — lyrics, style, sliders, advanced settings, and more.
Saving
Click Save project (below the Generate button). A .wrgl file is downloaded containing all current settings. The filename is derived from your style description.
Loading
Click Load project and pick a file. Two file types are accepted:
.wrglfiles — native project files saved by Wrangler. Restores all settings exactly as they were..jsonsong metadata files — the JSON files downloaded alongside generated audio. When you load one of these, Wrangler imports the generation parameters (lyrics, style, duration, model settings, guidance values, etc.) and sets up the UI to match. The original seed is placed on the Use Last Seed button rather than pre-filled, so you get a fresh random seed by default — click Use Last Seed if you want to reproduce the exact same result.
The status line shows which type was loaded: "Loaded project: ..." for .wrgl files, or "Imported song settings: ..." for song metadata files.
Note: Song metadata files don't include everything a project file does (e.g. tag selections, VRAM tier, LoRA settings). Settings not present in the metadata keep their current values.
Advanced Settings
Click Advanced in the Controls panel to expand.
| Setting | Options | Notes |
|---|---|---|
| Generation model | Turbo (default), High Quality, Base | Turbo is fastest; High Quality produces the most refined output |
| Planning intelligence | None, Small, Medium (default), Large | The LM that plans lyrics structure and arrangement; larger = slower but often better |
| VRAM tier | ≤16GB (default), 24GB, 32GB+ | Controls the maximum allowed batch size |
| Batch size | 1–8 (tier-dependent) | How many results to generate in one run |
| Audio format | MP3 (default), WAV, FLAC | Format for downloaded files |
| Seed | Integer or blank | Leave blank for a random seed; set a value to reproduce a result |
| Scheduler | Euler, DPM++, DDIM | Diffusion sampler; Euler is the default |
| Inference steps | 10–150 | More steps = slower but more refined; overrides the Quality preset |
| Guidance scale (lyric) | 1–15 | Raw control over lyric adherence; overrides the Strictly follow lyrics preset |
| Guidance scale (audio) | 1–15 | Raw control over audio style adherence |
| Guidance mode | Standard (default), Precise | Precise (angle-based guidance) available only with High Quality or Base models |
| Guidance focus | Start % / End % | Controls when guidance is active during the diffusion process (0–100%) |
Sound Reference
Upload an audio track to match its vibe and production style. This shapes the timbre and feel of the output — not its structure or lyrics. Drag and drop or browse to load a reference file. Available in Create and Rework modes.
Style Adapter (LoRA)
Load a pre-trained style adapter to influence generation. Adapters trained in Train mode are automatically available here.
- Select adapter — dropdown lists adapters found in the
loras/directory - Load / Unload — activate or deactivate the selected adapter
- Style influence — slider (0–100%) controlling how strongly the adapter shapes the output
Note: LoRA adapters are not compatible with quantized models. If you see an error when loading, try switching to a non-quantized generation model.
Batch size limits
Certain model combinations require more VRAM and cap the batch size:
| VRAM tier | High Quality / Base + Large LM | All other combinations |
|---|---|---|
| ≤16GB | 1 (locked) | 2 |
| 24GB | 2 | 4 |
| 32GB+ | 4 | 8 |
When the batch size is locked, an inline note explains why.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| Ctrl / Cmd + Enter | Trigger Generate from anywhere in the UI |
Tips
- Section headers in lyrics matter.
[Verse],[Chorus],[Bridge]etc. help the model structure the arrangement correctly and enable the Auto Duration estimate. - Auto Duration works best when BPM is set and the lyrics have section headers.
- Use AI Lyrics when you want the AI to write them. Describe the song you want and your style panel settings (tags, key, BPM) feed directly into what the LM generates — set those first for better results. Copy the generated lyrics to My Lyrics if you want to edit them.
- Instrumental mode is the fastest path to background music or loop generation — no lyrics needed, just set the style and hit Generate.
- Each tab remembers its last song. You can generate from My Lyrics, switch to AI Lyrics, generate something different, and switch back — both results are still there. Switching to Rework auto-loads from whichever tab is active.
- Import a previous song's settings by loading its JSON metadata file via Load Project. This sets up all the parameters for a variation — just hit Generate for a new take with a fresh seed, or click Use Last Seed to reproduce the original.
- Fix & Blend on small regions works better than trying to repaint large portions of a song. For a big change, use Reimagine instead.
- Load music in the Rework upload zone lets you bring in any audio file with an optional companion JSON to restore all the original settings.
- Now Playing bar lets you control playback without scrolling or switching tabs — start a song in AI Lyrics, move to My Lyrics to edit, and the bottom bar keeps playing and lets you pause or rewind.
- Save button (⬇) on every player bar (including Now Playing) lets you quickly download audio at any point.
- Seed is your best friend for reproducibility. Once you have a result you like, note the seed from the downloaded JSON before running variations.
- Train your own style using the Train tab. Upload reference audio, auto-label it, train a LoRA adapter, and it appears immediately in the Style Adapter dropdown.
Updating ACE-Step
ACE-Step 1.5 is bundled as a git submodule. To pull the latest upstream version:
git submodule update --remote vendor/ACE-Step-1.5
git add vendor/ACE-Step-1.5
git commit -m "Update ACE-Step submodule to latest upstream"
This fetches the newest commit from the ACE-Step repo and pins it in your project.
Note: git pull --recurse-submodules does not advance the submodule — it only syncs to whatever commit is already pinned. Use the commands above to actually update.
Caution: Upstream updates may introduce new dependencies or breaking API changes. Test locally before committing the updated submodule — run uv sync to pick up any new requirements, then launch with uv run wrangler and verify generation still works.