ace-step-ui/README.md

ACE-Step UI

A professional, local-first music generation studio for ACE-Step 1.5

Features • Demo • Installation • Usage • Configuration • Credits

---

Demo

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
Thinking Mode	Let AI enhance your prompts automatically

🎨 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
Audio Tools	AudioMass, Demucs, FFmpeg

Requirements

Requirement	Specification
Node.js	18 or higher
Python	3.10+ (3.11 recommended)
NVIDIA GPU	8GB+ VRAM (12GB+ recommended)
FFmpeg	For audio processing
uv	Python package manager (recommended)

Quick Start

# 1. Start ACE-Step API (in ACE-Step directory)
cd /path/to/ACE-Step
uv run acestep-api --port 8001

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

Open http://localhost:3000

Installation

1. Install ACE-Step

# Clone ACE-Step
git clone https://github.com/ace-step/ACE-Step
cd ACE-Step

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

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

2. Install ACE-Step UI

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

# Run setup script
./setup.sh

Or manually:

# Install frontend dependencies
npm install

# Install server dependencies
cd server
npm install
cd ..

# Copy environment file
cp server/.env.example server/.env

Usage

Step 1: Start ACE-Step API Server

cd /path/to/ACE-Step
uv run acestep-api --port 8001

Wait for "Application startup complete" before proceeding.

Step 2: Start ACE-Step UI

cd ace-step-ui
./start.sh

Or manually in two terminals:

# Terminal 1 - Backend
cd server && npm run dev

# Terminal 2 - Frontend
npm run dev

Step 3: Open the UI

Mode	URL
Local	http://localhost:3000
LAN	http://YOUR_IP:3000

On first launch, you'll be asked to set a username. This is stored locally.

Configuration

Environment Variables

Edit server/.env:

# Server
PORT=3001
NODE_ENV=development

# ACE-Step API
ACESTEP_API_URL=http://localhost:8001

# Database
DATABASE_PATH=./data/acestep.db

# Storage
AUDIO_DIR=./public/audio

# Optional: Pexels API for video backgrounds
PEXELS_API_KEY=your_key_here

LAN Access

ACE-Step UI automatically supports LAN access. Start the servers and access from any device:

1. Find your computer's IP: hostname -I (Linux) or ipconfig (Windows)
2. Open http://YOUR_IP:3000 on any device

Generation Modes

Simple Mode

Enter a description of the music you want. The AI handles the rest.

Custom Mode

Fine-tune every parameter:

Parameter	Description
Title	Song title
Lyrics	Full lyrics with structure tags [Verse], [Chorus], etc.
Style	Genre, mood, instruments, tempo descriptors
Duration	30-240 seconds
BPM	60-200 beats per minute
Key	Musical key (C major, A minor, etc.)
Time Signature	4/4, 3/4, 6/8, etc.

Advanced Settings

Setting	Description
Inference Steps	Higher = better quality, slower (default: 60)
Guidance Scale	Prompt adherence strength (default: 15)
Batch Size	Number of variations to generate
Thinking Mode	AI prompt enhancement
Random Seed	For reproducible results

Built-in Tools

Audio Editor

Click the edit icon on any song to open AudioMass:

• Cut, copy, paste audio
• Apply fades and effects
• Export in multiple formats

Stem Extraction

Separate any song into:

• 🎤 Vocals
• 🥁 Drums
• 🎸 Bass
• 🎹 Other instruments

Video Generator

Create music videos with:

• Pexels stock footage (requires API key)
• Gradient animations
• Lyrics overlay
• Album art display

Troubleshooting

Issue	Solution
ACE-Step API not reachable	Ensure uv run acestep-api --port 8001 is running
CUDA out of memory	Close other GPU apps, reduce duration/batch size
Songs show 0:00 duration	Install FFmpeg: sudo apt install ffmpeg
LAN access not working	Check firewall allows ports 3000 and 3001
Liked songs not saving	Refresh page, check browser console for errors

Project Structure

ace-step-ui/
├── components/           # React components
│   ├── CreatePanel.tsx   # Main generation form
│   ├── Player.tsx        # Bottom audio player
│   ├── LibraryView.tsx   # Song library
│   └── ...
├── server/
│   ├── src/
│   │   ├── routes/       # API endpoints
│   │   ├── services/     # Business logic
│   │   └── db/           # SQLite database
│   ├── public/
│   │   ├── audio/        # Generated audio files
│   │   └── demucs-web/   # Stem extraction UI
│   └── audio-editor/     # AudioMass editor
├── services/             # Frontend API client
├── context/              # React context providers
└── docs/                 # Documentation & assets

API Endpoints

Method	Endpoint	Description
POST	/api/generate	Start music generation
GET	/api/generate/status/:id	Get job status
GET	/api/songs	Get user's songs
POST	/api/songs/:id/like	Toggle like
GET	/api/playlists	Get playlists
POST	/api/playlists	Create playlist

Development

# Development mode with hot reload
./start.sh

# Build for production
npm run build
cd server && npm run build

Credits

• ACE-Step - AI music generation model
• AudioMass - Web audio editor
• Demucs - Audio source separation
• Pexels - Stock video backgrounds

License

This project is open source under the MIT License.

Contributing

Contributions are welcome! Please feel free to:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

Made with ❤️ for the open-source AI music community