3dtours/ace-step-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README with professional styling and demo gif

Browse Source
This commit is contained in:
fspecii
2026-02-04 03:12:34 +02:00
parent 44f7563014
commit fc67e97504
1 changed files with 248 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+248 -87
View File
@@ -1,29 +1,118 @@
# ACE-Step UI <p align="center">
<img src="https://img.shields.io/badge/🎵-ACE--Step_UI-ff69b4?style=for-the-badge&labelColor=1a1a1a" alt="ACE-Step UI" height="60">
</p>
A local-first web UI for [ACE-Step 1.5](https://github.com/ace-step/ACE-Step) AI music generation. <h1 align="center">ACE-Step UI</h1>
![ACE-Step UI](https://img.shields.io/badge/ACE--Step-1.5-pink) <p align="center">
![License](https://img.shields.io/badge/license-MIT-blue) <strong>A professional, local-first music generation studio for <a href="https://github.com/ace-step/ACE-Step">ACE-Step 1.5</a></strong>
</p>
<p align="center">
<a href="#features">Features</a> •
<a href="#demo">Demo</a> •
<a href="#installation">Installation</a> •
<a href="#usage">Usage</a> •
<a href="#configuration">Configuration</a> •
<a href="#credits">Credits</a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/React-18.3-61DAFB?style=flat-square&logo=react" alt="React">
<img src="https://img.shields.io/badge/Express-4.x-000000?style=flat-square&logo=express" alt="Express">
<img src="https://img.shields.io/badge/TypeScript-5.x-3178C6?style=flat-square&logo=typescript" alt="TypeScript">
<img src="https://img.shields.io/badge/TailwindCSS-3.x-06B6D4?style=flat-square&logo=tailwindcss" alt="TailwindCSS">
<img src="https://img.shields.io/badge/SQLite-3-003B57?style=flat-square&logo=sqlite" alt="SQLite">
<img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="License">
</p>
---
## Demo
<p align="center">
<img src="docs/demo.gif" alt="ACE-Step UI Preview" width="100%">
</p>
## Features ## Features
- Generate music with text prompts and lyrics ### 🎵 AI Music Generation
- Simple and Custom generation modes | Feature | Description |
- Instrumental and vocal track support |---------|-------------|
- Audio editor with waveform visualization | **Full Song Generation** | Create complete songs with vocals and lyrics up to 4+ minutes |
- Stem extraction (vocals, drums, bass, other) | **Instrumental Mode** | Generate instrumental tracks without vocals |
- Video generator with Pexels backgrounds | **Custom Mode** | Fine-tune BPM, key, time signature, and duration |
- Local SQLite database (no cloud required) | **Style Tags** | Define genre, mood, tempo, and instrumentation |
- Playlist management | **Batch Generation** | Generate multiple variations at once |
- Beautiful gradient album covers (no internet needed) | **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](https://github.com/ace-step/ACE-Step) |
| **Audio Tools** | AudioMass, Demucs, FFmpeg |
## Requirements ## Requirements
- **Node.js** 18+ | Requirement | Specification |
- **Python** 3.10+ (3.11 recommended) |-------------|---------------|
- **NVIDIA GPU** with 8GB+ VRAM (12GB+ recommended) | **Node.js** | 18 or higher |
- **FFmpeg** and **FFprobe** (for audio processing) | **Python** | 3.10+ (3.11 recommended) |
- [uv](https://github.com/astral-sh/uv) package manager (recommended for Python) | **NVIDIA GPU** | 8GB+ VRAM (12GB+ recommended) |
| **FFmpeg** | For audio processing |
| **uv** | Python package manager (recommended) |
## Quick Start
```bash
# 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 ## Installation
@@ -38,9 +127,7 @@ cd ACE-Step
uv venv uv venv
uv pip install -e . uv pip install -e .
# Download the model (first run will download automatically, or manually): # Models download automatically on first run (~5GB)
# The model will be downloaded to ~/.cache/huggingface/
cd .. cd ..
``` ```
@@ -48,14 +135,14 @@ cd ..
```bash ```bash
# Clone this repository # Clone this repository
git clone https://github.com/your-org/ace-step-ui git clone https://github.com/fspecii/ace-step-ui
cd ace-step-ui cd ace-step-ui
# Run setup script # Run setup script
./setup.sh ./setup.sh
``` ```
Or manually: **Or manually:**
```bash ```bash
# Install frontend dependencies # Install frontend dependencies
@@ -70,48 +157,25 @@ cd ..
cp server/.env.example server/.env 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 ## Usage
### Step 1: Start ACE-Step API Server ### Step 1: Start ACE-Step API Server
In a terminal, start the ACE-Step API server:
```bash ```bash
cd /path/to/ACE-Step cd /path/to/ACE-Step
uv run acestep-api --port 8001 uv run acestep-api --port 8001
``` ```
Wait until you see "Application startup complete" before proceeding. Wait for "Application startup complete" before proceeding.
### Step 2: Start ACE-Step UI ### Step 2: Start ACE-Step UI
In another terminal:
```bash ```bash
cd ace-step-ui cd ace-step-ui
./start.sh ./start.sh
``` ```
Or manually in two terminals: **Or manually in two terminals:**
```bash ```bash
# Terminal 1 - Backend # Terminal 1 - Backend
@@ -123,62 +187,142 @@ npm run dev
### Step 3: Open the UI ### Step 3: Open the UI
Open http://localhost:3000 in your browser. | 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. On first launch, you'll be asked to set a username. This is stored locally.
## Generating Music ## Configuration
1. **Simple Mode**: Enter a description of the music you want ### Environment Variables
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. Edit `server/.env`:
## Additional Features ```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 ### Audio Editor
Click the waveform icon on any song to open the built-in audio editor for trimming, fading, and effects. Click the edit icon on any song to open AudioMass:
- Cut, copy, paste audio
- Apply fades and effects
- Export in multiple formats
### Stem Extraction ### Stem Extraction
Extract vocals, drums, bass, and other stems from any song using the Demucs-powered stem separator. Separate any song into:
- 🎤 Vocals
- 🥁 Drums
- 🎸 Bass
- 🎹 Other instruments
### Video Generator ### Video Generator
Create music videos with: Create music videos with:
- Custom backgrounds from Pexels (requires API key) - Pexels stock footage (requires API key)
- Gradient animations - Gradient animations
- Lyrics display - Lyrics overlay
- Album art overlay - Album art display
## Troubleshooting ## Troubleshooting
### "ACE-Step API not reachable" | Issue | Solution |
Make sure the ACE-Step API server is running on port 8001: |-------|----------|
```bash | **ACE-Step API not reachable** | Ensure `uv run acestep-api --port 8001` is running |
cd /path/to/ACE-Step | **CUDA out of memory** | Close other GPU apps, reduce duration/batch size |
uv run acestep-api --port 8001 | **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
``` ```
### "CUDA out of memory" ## API Endpoints
- Close other GPU-intensive applications
- Try generating shorter clips (30-60 seconds)
- Reduce batch size if available
### Songs show 0:00 duration | Method | Endpoint | Description |
This can happen if FFprobe is not installed. Install it: |--------|----------|-------------|
```bash | `POST` | `/api/generate` | Start music generation |
# Ubuntu/Debian | `GET` | `/api/generate/status/:id` | Get job status |
sudo apt install ffmpeg | `GET` | `/api/songs` | Get user's songs |
| `POST` | `/api/songs/:id/like` | Toggle like |
# macOS | `GET` | `/api/playlists` | Get playlists |
brew install ffmpeg | `POST` | `/api/playlists` | Create playlist |
```
New songs will automatically detect duration. For existing songs, they'll update when played.
## Development ## Development
```bash ```bash
# Run in development mode with hot reload # Development mode with hot reload
./start.sh ./start.sh
# Build for production # Build for production
@@ -186,12 +330,29 @@ npm run build
cd server && npm run build cd server && npm run build
``` ```
## License
MIT
## Credits ## Credits
- [ACE-Step](https://github.com/ace-step/ACE-Step) - AI music generation model - **[ACE-Step](https://github.com/ace-step/ACE-Step)** - AI music generation model
- [Demucs](https://github.com/facebookresearch/demucs) - Audio source separation - **[AudioMass](https://github.com/pkalogiros/AudioMass)** - Web audio editor
- [Pexels](https://www.pexels.com) - Stock video backgrounds - **[Demucs](https://github.com/facebookresearch/demucs)** - Audio source separation
- **[Pexels](https://www.pexels.com)** - Stock video backgrounds
## License
This project is open source under the [MIT License](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
---
<p align="center">
Made with ❤️ for the open-source AI music community
</p>