diff --git a/README.md b/README.md
index ddd6753..9963a9c 100644
--- a/README.md
+++ b/README.md
@@ -1,29 +1,118 @@
-# ACE-Step UI
+
+ 
+
-A local-first web UI for [ACE-Step 1.5](https://github.com/ace-step/ACE-Step) AI music generation.
+ACE-Step UI
-
-
+
+ A professional, local-first music generation studio for ACE-Step 1.5
+
+
+
+ Features •
+ Demo •
+ Installation •
+ Usage •
+ Configuration •
+ Credits
+
+
+
+ 
+ 
+ 
+ 
+ 
+ 
+
+
+---
+
+## Demo
+
+
+ 
+
## 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)
+### 🎵 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](https://github.com/ace-step/ACE-Step) |
+| **Audio Tools** | AudioMass, Demucs, FFmpeg |
## 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)
+| 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
+
+```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
@@ -38,9 +127,7 @@ cd ACE-Step
uv venv
uv pip install -e .
-# Download the model (first run will download automatically, or manually):
-# The model will be downloaded to ~/.cache/huggingface/
-
+# Models download automatically on first run (~5GB)
cd ..
```
@@ -48,14 +135,14 @@ cd ..
```bash
# 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
# Run setup script
./setup.sh
```
-Or manually:
+**Or manually:**
```bash
# Install frontend dependencies
@@ -70,48 +157,25 @@ cd ..
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.
+Wait for "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:
+**Or manually in two terminals:**
```bash
# Terminal 1 - Backend
@@ -123,62 +187,142 @@ npm run dev
### 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.
-## Generating Music
+## Configuration
-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
+### Environment Variables
-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
-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
-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
Create music videos with:
-- Custom backgrounds from Pexels (requires API key)
+- Pexels stock footage (requires API key)
- Gradient animations
-- Lyrics display
-- Album art overlay
+- Lyrics overlay
+- Album art display
## 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
+| 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
```
-### "CUDA out of memory"
-- Close other GPU-intensive applications
-- Try generating shorter clips (30-60 seconds)
-- Reduce batch size if available
+## API Endpoints
-### 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.
+| 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
```bash
-# Run in development mode with hot reload
+# Development mode with hot reload
./start.sh
# Build for production
@@ -186,12 +330,29 @@ 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
+- **[ACE-Step](https://github.com/ace-step/ACE-Step)** - AI music generation model
+- **[AudioMass](https://github.com/pkalogiros/AudioMass)** - Web audio editor
+- **[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
+
+---
+
+
+ Made with ❤️ for the open-source AI music community
+