ace-step-ui README

The project's README from github.com/fspecii/ace-step-ui. As one markdown file: README.md.

ACE-Step UI

ACE-Step UI

The Ultimate Open Source Suno Alternative
Seamless integration with ACE-Step 1.5 - The Open Source AI Music Generation Model

Subscribe on YouTube Follow on X Web Design Studio London

Demo • Why ACE-Step • Features • Installation • Usage • Contributing

React TypeScript TailwindCSS SQLite License Stars

🎬 Demo

Watch Demo on YouTube

ACE-Step UI - Open Source Suno Alternative

Generate professional AI music with a Spotify-like interface - 100% free and local

🚀 Why ACE-Step UI?

Tired of paying $10+/month for Suno or Udio? ACE-Step 1.5 is the open source Suno killer that runs locally on your own GPU - and ACE-Step UI gives you a beautiful, professional interface to harness its full power.

Feature Suno/Udio ACE-Step UI
Cost $10-50/month FREE forever
Privacy Cloud-based 100% local
Ownership Licensed You own everything
Customization Limited Full control
Queue Limits Restricted Unlimited
Commercial Use Expensive tiers No restrictions

What Makes ACE-Step 1.5 Special?

✨ 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
AI Enhance Enrich genre tags into detailed captions with proper BPM/key/time
Thinking Mode Let AI reason about structure and generate audio codes

🎨 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 (Gradio API)
Audio Tools AudioMass, Demucs, FFmpeg

📋 Requirements

Requirement Specification
Node.js 18 or higher
Python 3.10+ (3.11 recommended) OR Windows Portable Package
NVIDIA GPU 4GB+ VRAM (works without LLM), 12GB+ recommended (with LLM)
CUDA 12.8 (for Windows Portable Package)
FFmpeg For audio processing
uv Python package manager (recommended for standard install)

⚡ Quick Start

🎯 Pinokio - 1-Click Install (Recommended for All Users!)

The easiest way to get ACE-Step UI up and running on any platform — no terminal, no manual setup:

Install with Pinokio

Pinokio handles everything automatically: Python, Node.js, dependencies, model downloads, and launching. Just click install and start making music.

🪟 Windows - One-Click Start (Easiest!)

cd ace-step-ui
start-all.bat

That's it! This starts everything: API + Backend + Frontend in one command.

Note: By default, it looks for ACE-Step in ..\ACE-Step-1.5. If yours is elsewhere, set ACESTEP_PATH first:

set ACESTEP_PATH=C:\path\to\ACE-Step-1.5
start-all.bat

🪟 Windows - Manual Start

REM 1. Start ACE-Step Gradio (with API endpoints)
cd C:\ACE-Step-1.5
python_embeded\python -m acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

REM 2. Start ACE-Step UI (in another terminal)
cd ace-step-ui
start.bat

Linux / macOS - One-Click Start (Easiest!)

cd ace-step-ui
./start-all.sh

That's it! This starts everything: Gradio + Backend + Frontend in one command.

Note: By default, it looks for ACE-Step in ../ACE-Step-1.5. If yours is elsewhere, set ACESTEP_PATH first:

export ACESTEP_PATH=/path/to/ACE-Step-1.5
./start-all.sh

To stop: ./stop-all.sh

Linux / macOS - Manual Start

# 1. Start ACE-Step Gradio with API (in ACE-Step-1.5 directory)
cd /path/to/ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

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

Windows (Standard Installation)

REM 1. Start ACE-Step Gradio with API (in ACE-Step-1.5 directory)
cd C:\path\to\ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

REM 2. Start ACE-Step UI (in another terminal)
cd ace-step-ui
start.bat

Open http://localhost:3000 and start creating!

📦 Installation

1. Install ACE-Step (The AI Engine)

The easiest way to get started on Windows! This package includes everything pre-configured:

  1. Download ACE-Step-1.5.7z (~5GB)
  2. Extract to C:\ACE-Step-1.5 (or your preferred location)
  3. Done! The package includes python_embeded with all dependencies

✅ Works with 4GB GPU - No LLM installation required ✅ CUDA 12.8 included ✅ Zero setup hassle

Note: Thinking Mode (LLM features) is automatically disabled on GPUs with <12GB VRAM. You can still enable it manually if you have 12GB+.

Standard Installation (All Platforms)

# Clone ACE-Step 1.5 - the open source Suno alternative
git clone https://github.com/ace-step/ACE-Step-1.5
cd ACE-Step-1.5

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

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

2. Install ACE-Step UI (This Repository)

Linux / macOS

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

# Run setup script (installs all dependencies)
./setup.sh

Windows

REM Clone the UI
git clone https://github.com/fspecii/ace-step-ui
cd ace-step-ui

REM Run setup script (installs all dependencies)
setup.bat

Manual Installation (All Platforms)

# Install frontend dependencies
npm install

# Install server dependencies
cd server
npm install
cd ..

# Copy environment file
# Linux/macOS:
cp server/.env.example server/.env
# Windows:
copy server\.env.example server\.env

🎮 Usage

Step 1: Start ACE-Step Gradio Server

🪟 Windows Portable Package:

cd C:\ACE-Step-1.5
python_embeded\python -m acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Linux / macOS:

cd /path/to/ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Windows (Standard Installation):

cd C:\path\to\ACE-Step-1.5
uv run acestep --port 8001 --enable-api --backend pt --server-name 127.0.0.1

Wait for "API endpoints enabled" before proceeding.

Step 2: Start ACE-Step UI

Linux / macOS:

cd ace-step-ui
./start.sh

Windows:

cd ace-step-ui
start.bat

Step 3: Create Music!

Access URL
Local http://localhost:3000
LAN (other devices) http://YOUR_IP:3000

⚙️ Configuration

Edit server/.env:

# Server
PORT=3001

# ACE-Step Gradio URL (must match --port used when starting ACE-Step)
ACESTEP_API_URL=http://localhost:8001

# Database (local-first, no cloud)
DATABASE_PATH=./data/acestep.db

# Optional: Pexels API for video backgrounds
PEXELS_API_KEY=your_key_here

🎼 Generation Modes

Simple Mode

Just describe what you want. ACE-Step handles the rest.

"An upbeat pop song about summer adventures with catchy hooks"

Custom Mode

Full control over every parameter:

Parameter Description
Lyrics Full lyrics with [Verse], [Chorus] tags
Style Genre, mood, instruments, tempo
Duration 30-240 seconds
BPM 60-200 beats per minute
Key Musical key (C major, A minor, etc.)

AI Enhance & Thinking Mode

Mode What it does Speed impact
AI Enhance OFF Sends your style tags directly to the model Fastest
AI Enhance ON LLM enriches your tags into a detailed caption and generates proper BPM, key, time signature +10-20s
Thinking Mode Full LLM reasoning with audio code generation Slowest, best quality

Tip: If your genre tags (e.g. "pop, rock") produce ballad-like output, turn on AI Enhance for much better genre accuracy. No extra VRAM needed — the LLM runs on CPU with the PT backend.

Batch Size & Bulk Generation

Setting Description
Batch Size Number of variations generated per job (1-4). Default is 1 for broad GPU compatibility. Higher values generate more variations but use more VRAM. 8GB GPU users should keep this at 1.
Bulk Generate Queue multiple independent generation jobs (1-10). Each job runs sequentially, so this is safe for any GPU.
LM Backend Choose between PT (1.6 GB VRAM) and VLLM (9.2 GB VRAM). PT is the default and works on most GPUs.

Tip: Both batch size and bulk count are remembered in your browser — set them once and they stick for future sessions.

🔧 Built-in Tools

Tool Description
🎚️ Audio Editor Cut, trim, fade, and apply effects
🎤 Stem Extraction Separate vocals, drums, bass, other
🎬 Video Generator Create music videos with stock footage
🎨 Album Art Auto-generated gradient covers

🐛 Troubleshooting

Issue Solution
ACE-Step not reachable Ensure Gradio server is running with --enable-api flag (see Usage section)
CUDA out of memory Use --backend pt (default), set batch size to 1, reduce duration, or disable Thinking Mode
4GB GPU - Out of memory Use PT backend (default), batch size 1, and keep Thinking Mode OFF. LLM features require 12GB+
Genre always sounds like ballad Enable AI Enhance toggle in the Style section — it enriches your tags with proper metadata
AttributeError: 'NoneType' Update to latest ACE-Step-1.5 (fix merged in PR #109)
Songs show 0:00 duration Install FFmpeg: sudo apt install ffmpeg (Linux) or download from ffmpeg.org (Windows)
LAN access not working Check firewall allows ports 3000 and 3001

🤝 Contributing

We need your help to make ACE-Step UI even better!

This is a community-driven project and contributions are what make open source amazing. Whether you're fixing bugs, adding features, improving documentation, or sharing ideas - every contribution counts!

Ways to Contribute

How to Contribute

  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

📣 Stay Connected

YouTube

X/Twitter

Subscribe and follow for:
🎥 Video tutorials and demos
🚀 New feature announcements
💡 Tips and tricks
🎵 AI music generation news

💼 Need a Website Like This?

If you like the engineering and design behind ACE-Step UI and want something similar built for your business, the same team offers professional web development services.

We build:

webdesignstudio.london

From the makers of ACE-Step UI — we ship production-grade web experiences.

👤 About the Author

ACE-Step UI is built and maintained by Vali — open-source developer and founder of Web Design Studio London, a specialist web design and development studio serving London businesses and international clients.

Web Design Studio London builds high-performance Next.js websites, ecommerce platforms, and AI-integrated web applications — the same technical approach that powers this project.

If you need a professional website, ecommerce build, or AI integration for your business, visit webdesignstudio.london.

🙏 Credits

📄 License

This project is open source under the MIT License.

⭐ If ACE-Step UI helps you create amazing music, please star this repo! ⭐

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

Stop paying for Suno. Start creating with ACE-Step.

ace-step-ui (fspecii/ace-step-ui)

Searching Database…

5.1K ·GitHub
Ace-step-ui
这是什么？ACE-Step UI 是一款免费、开源、可在本地运行的网页界面，用于 ACE-Step 1.5 AI 音乐生成模型，让你无需付费使用 Suno 或 Udio，就能创作带人声或纯音乐的完整歌曲。
这是 AI 模型本身，还是只是它的界面？它只是前端和后端层（React、TypeScript、Express、SQLite），通过 Gradio API 与单独安装的 ACE-Step 1.5 模型通信。你仍然需要先安装 ACE-Step 作为真正的 AI 引擎。
我该怎么让它运行起来？先安装 ACE-Step 1.5（Windows Portable Package 或手动配置 Python 环境），然后在 Windows 上运行一键启动脚本 start-all.bat，在 Linux/macOS 上运行 ./start-all.sh，即可同时启动 API、后端和前端。Pinokio 则在任何平台上都提供真正的一键安装。
使用前我需要先安装哪些东西？Node.js 18+、Python 3.10+（或 Windows Portable Package）、至少 4GB 显存的 NVIDIA GPU（LLM 功能需要 12GB+ 显存）、便携版包需要 CUDA 12.8，以及用于音频处理的 FFmpeg。
如果我的显卡性能较弱，有什么需要注意的吗？显存低于 12GB 的 GPU 会自动禁用 Thinking Mode 和其他基于 LLM 的功能；4GB 显存的显卡必须使用 PT 后端并将 batch size 设为 1，否则容易耗尽显存。
我的数据会离开我的电脑吗？不会。完成设置后，所有操作都在本地运行，包括生成、存储（SQLite）和音频工具，全部只使用你自己的 GPU 和网络。
它自带哪些音频工具？它内置基于 AudioMass 的音频编辑器，可用于剪辑和添加效果；借助 Demucs 进行音轨分离，可将人声、鼓和贝斯分开；还有使用 Pexels 素材的音乐视频生成器，以及程序生成的渐变专辑封面。
我能在局域网内的其他设备上使用它吗？可以。它支持局域网访问，只要防火墙开放端口 3000 和 3001，局域网内的任何设备都能生成和播放曲目。
什么是 'Thinking Mode'？这是一种模式：LLM 会在合成音频前推理歌曲结构并生成音频编码。它的音质最好，但速度最慢，并且需要 12GB+ 显存。
在 Custom Mode 中我能控制哪些内容？你可以设置包含 [Verse]、[Chorus] 等结构标签的完整歌词，指定风格、情绪和乐器编配，设定 30-240 秒的时长、60-200 的 BPM，以及调性。
What are similar projects?yovoice, stemkit, MiniMax-Music3, WanGP, youtubepro, openwhispr, vlo, bark
Which topics is it in?music-generation, audio-generation, express, music, tailwindcss, ffmpeg, vite, audio, offline, sqlite, nvidia, generative-ai
Creator
fspecii
Size
20.4 MB
Stars
5.1K
Updated
CommitJun 27
Age
8mo
Commits · 90 Days