ace-step-ui

---

🎬 Demo

---

🚀 Why ACE-Step UI?

Tired of paying $10+/month for Suno or Udio? ACE-Step 1.5 is the open source Suno killer that runs locally on your own GPU - and ACE-Step UI gives you a beautiful, professional interface to harness its full power.

Feature	Suno/Udio	ACE-Step UI
Cost	$10-50/month	FREE forever
Privacy	Cloud-based	100% local
Ownership	Licensed	You own everything
Customization	Limited	Full control
Queue Limits	Restricted	Unlimited
Commercial Use	Expensive tiers	No restrictions

What Makes ACE-Step 1.5 Special?

• State-of-the-art quality rivaling commercial services
• Full song generation up to 4+ minutes with vocals
• Runs locally - no internet required after setup
• Open source - inspect, modify, improve
• Active development - constant improvements

---

✨ Features

🎵 AI Music Generation

Feature	Description
Full Song Generation	Create complete songs with vocals and lyrics up to 4+ minutes
Instrumental Mode	Generate instrumental tracks without vocals
Custom Mode	Fine-tune BPM, key, time signature, and duration
Style Tags	Define genre, mood, tempo, and instrumentation
Batch Generation	Generate multiple variations at once
AI Enhance	Enrich genre tags into detailed captions with proper BPM/key/time
Thinking Mode	Let AI reason about structure and generate audio codes

🎨 Advanced Parameters

Feature	Description
Reference Audio	Use any audio file as a style reference
Audio Cover	Transform existing audio with new styles
Repainting	Regenerate specific sections of a track
Seed Control	Reproduce exact generations for consistency
Inference Steps	Control quality vs speed tradeoff

🎤 Lyrics & Prompts

Feature	Description
Lyrics Editor	Write and format lyrics with structure tags
Format Assistant	AI-powered caption and lyrics formatting
Prompt Templates	Quick-start with genre presets
Reuse Prompts	Clone settings from any previous generation

🎧 Professional Interface

Feature	Description
Spotify-Inspired UI	Clean, modern design with dark/light mode
Bottom Player	Full-featured player with waveform and progress
Library Management	Browse, search, and organize all your tracks
Likes & Playlists	Organize favorites into custom playlists
Real-time Progress	Live generation progress with queue position
LAN Access	Use from any device on your local network

🛠️ Built-in Tools

Feature	Description
Audio Editor	Trim, fade, and apply effects with AudioMass
Stem Extraction	Separate vocals, drums, bass, and other with Demucs
Video Generator	Create music videos with Pexels backgrounds
Gradient Covers	Beautiful procedural album art (no internet needed)

---

💻 Tech Stack

Layer	Technologies
Frontend	React 18, TypeScript, TailwindCSS, Vite
Backend	Express.js, SQLite, better-sqlite3
AI Engine	ACE-Step 1.5 (Gradio API)
Audio Tools	AudioMass, Demucs, FFmpeg

---

📋 Requirements

Requirement	Specification
Node.js	18 or higher
Python	3.10+ (3.11 recommended) OR Windows Portable Package
NVIDIA GPU	4GB+ VRAM (works without LLM), 12GB+ recommended (with LLM)
CUDA	12.8 (for Windows Portable Package)
FFmpeg	For audio processing
uv	Python package manager (recommended for standard install)

---

⚡ Quick Start

🎯 Pinokio - 1-Click Install (Recommended for All Users!)

The easiest way to get ACE-Step UI up and running on any platform — no terminal, no manual setup:

Pinokio handles everything automatically: Python, Node.js, dependencies, model downloads, and launching. Just click install and start making music.

---

🪟 Windows - One-Click Start (Easiest!)

cd ace-step-ui
start-all.bat

That's it! This starts everything: API + Backend + Frontend in one command.

Note: By default, it looks for ACE-Step in ..\ACE-Step-1.5. If yours is elsewhere, set ACESTEP_PATH first:

set ACESTEP_PATH=C:\path\to\ACE-Step-1.5
start-all.bat

🪟 Windows - Manual Start

REM 1. Start ACE-Step Gradio (with API endpoints)
cd C:\ACE-Step-1.5
python_embeded\python -m acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

REM 2. Start ACE-Step UI (in another terminal)
cd ace-step-ui
start.bat

Linux / macOS - One-Click Start (Easiest!)

cd ace-step-ui
./start-all.sh

That's it! This starts everything: Gradio + Backend + Frontend in one command.

Note: By default, it looks for ACE-Step in ../ACE-Step-1.5. If yours is elsewhere, set ACESTEP_PATH first:

export ACESTEP_PATH=/path/to/ACE-Step-1.5
./start-all.sh

To stop: ./stop-all.sh

Linux / macOS - Manual Start

# 1. Start ACE-Step Gradio with API (in ACE-Step-1.5 directory)
cd /path/to/ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

# 2. Start ACE-Step UI (in another terminal)
cd ace-step-ui
./start.sh

Windows (Standard Installation)

REM 1. Start ACE-Step Gradio with API (in ACE-Step-1.5 directory)
cd C:\path\to\ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

REM 2. Start ACE-Step UI (in another terminal)
cd ace-step-ui
start.bat

Open http://localhost:3000 and start creating!

---

📦 Installation

1. Install ACE-Step (The AI Engine)

🪟 Windows Portable Package (Recommended for Windows)

The easiest way to get started on Windows! This package includes everything pre-configured:

1. Download ACE-Step-1.5.7z (~5GB)
2. Extract to C:\ACE-Step-1.5 (or your preferred location)
3. Done! The package includes python_embeded with all dependencies

✅ Works with 4GB GPU - No LLM installation required ✅ CUDA 12.8 included ✅ Zero setup hassle

Note: Thinking Mode (LLM features) is automatically disabled on GPUs with <12GB VRAM. You can still enable it manually if you have 12GB+.

Standard Installation (All Platforms)

# Clone ACE-Step 1.5 - the open source Suno alternative
git clone https://github.com/ace-step/ACE-Step-1.5
cd ACE-Step-1.5

# Create virtual environment and install
uv venv
uv pip install -e .

# Models download automatically on first run (~5GB)
cd ..

2. Install ACE-Step UI (This Repository)

Linux / macOS

# Clone the UI
git clone https://github.com/fspecii/ace-step-ui
cd ace-step-ui

# Run setup script (installs all dependencies)
./setup.sh

Windows

REM Clone the UI
git clone https://github.com/fspecii/ace-step-ui
cd ace-step-ui

REM Run setup script (installs all dependencies)
setup.bat

Manual Installation (All Platforms)

# Install frontend dependencies
npm install

# Install server dependencies
cd server
npm install
cd ..

# Copy environment file
# Linux/macOS:
cp server/.env.example server/.env
# Windows:
copy server\.env.example server\.env

---

🎮 Usage

Step 1: Start ACE-Step Gradio Server

🪟 Windows Portable Package:

cd C:\ACE-Step-1.5
python_embeded\python -m acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Linux / macOS:

cd /path/to/ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Windows (Standard Installation):

cd C:\path\to\ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Wait for "API endpoints enabled" before proceeding.

Step 2: Start ACE-Step UI

Linux / macOS:

cd ace-step-ui
./start.sh

Windows:

cd ace-step-ui
start.bat

Step 3: Create Music!

Access	URL
Local	http://localhost:3000
LAN (other devices)	http://YOUR_IP:3000

---

⚙️ Configuration

Edit server/.env:

# Server
PORT=3001

# ACE-Step Gradio URL (must match --port used when starting ACE-Step)
ACESTEP_API_URL=http://localhost:8001

# Database (local-first, no cloud)
DATABASE_PATH=./data/acestep.db

# Optional: Pexels API for video backgrounds
PEXELS_API_KEY=your_key_here

---

🎼 Generation Modes

Simple Mode

Just describe what you want. ACE-Step handles the rest.

"An upbeat pop song about summer adventures with catchy hooks"

Custom Mode

Full control over every parameter:

Parameter	Description
Lyrics	Full lyrics with [Verse], [Chorus] tags
Style	Genre, mood, instruments, tempo
Duration	30-240 seconds