README.md

metadata

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ی توربو کامل نشسته است.

---

MiniMax-H3 — a first frame and a soundtrack you provide (the 🗣️ tab)

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 (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 (51.3 GB); the 62 GiB Qwen3-VL conditioner runs in 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 (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).

ACE-Step 1.5

Pushing the Boundaries of Open-Source Music Generation

Project | Hugging Face | ModelScope | Space Demo | Discord | Technical Report

Table of Contents

• ✨ Features
• 📦 Installation
• 🚀 Usage
• 🔨 Train
• 🏗️ Architecture
• 🦁 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

⚡ 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)

# 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

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)

uv run acestep

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

🌐 REST API Server

uv run acestep-api

API runs at http://localhost:8001. See API Documentation 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:

# 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

# 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
🐍 Python API	Programmatic access for integration	Inference API
🌐 REST API	HTTP-based async API for services	REST API

📚 Documentation available in: English | 中文 | 日本語

🔨 Train

See the LoRA Training tab in Gradio UI for one-click training, or check Gradio Guide - LoRA Training for details.

🏗️ Architecture

🦁 Model Zoo

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
acestep-v15-sft	✅	✅	❌	✅	50	✅	✅	✅	✅	❌	❌	❌	High	Medium	Easy	Link
acestep-v15-turbo	✅	✅	❌	❌	8	✅	✅	✅	✅	❌	❌	❌	Very High	Medium	Medium	Link
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

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:

@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}
}