From fc67e97504030bc1b9c95e65d0d95af481099898 Mon Sep 17 00:00:00 2001 From: fspecii Date: Wed, 4 Feb 2026 03:12:34 +0200 Subject: [PATCH] Update README with professional styling and demo gif --- README.md | 335 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 248 insertions(+), 87 deletions(-) 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 +

+ 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

-![ACE-Step UI](https://img.shields.io/badge/ACE--Step-1.5-pink) -![License](https://img.shields.io/badge/license-MIT-blue) +

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

+ +

+ Features • + Demo • + Installation • + Usage • + Configuration • + Credits +

+ +

+ React + Express + TypeScript + TailwindCSS + SQLite + License +

+ +--- + +## Demo + +

+ ACE-Step UI Preview +

## 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 +