Apppublic
ACE-Step/Ace-Step-v1.5

sourceHugging Facemitupdated 6mo agoView on Hugging Face
580likes
README.md235 linesDownload Raw Back to root
1---2title: ACE-Step v1.53emoji: 🎵4colorFrom: blue5colorTo: purple6sdk: gradio7sdk_version: 6.2.08python_version: 3.119pinned: false10models: 11 - ACE-Step/Ace-Step1.512 - ACE-Step/acestep-v15-xl-turbo13license: mit14app_file: app.py15short_description: Music Generation Foundation Model v1.516---17 18<h1 align="center">ACE-Step 1.5</h1>19<h1 align="center">Pushing the Boundaries of Open-Source Music Generation</h1>20<p align="center">21    <a href="https://ace-step.github.io/ace-step-v1.5.github.io/">Project</a> |22    <a href="https://huggingface.co/collections/ACE-Step/ace-step-15">Hugging Face</a> |23    <a href="https://modelscope.cn/models/ACE-Step/ACE-Step-v1-5">ModelScope</a> |24    <a href="https://huggingface.co/spaces/ACE-Step/Ace-Step-v1.5">Space Demo</a> |25    <a href="https://discord.gg/PeWDxrkdj7">Discord</a> |26    <a href="https://arxiv.org/abs/2602.00744">Technical Report</a>27</p>28 29<p align="center">30    <img src="./assets/orgnization_logos.png" width="100%" alt="StepFun Logo">31</p>32 33## Table of Contents34 35- [✨ Features](#-features)36- [📦 Installation](#-installation)37- [🚀 Usage](#-usage)38- [🔨 Train](#-train)39- [🏗️ Architecture](#️-architecture)40- [🦁 Model Zoo](#-model-zoo)41 42## 📝 Abstract43We present ACE-Step v1.5, a highly efficient foundation model that democratizes commercial-grade music production on consumer hardware. Optimized for local deployment (<4GB VRAM), the model accelerates generation by over 100× compared to traditional pure LM architectures, producing superior high-fidelity audio in seconds characterized by coherent semantics and exceptional melodies. At its core lies a novel hybrid architecture where the Language Model (LM) functions as an omni-capable planner: it transforms simple user queries into comprehensive song blueprints—scaling from short loops to 10-minute compositions—while synthesizing metadata, lyrics, and captions via Chain-of-Thought to guide the Diffusion Transformer (DiT). Uniquely, this alignment is achieved through intrinsic reinforcement learning relying solely on the model’s internal mechanisms, thereby eliminating the biases inherent in external reward models or human preferences. Beyond standard synthesis, ACE-Step v1.5 unifies precise stylistic control with versatile editing capabilities—such as cover generation, repainting, and vocal-to-BGM conversion—while maintaining strict adherence to prompts across 50+ languages.44 45 46## ✨ Features47 48<p align="center">49    <img src="./assets/application_map.png" width="100%" alt="ACE-Step Framework">50</p>51 52### ⚡ Performance53- ✅ **Ultra-Fast Generation** — 0.5s to 10s generation time on A100 (depending on think mode & diffusion steps)54- ✅ **Flexible Duration** — Supports 10 seconds to 10 minutes (600s) audio generation55- ✅ **Batch Generation** — Generate up to 8 songs simultaneously56 57### 🎵 Generation Quality58- ✅ **Commercial-Grade Output** — Quality between Suno v4.5 and Suno v559- ✅ **Rich Style Support** — 1000+ instruments and styles with fine-grained timbre description60- ✅ **Multi-Language Lyrics** — Supports 50+ languages with lyrics prompt for structure & style control61 62### 🎛️ Versatility & Control63 64| Feature | Description |65|---------|-------------|66| ✅ Reference Audio Input | Use reference audio to guide generation style |67| ✅ Cover Generation | Create covers from existing audio |68| ✅ Repaint & Edit | Selective local audio editing and regeneration |69| ✅ Track Separation | Separate audio into individual stems |70| ✅ Multi-Track Generation | Add layers like Suno Studio's "Add Layer" feature |71| ✅ Vocal2BGM | Auto-generate accompaniment for vocal tracks |72| ✅ Metadata Control | Control duration, BPM, key/scale, time signature |73| ✅ Simple Mode | Generate full songs from simple descriptions |74| ✅ Query Rewriting | Auto LM expansion of tags and lyrics |75| ✅ Audio Understanding | Extract BPM, key/scale, time signature & caption from audio |76| ✅ LRC Generation | Auto-generate lyric timestamps for generated music |77| ✅ LoRA Training | One-click annotation & training in Gradio. 8 songs, 1 hour on 3090 (12GB VRAM) |78| ✅ Quality Scoring | Automatic quality assessment for generated audio |79 80 81 82## 📦 Installation83 84> **Requirements:** Python 3.11, CUDA GPU recommended (works on CPU/MPS but slower)85 86### 1. Install uv (Package Manager)87 88```bash89# macOS / Linux90curl -LsSf https://astral.sh/uv/install.sh | sh91 92# Windows (PowerShell)93powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"94```95 96### 2. Clone & Install97 98```bash99git clone https://github.com/ACE-Step/ACE-Step-1.5.git100cd ACE-Step-1.5101uv sync102```103 104### 3. Launch105 106#### 🖥️ Gradio Web UI (Recommended)107 108```bash109uv run acestep110```111 112Open http://localhost:7860 in your browser. Models will be downloaded automatically on first run.113 114#### 🌐 REST API Server115 116```bash117uv run acestep-api118```119 120API runs at http://localhost:8001. See [API Documentation](./docs/en/API.md) for endpoints.121 122### Command Line Options123 124**Gradio UI (`acestep`):**125 126| Option | Default | Description |127|--------|---------|-------------|128| `--port` | 7860 | Server port |129| `--server-name` | 127.0.0.1 | Server address (use `0.0.0.0` for network access) |130| `--share` | false | Create public Gradio link |131| `--language` | en | UI language: `en`, `zh`, `ja` |132| `--init_service` | false | Auto-initialize models on startup |133| `--config_path` | auto | DiT model (e.g., `acestep-v15-turbo`, `acestep-v15-turbo-shift3`) |134| `--lm_model_path` | auto | LM model (e.g., `acestep-5Hz-lm-0.6B`, `acestep-5Hz-lm-1.7B`) |135| `--offload_to_cpu` | auto | CPU offload (auto-enabled if VRAM < 16GB) |136 137**Examples:**138 139```bash140# Public access with Chinese UI141uv run acestep --server-name 0.0.0.0 --share --language zh142 143# Pre-initialize models on startup144uv run acestep --init_service true --config_path acestep-v15-turbo145```146 147### Development148 149```bash150# Add dependencies151uv add package-name152uv add --dev package-name153 154# Update all dependencies155uv sync --upgrade156```157 158## 🚀 Usage159 160We provide multiple ways to use ACE-Step:161 162| Method | Description | Documentation |163|--------|-------------|---------------|164| 🖥️ **Gradio Web UI** | Interactive web interface for music generation | [Gradio Guide](./docs/en/GRADIO_GUIDE.md) |165| 🐍 **Python API** | Programmatic access for integration | [Inference API](./docs/en/INFERENCE.md) |166| 🌐 **REST API** | HTTP-based async API for services | [REST API](./docs/en/API.md) |167 168**📚 Documentation available in:** [English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)169 170 171## 🔨 Train172 173See the **LoRA Training** tab in Gradio UI for one-click training, or check [Gradio Guide - LoRA Training](./docs/en/GRADIO_GUIDE.md#lora-training) for details.174 175## 🏗️ Architecture176 177<p align="center">178    <img src="./assets/ACE-Step_framework.png" width="100%" alt="ACE-Step Framework">179</p>180 181## 🦁 Model Zoo182 183<p align="center">184    <img src="./assets/model_zoo.png" width="100%" alt="Model Zoo">185</p>186 187### DiT Models188 189| DiT Model | Pre-Training | SFT | RL | CFG | Step | Refer audio | Text2Music | Cover | Repaint | Extract | Lego | Complete | Quality | Diversity | Fine-Tunability | Hugging Face |190|-----------|:------------:|:---:|:--:|:---:|:----:|:-----------:|:----------:|:-----:|:-------:|:-------:|:----:|:--------:|:-------:|:---------:|:---------------:|--------------|191| `acestep-v15-base` | ✅ | ❌ | ❌ | ✅ | 50 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Medium | High | Easy | [Link](https://huggingface.co/ACE-Step/acestep-v15-base) |192| `acestep-v15-sft` | ✅ | ✅ | ❌ | ✅ | 50 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | High | Medium | Easy | [Link](https://huggingface.co/ACE-Step/acestep-v15-sft) |193| `acestep-v15-turbo` | ✅ | ✅ | ❌ | ❌ | 8 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | Very High | Medium | Medium | [Link](https://huggingface.co/ACE-Step/Ace-Step1.5) |194| `acestep-v15-turbo-rl` | ✅ | ✅ | ✅ | ❌ | 8 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | Very High | Medium | Medium | To be released |195 196### LM Models197 198| LM Model | Pretrain from | Pre-Training | SFT | RL | CoT metas | Query rewrite | Audio Understanding | Composition Capability | Copy Melody | Hugging Face |199|----------|---------------|:------------:|:---:|:--:|:---------:|:-------------:|:-------------------:|:----------------------:|:-----------:|--------------|200| `acestep-5Hz-lm-0.6B` | Qwen3-0.6B | ✅ | ✅ | ✅ | ✅ | ✅ | Medium | Medium | Weak | ✅ |201| `acestep-5Hz-lm-1.7B` | Qwen3-1.7B | ✅ | ✅ | ✅ | ✅ | ✅ | Medium | Medium | Medium | ✅ |202| `acestep-5Hz-lm-4B` | Qwen3-4B | ✅ | ✅ | ✅ | ✅ | ✅ | Strong | Strong | Strong | To be released |203 204## 📜 License & Disclaimer205 206This project is licensed under [MIT](./LICENSE)207 208ACE-Step enables original music generation across diverse genres, with applications in creative production, education, and entertainment. While designed to support positive and artistic use cases, we acknowledge potential risks such as unintentional copyright infringement due to stylistic similarity, inappropriate blending of cultural elements, and misuse for generating harmful content. To ensure responsible use, we encourage users to verify the originality of generated works, clearly disclose AI involvement, and obtain appropriate permissions when adapting protected styles or materials. By using ACE-Step, you agree to uphold these principles and respect artistic integrity, cultural diversity, and legal compliance. The authors are not responsible for any misuse of the model, including but not limited to copyright violations, cultural insensitivity, or the generation of harmful content.209 210🔔 Important Notice  211The only official website for the ACE-Step project is our GitHub Pages site.    212 We do not operate any other websites.  213🚫 Fake domains include but are not limited to:214ac\*\*p.com, a\*\*p.org, a\*\*\*c.org  215⚠️ Please be cautious. Do not visit, trust, or make payments on any of those sites.216 217## 🙏 Acknowledgements218 219This project is co-led by ACE Studio and StepFun.220 221 222## 📖 Citation223 224If you find this project useful for your research, please consider citing:225 226```BibTeX227@misc{gong2026acestep,228	title={ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation},229	author={Junmin Gong, Song Yulin, Wenxiao Zhao, Sen Wang, Shengyuan Xu, Jing Guo}, 230	howpublished={\url{https://github.com/ace-step/ACE-Step-1.5}},231	year={2026},232	note={GitHub repository}233}234```235