A creative-friendly web UI for AceStep 1.5, designed for musicians and producers — not ML researchers.

ACE-Step-Wrangler replaces the default Gradio interface with a dark, DAW-inspired UI that abstracts complex model parameters behind intuitive controls. If you know what a compressor does but not what a guidance scale is, this is for you.

• Four modes — Create (new songs from scratch), Rework (reimagine or fix regions of existing audio), Analyze (extract, replace, or complete stems), and Train (build custom style adapters)
• Three lyrics modes — My Lyrics (write/paste/load), AI Lyrics (describe a song and let AceStep write the words), and Instrumental (no vocals)
• Per-tab results — each lyrics tab keeps its own generated audio independently; switch tabs without losing your results
• Now Playing bar — a persistent transport strip at the bottom shows what is playing and which tab it came from; works across all tabs and modes
• Friendly controls — sliders like "Creativity" and "Quality" instead of raw model parameters
• Genre + mood tag picker — click presets or type your own style description
• Song parameters — set key (e.g. A minor), BPM, and time signature; appended to the AceStep prompt automatically
• Auto duration — estimates song length from your lyrics and tempo using AceStep's LM planner, with a heuristic fallback
• Rework mode — reimagine a full song or fix and blend a selected region using the waveform editor; auto-loads from whichever lyrics tab is active
• Analyze mode — extract individual stems, replace a single track, or complete an arrangement with missing instruments
• Train mode — train LoRA/LoKR style adapters from your own audio, then use them immediately in generation
• Style Adapter (LoRA) — load trained adapters to shape the model's style; adjust influence with a slider
• Sound reference — upload a track to match its vibe and production style without changing lyrics or structure
• Project save & load — save all UI settings to a .wrgl file; also import settings from song metadata JSON files to create variations on previous generations
• Smart warnings — get notified if your song duration is too short for your lyrics before you generate
• DAW-style audio transport — Play/Pause toggle, Stop, Rewind, scrubber, and save button on every player
• Advanced panel — raw AceStep parameters (guidance scale, inference steps, scheduler, seed, batch size, audio format) still accessible for power users
• Dark DAW aesthetic — feels at home next to your other music tools

See the User Guide for full documentation, or the Lyrics Guide for tips on writing lyrics that work well with ACE-Step.

• Python 3.11 or 3.12
• A CUDA-capable GPU (for AceStep — Wrangler itself has no GPU requirements)
• A modern browser
• uv (recommended) or pip

ACE-Step 1.5 is bundled as a git submodule — no separate installation needed.

git clone --recursive https://github.com/tsondo/ACE-Step-Wrangler.git
cd ACE-Step-Wrangler
uv sync

The --recursive flag pulls in the ACE-Step 1.5 submodule. If you already cloned without it:

git submodule update --init --recursive
uv sync

uv sync creates a virtual environment and installs everything — Wrangler's lightweight dependencies and ACE-Step's full ML stack (PyTorch, transformers, etc.).

uv run wrangler

This starts both servers:

• AceStep API on http://localhost:8001 (loads models, runs inference on GPU)
• Wrangler UI on http://localhost:7860 (serves the web interface, no GPU)

Open http://localhost:7860 in your browser and start making music.

Ctrl+C shuts down both servers gracefully.

First run: AceStep will automatically download its models (~10 GB) on first launch. The default download includes the turbo DiT model, the 1.7B language model, the Qwen3 text encoder, and the audio VAE. The exact LM model chosen may vary based on your GPU's available VRAM. Ensure you have sufficient disk space and a reasonable internet connection. Models are cached locally and only downloaded once. You can also pre-download them with uv run acestep-download.

ACE-Step is a single-GPU model — it does not do multi-GPU inference, but CUDA_VISIBLE_DEVICES controls which GPU it uses.

On multi-GPU systems, Wrangler auto-selects the GPU with the most free VRAM when no explicit choice is made. The startup banner shows which GPU was selected, how it was chosen, and current VRAM:

============================================================
  ACE-Step Wrangler
============================================================
  GPU:           0 — NVIDIA GeForce RTX 3090 Ti (22.1 / 24.0 GB free)  [auto-selected (most free VRAM)]
  Models:        /data/models
  AceStep API:   http://localhost:8001
  Wrangler UI:   http://localhost:7860
============================================================

To override auto-selection:

# Use a specific GPU (e.g. GPU 1)
uv run wrangler --gpu 1

# Or set in .env / environment
ACESTEP_GPU=1 uv run wrangler

Priority: --gpu flag > ACESTEP_GPU env var > auto-select (most free VRAM) > CUDA default.

If free VRAM on the selected GPU is below 14 GB, the banner warns and suggests using a smaller LM or offloading the VAE to CPU.

The Wrangler UI server never sees CUDA_VISIBLE_DEVICES — it has no GPU requirements.

ACE-Step supports several environment variables for fine-tuning GPU behavior. These are forwarded to the AceStep subprocess if set:

Example:

MAX_CUDA_VRAM=14 ACESTEP_VAE_ON_CPU=true uv run wrangler --gpu 0

See the ACE-Step 1.5 documentation for full details on GPU compatibility and these variables.

If you already have AceStep running elsewhere (different machine, custom setup, etc.), you can skip run.py and start only the Wrangler UI:

uv run python backend/main.py

This connects to AceStep's API at http://localhost:8001 by default. Open http://localhost:7860 in your browser.

ACE-Step-Wrangler/
├── run.py                    # Unified launcher (both servers)
├── pyproject.toml            # Project dependencies (managed by uv)
├── vendor/
│   └── ACE-Step-1.5/        # Git submodule — upstream ACE-Step
├── backend/
│   ├── main.py               # FastAPI server (Wrangler UI)
│   └── acestep_wrapper.py    # AceStep API wrapper
├── frontend/
│   ├── index.html
│   ├── style.css
│   └── app.js
├── loras/                    # Trained LoRA adapters (auto-scanned by Style Adapter)
└── docs/
    ├── USER_GUIDE.md         # Current user-facing documentation
    ├── LYRICS_GUIDE.md       # Tips for writing lyrics that work with ACE-Step
    ├── PROJECT_PLAN.md       # Original design spec (historical)
    ├── DESIGN_SPEC_V2.md     # v2 design spec (historical)
    ├── LORA_PLAN.md          # LoRA integration plan (historical)
    └── FUTURE_PLANS.md       # Planned future features

• Python: 3.11–3.12
• CUDA: 12.8 (x86_64 / Windows), 13.0 (aarch64 Linux)
• PyTorch: 2.10 (Linux / macOS), 2.7 (Windows)
• Platforms: Linux x86_64, Linux aarch64, macOS Apple Silicon, Windows

Wrangler itself has no GPU dependencies — GPU/platform support comes entirely from ACE-Step.

Complete — all build stages shipped and end-to-end tested. The full generation loop works: style + song parameters → AceStep → audio playback, download, and JSON metadata export.

• General inquiries: info@tsondo.com
• Contributors: dev@tsondo.com

MIT