fspecii
198 lines
4.1 KiB
Markdown
198 lines
4.1 KiB
Markdown
# ACE-Step UI
|
|
|
|
A local-first web UI for [ACE-Step 1.5](https://github.com/ace-step/ACE-Step) AI music generation.
|
|
|
|
|
|
|
|
|
|
## Features
|
|
|
|
- Generate music with text prompts and lyrics
|
|
- Simple and Custom generation modes
|
|
- Instrumental and vocal track support
|
|
- Audio editor with waveform visualization
|
|
- Stem extraction (vocals, drums, bass, other)
|
|
- Video generator with Pexels backgrounds
|
|
- Local SQLite database (no cloud required)
|
|
- Playlist management
|
|
- Beautiful gradient album covers (no internet needed)
|
|
|
|
## Requirements
|
|
|
|
- **Node.js** 18+
|
|
- **Python** 3.10+ (3.11 recommended)
|
|
- **NVIDIA GPU** with 8GB+ VRAM (12GB+ recommended)
|
|
- **FFmpeg** and **FFprobe** (for audio processing)
|
|
- [uv](https://github.com/astral-sh/uv) package manager (recommended for Python)
|
|
|
|
## Installation
|
|
|
|
### 1. Install ACE-Step
|
|
|
|
```bash
|
|
# 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 .
|
|
|
|
# Download the model (first run will download automatically, or manually):
|
|
# The model will be downloaded to ~/.cache/huggingface/
|
|
|
|
cd ..
|
|
```
|
|
|
|
### 2. Install ACE-Step UI
|
|
|
|
```bash
|
|
# Clone this repository
|
|
git clone https://github.com/your-org/ace-step-ui
|
|
cd ace-step-ui
|
|
|
|
# Run setup script
|
|
./setup.sh
|
|
```
|
|
|
|
Or manually:
|
|
|
|
```bash
|
|
# Install frontend dependencies
|
|
npm install
|
|
|
|
# Install server dependencies
|
|
cd server
|
|
npm install
|
|
cd ..
|
|
|
|
# Copy environment file
|
|
cp server/.env.example server/.env
|
|
```
|
|
|
|
### 3. Configure (Optional)
|
|
|
|
Edit `server/.env` to customize:
|
|
|
|
```env
|
|
# Server port
|
|
PORT=3001
|
|
|
|
# ACE-Step API URL (default: http://localhost:8001)
|
|
ACESTEP_API_URL=http://localhost:8001
|
|
|
|
# Database location
|
|
DATABASE_PATH=./data/acestep.db
|
|
|
|
# Optional: Pexels API key for video backgrounds
|
|
# Get a free key at https://www.pexels.com/api/
|
|
PEXELS_API_KEY=your_key_here
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Step 1: Start ACE-Step API Server
|
|
|
|
In a terminal, start the ACE-Step API server:
|
|
|
|
```bash
|
|
cd /path/to/ACE-Step
|
|
uv run acestep-api --port 8001
|
|
```
|
|
|
|
Wait until you see "Application startup complete" before proceeding.
|
|
|
|
### Step 2: Start ACE-Step UI
|
|
|
|
In another terminal:
|
|
|
|
```bash
|
|
cd ace-step-ui
|
|
./start.sh
|
|
```
|
|
|
|
Or manually in two terminals:
|
|
|
|
```bash
|
|
# Terminal 1 - Backend
|
|
cd server && npm run dev
|
|
|
|
# Terminal 2 - Frontend
|
|
npm run dev
|
|
```
|
|
|
|
### Step 3: Open the UI
|
|
|
|
Open http://localhost:3000 in your browser.
|
|
|
|
On first launch, you'll be asked to set a username. This is stored locally.
|
|
|
|
## Generating Music
|
|
|
|
1. **Simple Mode**: Enter a description of the music you want
|
|
2. **Custom Mode**: Fine-tune parameters like BPM, key, duration, and add lyrics
|
|
3. Click "Create" to generate
|
|
|
|
Generated songs are saved locally and appear in your library.
|
|
|
|
## Additional Features
|
|
|
|
### Audio Editor
|
|
Click the waveform icon on any song to open the built-in audio editor for trimming, fading, and effects.
|
|
|
|
### Stem Extraction
|
|
Extract vocals, drums, bass, and other stems from any song using the Demucs-powered stem separator.
|
|
|
|
### Video Generator
|
|
Create music videos with:
|
|
- Custom backgrounds from Pexels (requires API key)
|
|
- Gradient animations
|
|
- Lyrics display
|
|
- Album art overlay
|
|
|
|
## Troubleshooting
|
|
|
|
### "ACE-Step API not reachable"
|
|
Make sure the ACE-Step API server is running on port 8001:
|
|
```bash
|
|
cd /path/to/ACE-Step
|
|
uv run acestep-api --port 8001
|
|
```
|
|
|
|
### "CUDA out of memory"
|
|
- Close other GPU-intensive applications
|
|
- Try generating shorter clips (30-60 seconds)
|
|
- Reduce batch size if available
|
|
|
|
### Songs show 0:00 duration
|
|
This can happen if FFprobe is not installed. Install it:
|
|
```bash
|
|
# Ubuntu/Debian
|
|
sudo apt install ffmpeg
|
|
|
|
# macOS
|
|
brew install ffmpeg
|
|
```
|
|
New songs will automatically detect duration. For existing songs, they'll update when played.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Run in development mode with hot reload
|
|
./start.sh
|
|
|
|
# Build for production
|
|
npm run build
|
|
cd server && npm run build
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Credits
|
|
|
|
- [ACE-Step](https://github.com/ace-step/ACE-Step) - AI music generation model
|
|
- [Demucs](https://github.com/facebookresearch/demucs) - Audio source separation
|
|
- [Pexels](https://www.pexels.com) - Stock video backgrounds
|