Blame for README.md

---
title: ACE-Step Music + Vevo Voice Clone + MiniMax-H3 Avatar
emoji: 🎵
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.2.0
python_version: 3.11
pinned: false
models: 
 - ACE-Step/Ace-Step1.5
 - ACE-Step/acestep-v15-xl-sft
 - amphion/Vevo
 - multimodalart/MiniMax-H3-Pruned
 - MiniMaxAI/MiniMax-H3
 - larryvrh/MiniMax-H3-Turbo-Lora
 - hfmlsoc/ncii-light-guard-v01
license: mit
app_file: app.py
short_description: Music (GPU) + voice cloning (CPU) + talking avatar (GPU)
startup_duration_timeout: 1h
---

## 🆕 اسپیسِ ترکیبی: «ساخت آهنگ» + «کلون کردن صدا» + «آواتار سخنگو» در یک اسپیس

این اسپیس سه بخش دارد که هر کدام همان اسپیسِ قبلیِ خودش است — هیچ قابلیتی کم نشده:

| تب | چه چیزی | سخت‌افزار | فایل‌ها |
|---|---|---|---|
| 🎵 ساخت آهنگ | همان ACE-Step v1.5 (XL SFT)، همه‌ی قابلیت‌ها: ساده/سفارشی/کاور/بازسازی، LoRA، امتیاز، LRC، کد پیگیری و ادامه‌ی ساخت | **GPU** (ZeroGPU، کارتِ large، مثلِ قبل) | `app.py`، `acestep/` |
| 🎙️ کلون کردن صدا | همان اسپیسِ صدای قبلی (Vevo، تبدیلِ timbre با ۳۲ گام، برشِ هوشمند از روی سکوت) — حالا با **جای دوم** (فقط وقتی لازم است)، **سقفِ ۱۲ ثانیه برای صدای مرجع** و **لغوِ کارِ بی‌صاحب** | **فقط CPU** (همه‌ی هسته‌ها، بدونِ مصرفِ سهمیه‌ی GPU) | `voice_clone.py`، `voice_engine.py` |
| 🗣️ آواتار سخنگو | همان اسپیسِ آواتارِ قبلی (MiniMax-H3: عکس + صدا ← ویدیوی سخنگو، LoRAی توربو، فیلترِ محتوا، همه‌ی بوم‌ها، Upsample prompt) — بدونِ روشِ فایلِ `.pt` | **GPU** (ZeroGPU، کارتِ xlarge، مثلِ قبل) | `avatar_tab.py`، `h3_*.py`، `ncii_guard.py` |

### مسیرهای API (برای اکشن پرو و هر کلاینتِ دیگر)

| کار | مسیر | ورودی ← خروجی |
|---|---|---|
| ساخت آهنگ | دکمه‌ی **Generate Music** (همان قبلی؛ `generation_wrapper`) | همان ۵۴ ورودیِ قبلی ← همان ۵۵ خروجی. اکشن پرو تابع را از روی نامِ دکمه و تعدادِ ورودی‌ها در کانفیگ پیدا می‌کند. |
| کلون کردن صدا | `/predict_voice_conversion` (همان نامِ اسپیسِ صدای قبلی) | `[صدای منبع، صدای مرجع]` ← یک فایل WAV (۲۴ کیلوهرتز، مونو) |
| وضعیتِ بخشِ صدا | `POST /gradio_api/run/voice_status` با بدنه‌ی `{"data": []}` | `{"ready", "warm", "running", "waiting", "fn_index", "slots", "concurrency", ...}` — فقط صفِ صدا، بدونِ صف و فوری |
| آواتار سخنگو | `/generate` (همان مسیرِ اسپیسِ آواتارِ قبلی) | `[prompt، عکس، صدا، canvas، duration (۲ تا ۱۴)، steps، seed، upsample]` ← `[ویدیو، گزارش، پرامپتِ بهبودیافته]` |

مسیرهای کمکیِ صفحه‌ی آواتار هم مثلِ قبل هستند: `/fit_keyframe` (برشِ عکس به نزدیک‌ترین نسبت) و
`/audio_duration` (مدت از روی صدا). مسیرهای حذف‌شده‌ی آواتار: `/animate_a2v` و `/forget_a2v` (روشِ `.pt`).

### 🎙️ سرعتِ صدا — از روی لاگ‌های اسپیسِ قبلی (آهنگ + صدا)

لاگ‌ها نشان می‌دادند یک تکه‌ی ۶ ثانیه‌ای گاهی در ۱۵ تا ۲۰ ثانیه و گاهی در ۴۰ تا ۹۰ و حتی **بیش از ۲۰۰ ثانیه** ساخته می‌شد (و
فایل‌های ۲۹ تکه‌ای با «تبدیل صدا بیش از حد طول کشید» و `BrokenPipeError` تمام می‌شدند). علت‌ها و رفعشان:

1. **صدای مرجعِ بلند (علتِ اصلی).** مدلِ Vevo صدای مرجع را جلوی **هر** تکه می‌گذارد و هر بار کاملش را پردازش می‌کند.
   مرجعِ ۳ دقیقه‌ای یعنی هر تکه‌ی ۶ ثانیه‌ای مثلِ یک صدای ~۳ دقیقه‌ای حساب می‌شد؛ برای همین ۲۰۰ ثانیه‌ای‌های لاگ تقریباً
   مستقل از طولِ تکه بودند (۲٫۱ ثانیه ← ۲۰۵ ثانیه، ۷٫۸ ثانیه ← ۲۰۴٫۶ ثانیه). مدل با مرجعِ حداکثر ~۱۲ ثانیه آموزش دیده؛ حالا
   از مرجعِ بلندتر **پُرصداترین ۱۲ ثانیه** (بیشترین گفتار؛ شروع درست پیش از گفتار، پایان روی مکث) برداشته می‌شود
   (`VOICE_REF_MAX_SECONDS`). مرجعِ تا ۱۲٫۵ ثانیه هیچ تغییری نمی‌کند. اکشن پرو هم همین را پیش از ارسال انجام می‌دهد.
2. **کارِ بی‌صاحب.** اگر درخواست‌دهنده رفت (اتصالش قطع شد یا زمانش تمام شد)، موتور قبلاً کار را تا آخر ادامه می‌داد و
   کارهای بعدی پشتش می‌ماندند (همان ۶۴۵ و ۶۴۷ ثانیه‌ای‌ها برای فایل‌های دوتکه‌ای و `BrokenPipe`ها). حالا همان لحظه (در گامِ بعدیِ مدل) لغو
   می‌شود و CPU و جایش آزاد می‌شود؛ در لاگ فقط یک خط: `⏹️ … لغو شد`.
3. **اولین درخواست.** یک تبدیلِ آزمایشیِ ۲ ثانیه‌ای پیش از اولین درخواست، کارهای یک‌باره‌ی مدل/librosa را انجام می‌دهد
   (قبلاً اولین کاربر ~۴۰ ثانیه برای یک تکه‌ی ۶ ثانیه‌ای منتظر می‌ماند).
4. **رندرِ سمتِ سرور (SSR) خاموش** شد (`ssr_mode=False`): فقط CPU مصرف می‌کرد و خطای `[405] POST /upload` می‌داد.
5. هشدارهای بی‌خطرِ «PySoundFile failed… audioread» (خواندنِ بعضی mp3ها) دیگر در لاگ نمی‌آیند؛ رفتار همان است.

با این سقف، روی اسپیسِ خالی یک تکه‌ی ۶ ثانیه‌ای باید حدودِ ۱۵ ثانیه باشد — همان که در لاگ‌ها برای مرجع‌های کوتاه دیده
می‌شد (۶٫۰ ثانیه ← ۱۵٫۲ ثانیه). برای هر فایلِ چندتکه‌ای، زمانِ هر
تکه هم در لاگ چاپ می‌شود: `[CPU MODE] chunk 3/8: 6.1s in 14.2s (16 threads)`.

### 🎙️ «کارِ دوم هم‌زمان» (جای دوم) — فقط وقتی لازم است

اسکرین‌شات نشان می‌داد یک تبدیلِ تنها فقط ۵۰ تا ۷۰ درصدِ CPU را می‌گیرد. حالا هر اسپیس تا **دو** تبدیل را هم‌زمان قبول
می‌کند (`VOICE_CONCURRENCY_LIMIT=2`)، ولی اکشن پرو «کارِ دوم» را **فقط وقتی می‌فرستد که هیچ اسپیسِ صدای خالیِ دیگری
نمانده** (تا وقتی اسپیسِ خالی هست، هر اسپیس فقط یک کار).

* کارِ تنها همه‌ی هسته‌ها را می‌گیرد (دقیقاً مثلِ قبل). وقتی دو کار با هم‌اند، هر کدام نصفِ هسته‌ها؛ این تقسیم در **هر
  گامِ** مدل دوباره حساب می‌شود، پس به‌محضِ تمام شدنِ یکی، دیگری دوباره همه‌ی هسته‌ها را می‌گیرد.
* تکه‌های یک فایل مثلِ قبل یکی‌یکی و به ترتیب ساخته و به هم وصل می‌شوند؛ هر تکه دقیقاً مثلِ قبل (همان نرمال‌سازی، همان
  ۳۲ گام، همان مدل). مسیرِ API همان `/predict_voice_conversion` است (هیچ مسیرِ تازه‌ای لازم نیست).
* `voice_status` حالا `"slots": 2` را اعلام می‌کند؛ اکشن پرو از روی همین می‌فهمد این اسپیس جای دوم دارد.

### سه بخش کنارِ هم — CPU، GPU، رم و دیسک

* **صدا** در یک پروسه‌ی جدا (`voice_engine.py`) که `spaces`/ZeroGPU را اصلاً ایمپورت نمی‌کند؛ پس مثلِ قبل فقط CPU و رم
  مصرف می‌کند و fork‌های ZeroGPU هیچ‌وقت وسطِ کارِ چندرشته‌ایِ صدا گیر نمی‌کنند.
* **آهنگ** دقیقاً مثلِ قبل: `@spaces.GPU`، کارتِ large، همان زمان‌ها؛ ZeroGPU فقط وزن‌های آهنگ را در بسته‌اش دارد.
* **آواتار** روی کارتِ xlarge (مثلِ قبل) ولی با جای‌گذاریِ «تنبل» (`H3_PLACEMENT=lazy`): ZeroGPU هر وزنی را که موقعِ
  بالا آمدن روی `cuda` برود در یک بسته‌ی مشترک می‌گذارد و در **هر** کارِ GPU (آهنگ یا آواتار) همه‌اش را روی کارت
  می‌برد. ترنسفورمرِ آواتار ۵۱ گیگابایت است؛ در بسته‌ی مشترک:
  * هر ساختِ آهنگ (کارتِ large، ۴۸ گیگ) با ۱۶ + ۵۱ گیگ وزن پُر می‌شد،
  * بسته از آستانه‌ی ۴۲ گیگیِ ZeroGPU می‌گذشت و زمانِ رزروِ آهنگ هم عوض می‌شد،
  * دیسک (وزن‌های دانلودی + نسخه‌ی دومِ بسته) به سقفِ ۱۵۰ گیگِ ZeroGPU می‌رسید.

  پس آواتار وزن‌هایش را خودش داخلِ همان مرحله‌ی GPUِ خودش روی کارت می‌برد، و کارگرِ GPUِ آواتار هم وزن‌های آهنگ را
  روی کارتش نمی‌برد (هوکِ کوچکِ `_move` در `avatar_tab.py`)؛ یعنی کلِ کارت مثلِ قبل مالِ آواتار است.
* **ترتیبِ بالا آمدن:** موتورِ صدا و فیلترِ محتوای آواتار (هر دو پروسه‌ی جدا، فقط CPU) ← مدل‌های آهنگ ← بسته‌بندیِ
  ZeroGPU (وزن‌های آهنگ از رم آزاد می‌شوند) ← مدلِ آواتار ← اولین درخواست. یعنی وقتی اسپیس «Running» شد هر سه آماده‌اند
  و اوجِ مصرفِ رم هم پایین می‌ماند.
* **رم:** وزن‌های آواتار (۶۱ گیگ) مستقیم از فایل‌های safetensors «نگاشت» می‌شوند (mmap)، یعنی حافظه‌ی کشِ فایل‌اند نه
  حافظه‌ی ثابتِ برنامه: سیستم هر وقت رم لازم داشت می‌تواند آزادشان کند و دوباره از دیسک بخواند (آزموده شد: ~۹۰٪ وزن‌ها
  پس از بارگذاری همان نگاشتِ فایل‌اند). پس با آهنگ و صدا هم زیرِ ۱۰۴ گیگ می‌ماند.
* **دیسک:** ≈ ۶۱ گیگ آواتار + ~۳۵ گیگ آهنگ (فایل‌ها + بسته‌ی ZeroGPU) + ~۵ گیگ صدا ≈ ۱۰۰ گیگ — زیرِ سقفِ ۱۵۰ گیگ
  (اگر آواتار هم در بسته‌ی ZeroGPU می‌رفت، نسخه‌ی دومِ ۵۱ گیگی‌اش این را به سقف می‌رساند).
* اولین روشن‌شدن همه‌ی مدل‌ها را دانلود می‌کند (حدودِ ۱۰۰ گیگ)؛ برای همین `startup_duration_timeout` یک ساعت است.

### وابستگی‌ها (چرا diffusers داخلِ `vendor/` است)

آواتار به **diffusers main در کامیتِ `d5baa4fb`** نیاز دارد (MiniMax-H3 و LoRAی آن هنوز در هیچ نسخه‌ی منتشرشده‌ای که با این
محیط سازگار باشد نیست). آن کامیت `huggingface_hub>=1.23` می‌خواهد، ولی ساختِ آهنگ (ACE-Step) `transformers<4.58` لازم دارد و
transformers 4.57 هنگامِ ایمپورت فقط `huggingface_hub<1.0` را قبول می‌کند؛ pip این دو را با هم نصب نمی‌کند.
راه‌حل: همان کامیت به‌صورتِ یک فایلِ zip در `vendor/diffusers-d5baa4fb.zip` است و `app.py` آن را پیش از هر چیز به
مسیرِ ایمپورت اضافه می‌کند (هم VAEِ آهنگ و هم کلِ آواتار از همین استفاده می‌کنند). کدِ diffusers در عمل فقط در یک جا به
`huggingface_hub>=1.23` نیاز داشت (فهرستِ فایل‌ها در حالتِ آفلاین) که سازگار شد — توضیحِ کامل در `vendor/README.md`.

بقیه همان نسخه‌های آهنگ است (Python 3.11، torch 2.9.1، transformers 4.57.x، gradio 6.2.0، numpy<2) به‌اضافه‌ی
`peft==0.18.1` (همان نسخه‌ی LoRAی توربو)، `safetensors>=0.8.0` و `av`. این ترکیب بیرون از اسپیس آزموده شد: همه‌ی
ماژول‌های آواتار با همین نسخه‌ها ایمپورت می‌شوند و یک MiniMax-H3ِ کوچکِ تصادفی کلِ مسیرِ `fl2va`/`t2va` (صدای قفل‌شده،
دیکودِ ویدیو، ساختِ mp4 با صدا) و بارگذاریِ LoRA را روی CPU تا آخر اجرا کرد.

### 🗣️ رفعِ خطای `TypeError` در ساختِ آواتار

لاگِ اسپیس نشان داد هر درخواستی که از مرحله‌ی «کاندیشنر» رد می‌شد، در مرحله‌ی GPU با
`TypeError: int() argument must be … not 'NoneType'` (سطرِ `manual_seed(int(seed))`) شکست می‌خورد: مقدارِ `seed` خالی
(`None`) به مرحله‌ی GPU می‌رسید. اکشن پرو این خطا را «گام زیاد است» فرض می‌کرد، گام را کم و کلید را عوض می‌کرد تا به کفِ
گام برسد و کاربر «ساخت آواتار ممکن نشد» می‌دید. حالا `seed` یا `steps`ِ خالی/نامعتبر هرگز ویدیو را خراب نمی‌کند (پیش‌فرض:
`seed=42`، گامِ پیش‌فرضِ مدل) و یک خطِ `[gen] ⚠️ … empty value` در لاگ نشان می‌دهد چنین درخواستی رسیده است.

### چه چیزی از اسپیسِ آواتار حذف شد (طبقِ درخواست)

* روشِ **فایلِ `.pt`** (رندرِ مرحله‌ایِ ادامه‌پذیر تا ۶۰ ثانیه): `h3_a2v_resume.py`، بخشِ «Resumable render» صفحه،
  مسیرهای `/animate_a2v` و `/forget_a2v`، دکمه‌ی تخمین، آزمون‌های `tests/` و `GUIDE_FA.md` که فقط درباره‌ی همین روش بودند.
  حالا مثلِ حالتِ `H3_RESUME=0` اسپیسِ قبلی: هر ویدیو یک مرحله‌ی GPU و حداکثر ۱۴ ثانیه (کیفیتِ پایین در همان یک مرحله تمام
  می‌شود). اکشن پرو ویدیوهای بلندتر را مثلِ قبل تکه‌تکه می‌سازد.
* فایل‌های `.whl` که در ریشه‌ی اسپیسِ آواتار بودند (برای پایتون ۳٫۱۲؛ در هیچ جای کد استفاده نمی‌شدند).
* قالبِ ظاهری (theme) و CSSِ سراسریِ آواتار: یک اسپیس فقط یک قالب دارد و قالبِ بخشِ آهنگ عوض نشد.

### محدودیتِ GPU برای «هر حساب» است، نه هر اسپیس

طبقِ تجربه: خطای «No GPU was available after 60s» یعنی هاگینگ‌فیس **کلِ حساب** را محدود کرده و همه‌ی اسپیس‌های GPUِ
آن حساب با هم محدود می‌شوند — آهنگ و آواتار با هم. برای همین اکشن پرو با اینکه همه‌ی این اسپیس‌ها آهنگ و آواتار دارند،
برای کارهای GPU (آهنگ **و** آواتار) فقط **یک** اسپیس از هر حساب می‌گذارد و خطای No GPU روی هر کدام، آن حساب را
**۳۰ دقیقه** برای هر دو کنار می‌گذارد؛ ولی در چرخشِ صدا (CPU) **همه‌ی** اسپیس‌ها حضور دارند. توضیحِ کامل در README و
`space_rotation.py` اکشن پرو.

### متغیرهای اختیاری

| متغیر | پیش‌فرض | کار |
|---|---|---|
| `VOICE_CONCURRENCY_LIMIT` | `2` | چند تبدیلِ صدا هم‌زمان (۱ = یکی‌یکی، رفتارِ قبلی) |
| `VOICE_REF_MAX_SECONDS` | `12` | سقفِ صدای مرجع (۰ = بدونِ سقف، رفتارِ قبلی) |
| `VOICE_ENGINE_WAIT_SECONDS` / `VOICE_JOB_TIMEOUT_SECONDS` | `900` / `3600` | انتظار تا آماده‌شدنِ موتورِ صدا / سقفِ یک تبدیل |
| `VOICE_ENGINE_DISABLED` | — | `1` = بخشِ صدا خاموش |
| `AVATAR_DISABLED` | — | `1` = بخشِ آواتار خاموش (نه مدل بالا می‌آید نه تب ساخته می‌شود) |
| `H3_PLACEMENT` | `lazy` | جای‌گذاریِ وزن‌های آواتار (توضیحِ بالا؛ `pack` در اسپیسِ ترکیبی توصیه نمی‌شود) |
| `H3_TURBO`، `H3_ATTENTION`، `H3_GPU_SIZE`، `H3_MODEL_REPO`، `H3_CONDITIONER`، `H3_AOTI` | مثلِ قبل | همان متغیرهای اسپیسِ آواتار |

### آن‌چه این‌جا نمی‌شد آزمود

اجرای واقعی روی ZeroGPU و دانلودِ مدل‌های واقعی (دسترسی به GPU و هاگینگ‌فیس در محیطِ ساخت نبود). کدِ رابط، مسیرهای API،
زمان‌بندیِ دو کارِ هم‌زمان (تقسیمِ هسته‌ها در هر گام)، لغوِ کارِ بی‌صاحب، سقفِ صدای مرجع، هوک‌های ZeroGPU (با کدِ واقعیِ `spaces` 0.51.3) و کلِ مسیرِ آواتار با مدلِ کوچک آزموده شدند. اولین
بار لاگِ اسپیس را ببینید: خطِ `[gen] ready in …s (placement: lazy, turbo: on)` یعنی آواتار بالا آمده و
`[turbo] … 363 modules (51 AdaLN + 312 attention/FF), 51 AdaLN projection offsets` یعنی LoRAی توربو کامل نشسته است.

---

<h1 align="center">MiniMax-H3 — a first frame and a soundtrack you provide (the 🗣️ tab)</h1>

MiniMax-H3 denoises video and audio as **one packed sequence**, under two schedules (`shift = 12` for video,
`shift = 3` for audio). In the `fl2va` workflow the keyframe anchors the leading video rows and the audio rows are
drawn from noise like any other generated row, so the model invents its own soundtrack. This tab hands it the audio
rows instead: the upload is encoded by the model's own audio VAE, normalized the way the pipeline normalizes any
soundtrack, and imposed on the audio rows at every step — so the video is denoised alongside a soundtrack it does not
get to choose. **The first frame is optional**: without one the request is `t2va` and the canvas comes from the
Canvas dropdown alone.

* **How the soundtrack is imposed.** The audio rows are *locked*: your clip is written into them clean and written
  back clean after every scheduler step, and the row-timestep plan presents them at `t = 1.0`. The file you get back
  carries **your** upload as its soundtrack. `h3_a2v_blocks.py` also implements `blended` and `off` (kept for the a2v
  LoRA sweep), which this app does not reach.
* **Prompt upsampling.** *Upsample prompt* hands the rewrite to the conditioner Space, which rewrites the prompt on its
  own Qwen3-VL looking at your keyframe, encodes the rewrite, and returns it in the *Upsampled prompt* panel.
* **Speed: the turbo LoRA.** [`larryvrh/MiniMax-H3-Turbo-Lora`](https://huggingface.co/larryvrh/MiniMax-H3-Turbo-Lora)
  (`minimax_h3_turbo_v4_step600_ema.safetensors`) at scale 1.0, **7 steps** (6 NFE). A correct attach is **363
  modules and 51 AdaLN projection offsets**, both checked at startup; a mismatch removes the adapter and falls back
  to the base model at 28 steps. `H3_TURBO=0` loads the base model instead.
* **Split deployment.** This Space is the denoising half and runs
  [`multimodalart/MiniMax-H3-Pruned`](https://huggingface.co/multimodalart/MiniMax-H3-Pruned) (51.3 GB); the 62 GiB
  Qwen3-VL conditioner runs in
  [`qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner), called over the gradio API
  for every request (`prompt_embeds` + `text_token_tags` is the whole wire format). Its booking is billed to whoever
  asked for the video.
* **Content filter.** Every prompt goes through
  [`hfmlsoc/ncii-light-guard-v01`](https://huggingface.co/hfmlsoc/ncii-light-guard-v01) (a 270M CPU classifier, in its
  own process) before any GPU time is spent; a flagged prompt is refused with
  "This prompt was flagged by a content filter and wasn't run."
* **Length.** 2–14 s per request (one segment; 15 s snaps to 362 frames, past the model's ceiling).
* **Examples.** `examples/avatar/subject.png` (a studio portrait, free to use) and `examples/avatar/voice.wav`
  (6.5 s of speech), the ones the sibling `minimax-h3-reference` Space ships.

---

> **Note on this fork:** the default DiT model was switched from `acestep-v15-xl-turbo`
> (8-step, guidance-distilled, optimized for speed) to `acestep-v15-xl-sft` (50-step,
> full classifier-free guidance, optimized for audio quality — the 5B-parameter XL
> checkpoint, not guidance-distilled). This is the highest-quality checkpoint ACE-Step
> currently publishes; it is the same weights as `ACE-Step/acestep-v15-xl-sft-diffusers`,
> just loaded through this repo's native handler instead of HF `diffusers`. Set the
> `SERVICE_MODE_DIT_MODEL` Space variable back to `acestep-v15-xl-turbo` if you want
> the fast/turbo behavior instead. Needs ~20GB VRAM without CPU offload (~12GB with).

<h1 align="center">ACE-Step 1.5</h1>
<h1 align="center">Pushing the Boundaries of Open-Source Music Generation</h1>
<p align="center">
    <a href="https://ace-step.github.io/ace-step-v1.5.github.io/">Project</a> |
    <a href="https://huggingface.co/collections/ACE-Step/ace-step-15">Hugging Face</a> |
    <a href="https://modelscope.cn/models/ACE-Step/ACE-Step-v1-5">ModelScope</a> |
    <a href="https://huggingface.co/spaces/ACE-Step/Ace-Step-v1.5">Space Demo</a> |
    <a href="https://discord.gg/PeWDxrkdj7">Discord</a> |
    <a href="https://arxiv.org/abs/2602.00744">Technical Report</a>
</p>

<p align="center">
    <img src="./assets/orgnization_logos.png" width="100%" alt="StepFun Logo">
</p>

## Table of Contents

- [✨ Features](#-features)
- [📦 Installation](#-installation)
- [🚀 Usage](#-usage)
- [🔨 Train](#-train)
- [🏗️ Architecture](#️-architecture)
- [🦁 Model Zoo](#-model-zoo)

## 📝 Abstract
We 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.


## ✨ Features

<p align="center">
    <img src="./assets/application_map.png" width="100%" alt="ACE-Step Framework">
</p>

### ⚡ Performance
- ✅ **Ultra-Fast Generation** — 0.5s to 10s generation time on A100 (depending on think mode & diffusion steps)
- ✅ **Flexible Duration** — Supports 10 seconds to 10 minutes (600s) audio generation
- ✅ **Batch Generation** — Generate up to 8 songs simultaneously

### 🎵 Generation Quality
- ✅ **Commercial-Grade Output** — Quality between Suno v4.5 and Suno v5
- ✅ **Rich Style Support** — 1000+ instruments and styles with fine-grained timbre description
- ✅ **Multi-Language Lyrics** — Supports 50+ languages with lyrics prompt for structure & style control

### 🎛️ Versatility & Control

| Feature | Description |
|---------|-------------|
| ✅ Reference Audio Input | Use reference audio to guide generation style |
| ✅ Cover Generation | Create covers from existing audio |
| ✅ Repaint & Edit | Selective local audio editing and regeneration |
| ✅ Track Separation | Separate audio into individual stems |
| ✅ Multi-Track Generation | Add layers like Suno Studio's "Add Layer" feature |
| ✅ Vocal2BGM | Auto-generate accompaniment for vocal tracks |
| ✅ Metadata Control | Control duration, BPM, key/scale, time signature |
| ✅ Simple Mode | Generate full songs from simple descriptions |
| ✅ Query Rewriting | Auto LM expansion of tags and lyrics |
| ✅ Audio Understanding | Extract BPM, key/scale, time signature & caption from audio |
| ✅ LRC Generation | Auto-generate lyric timestamps for generated music |
| ✅ LoRA Training | One-click annotation & training in Gradio. 8 songs, 1 hour on 3090 (12GB VRAM) |
| ✅ Quality Scoring | Automatic quality assessment for generated audio |



## 📦 Installation

> **Requirements:** Python 3.11, CUDA GPU recommended (works on CPU/MPS but slower)

### 1. Install uv (Package Manager)

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

### 2. Clone & Install

```bash
git clone https://github.com/ACE-Step/ACE-Step-1.5.git
cd ACE-Step-1.5
uv sync
```

### 3. Launch

#### 🖥️ Gradio Web UI (Recommended)

```bash
uv run acestep
```

Open http://localhost:7860 in your browser. Models will be downloaded automatically on first run.

#### 🌐 REST API Server

```bash
uv run acestep-api
```

API runs at http://localhost:8001. See [API Documentation](./docs/en/API.md) for endpoints.

### Command Line Options

**Gradio UI (`acestep`):**

| Option | Default | Description |
|--------|---------|-------------|
| `--port` | 7860 | Server port |
| `--server-name` | 127.0.0.1 | Server address (use `0.0.0.0` for network access) |
| `--share` | false | Create public Gradio link |
| `--language` | en | UI language: `en`, `zh`, `ja` |
| `--init_service` | false | Auto-initialize models on startup |
| `--config_path` | auto | DiT model (e.g., `acestep-v15-turbo`, `acestep-v15-turbo-shift3`) |
| `--lm_model_path` | auto | LM model (e.g., `acestep-5Hz-lm-0.6B`, `acestep-5Hz-lm-1.7B`) |
| `--offload_to_cpu` | auto | CPU offload (auto-enabled if VRAM < 16GB) |

**Examples:**

```bash
# Public access with Chinese UI
uv run acestep --server-name 0.0.0.0 --share --language zh

# Pre-initialize models on startup
uv run acestep --init_service true --config_path acestep-v15-turbo
```

### Development

```bash
# Add dependencies
uv add package-name
uv add --dev package-name

# Update all dependencies
uv sync --upgrade
```

## 🚀 Usage

We provide multiple ways to use ACE-Step:

| Method | Description | Documentation |
|--------|-------------|---------------|
| 🖥️ **Gradio Web UI** | Interactive web interface for music generation | [Gradio Guide](./docs/en/GRADIO_GUIDE.md) |
| 🐍 **Python API** | Programmatic access for integration | [Inference API](./docs/en/INFERENCE.md) |
| 🌐 **REST API** | HTTP-based async API for services | [REST API](./docs/en/API.md) |

**📚 Documentation available in:** [English](./docs/en/) | [中文](./docs/zh/) | [日本語](./docs/ja/)


## 🔨 Train

See 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.

## 🏗️ Architecture

<p align="center">
    <img src="./assets/ACE-Step_framework.png" width="100%" alt="ACE-Step Framework">
</p>

## 🦁 Model Zoo

<p align="center">
    <img src="./assets/model_zoo.png" width="100%" alt="Model Zoo">
</p>

### DiT Models

| DiT Model | Pre-Training | SFT | RL | CFG | Step | Refer audio | Text2Music | Cover | Repaint | Extract | Lego | Complete | Quality | Diversity | Fine-Tunability | Hugging Face |
|-----------|:------------:|:---:|:--:|:---:|:----:|:-----------:|:----------:|:-----:|:-------:|:-------:|:----:|:--------:|:-------:|:---------:|:---------------:|--------------|
| `acestep-v15-base` | ✅ | ❌ | ❌ | ✅ | 50 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | Medium | High | Easy | [Link](https://huggingface.co/ACE-Step/acestep-v15-base) |
| `acestep-v15-sft` | ✅ | ✅ | ❌ | ✅ | 50 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | High | Medium | Easy | [Link](https://huggingface.co/ACE-Step/acestep-v15-sft) |
| `acestep-v15-turbo` | ✅ | ✅ | ❌ | ❌ | 8 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | Very High | Medium | Medium | [Link](https://huggingface.co/ACE-Step/Ace-Step1.5) |
| `acestep-v15-turbo-rl` | ✅ | ✅ | ✅ | ❌ | 8 | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | Very High | Medium | Medium | To be released |

### LM Models

| LM Model | Pretrain from | Pre-Training | SFT | RL | CoT metas | Query rewrite | Audio Understanding | Composition Capability | Copy Melody | Hugging Face |
|----------|---------------|:------------:|:---:|:--:|:---------:|:-------------:|:-------------------:|:----------------------:|:-----------:|--------------|
| `acestep-5Hz-lm-0.6B` | Qwen3-0.6B | ✅ | ✅ | ✅ | ✅ | ✅ | Medium | Medium | Weak | ✅ |
| `acestep-5Hz-lm-1.7B` | Qwen3-1.7B | ✅ | ✅ | ✅ | ✅ | ✅ | Medium | Medium | Medium | ✅ |
| `acestep-5Hz-lm-4B` | Qwen3-4B | ✅ | ✅ | ✅ | ✅ | ✅ | Strong | Strong | Strong | To be released |

## 📜 License & Disclaimer

This project is licensed under [MIT](./LICENSE)

ACE-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.

🔔 Important Notice  
The only official website for the ACE-Step project is our GitHub Pages site.    
 We do not operate any other websites.  
🚫 Fake domains include but are not limited to:
ac\*\*p.com, a\*\*p.org, a\*\*\*c.org  
⚠️ Please be cautious. Do not visit, trust, or make payments on any of those sites.

## 🙏 Acknowledgements

This project is co-led by ACE Studio and StepFun.


## 📖 Citation

If you find this project useful for your research, please consider citing:

```BibTeX
@misc{gong2026acestep,
	title={ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation},
	author={Junmin Gong, Song Yulin, Wenxiao Zhao, Sen Wang, Shengyuan Xu, Jing Guo}, 
	howpublished={\url{https://github.com/ace-step/ACE-Step-1.5}},
	year={2026},
	note={GitHub repository}
}
```