ACE-Step 1.5

ACE-Step 1.5 diperkenalkan dalam ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation oleh ACE-Step Team (ACE Studio dan StepFun). Ini adalah model dasar musik open-source yang menghasilkan musik stereo berkelas komersial dengan lirik dari prompt teks.

ACE-Step 1.5 menghasilkan audio stereo dengan panjang variabel pada 48 kHz (10 detik hingga 10 menit) dari prompt teks dan lirik opsional. Sistem lengkapnya menggabungkan perencana Language Model dengan sintetizer Diffusion Transformer (DiT); pipeline ini membungkus bagian DiT dari tumpukan tersebut, dan terdiri dari tiga komponen: VAE AutoencoderOobleck yang mengompresi waveform menjadi latens stereo 25 Hz, encoder teks berbasis Qwen3 untuk kondisioning prompt dan lirik, serta DiT AceStepTransformer1DModel yang beroperasi di ruang latens VAE menggunakan flow matching.

Model ini mendukung 50+ bahasa untuk lirik — termasuk Inggris, Mandarin, Jepang, Korea, Prancis, Jerman, Spanyol, Italia, Portugis, dan Rusia — dan berjalan pada GPU konsumen (di bawah 4 GB VRAM saat di-offload).

Pipeline ini disumbangkan oleh ACE-Step Team. Basis kode aslinya dapat ditemukan di ace-step/ACE-Step-1.5.

Varian

ACE-Step 1.5 menyediakan tiga checkpoint DiT yang berbagi arsitektur transformer yang sama tetapi berbeda dalam perilaku panduan; pipeline mendeteksi secara otomatis checkpoint turbo dari konfigurasi transformer yang dimuat dan mengabaikan panduan CFG untuk bobot yang telah melalui distilasi panduan tersebut.

Varian	CFG	Langkah-langkah default	`guidance_scale` bawaan	Default `shift`	repo HF
`turbo` (guidance-distilled)	off	8	diabaikan	3.0	`ACE-Step/acestep-v15-xl-turbo-diffusers`
`base`	on	8	7.0	3.0	`ACE-Step/acestep-v15-base`
`sft`	on	8	7.0	3.0	`ACE-Step/acestep-v15-sft`

Base dan SFT menggunakan null_condition_emb yang dipelajari untuk classifier-free guidance (APG, bukan CFG vanilla). Pengguna umumnya menimpa num_inference_steps menjadi 30–60 pada base/sft untuk kualitas yang lebih tinggi.

Tips

Saat menyusun prompt, perhatikan hal-hal berikut:

Input prompt deskriptif paling efektif; gunakan kata sifat untuk menggambarkan gaya musik, instrumen, suasana, dan tempo.
Prompt harus menggambarkan karakteristik musik secara keseluruhan (misalnya, “lagu pop yang ceria dengan gitar listrik dan drum”).
Lirik harus disusun dengan tag seperti [verse], [chorus], [bridge], dan sebagainya.

Selama inferensi:

num_inference_steps, guidance_scale, dan shift secara default menggunakan nilai yang ditunjukkan di atas. Untuk checkpoint turbo, guidance_scale > 1.0 diabaikan dengan peringatan karena guidance telah di-distil ke dalam bobot.
Parameter audio_duration mengontrol durasi musik yang dihasilkan dalam detik.
Parameter vocal_language harus sesuai dengan bahasa lirik.
pipe.sample_rate dan pipe.latents_per_second diambil dari konfigurasi VAE (48000 Hz dan 25 fps untuk checkpoint yang dirilis).
Untuk tugas audio-ke-audio, berikan src_audio dan reference_audio sebagai tensor stereo yang telah diproses pada pipe.sample_rate.
flash dan flash_hub menggunakan dukungan sliding-window native dari FlashAttention untuk self-attention ACE-Step dan mengharapkan batch teks tanpa padding. Jika prompt batch berisi padding, gunakan flash_varlen atau flash_varlen_hub sebagai gantinya. Inferensi single-prompt dengan padding="longest" biasanya tidak berpadding.

import torch
import soundfile as sf
from diffusers import AceStepPipeline

pipe = AceStepPipeline.from_pretrained("ACE-Step/acestep-v15-xl-turbo-diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

audio = pipe(
    prompt="A beautiful piano piece with soft melodies and gentle rhythm",
    lyrics="[verse]\nSoft notes in the morning light\nDancing through the air so bright\n[chorus]\nMusic fills the air tonight\nEvery note feels just right",
    audio_duration=30.0,
).audios

sf.write("output.wav", audio[0].T.cpu().float().numpy(), pipe.sample_rate)

AceStepPipeline

kelas diffusers.AceStepPipeline

< source >

( vae: AutoencoderOoblecktext_encoder: PreTrainedModeltokenizer: TokenizersBackendtransformer: AceStepTransformer1DModelcondition_encoder: AceStepConditionEncoderscheduler: FlowMatchEulerDiscreteScheduleraudio_tokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenizer] = Noneaudio_token_detokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenDetokenizer] = None )

Parameter

vae (AutoencoderOobleck) — Model Variational Auto-Encoder (VAE) untuk mengodekan dan mendekodekan gelombang audio ke dan dari representasi laten.
text_encoder (AutoModel) — Model text encoder (misalnya, Qwen3-Embedding-0.6B) untuk meng-encode prompt teks dan lirik.
tokenizer (AutoTokenizer) — Tokenizer untuk text encoder.
transformer (AceStepTransformer1DModel) — Model Diffusion Transformer (DiT) untuk denoising latens audio.
condition_encoder (AceStepConditionEncoder) — Encoder kondisi yang menggabungkan embedding teks, lirik, dan timbre untuk cross-attention.
scheduler (FlowMatchEulerDiscreteScheduler) — Scheduler Euler untuk flow-matching. ACE-Step memberikan timestep DiT dalam [0, 1], sehingga scheduler dikonfigurasi dengan num_train_timesteps=1 dan shift=1.0 — pipeline menghitung jadwal sigma yang digeser / turbo-nya sendiri dan meneruskannya melalui set_timesteps(sigmas=...).

Pipeline untuk generasi teks-ke-musik menggunakan ACE-Step 1.5.

Model ini mewarisi dari DiffusionPipeline. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline (mengunduh, menyimpan, menjalankan pada perangkat tertentu, dll.).

Pipeline ini menggunakan flow matching dengan jadwal timestep khusus untuk proses difusi. Varian model turbo menggunakan 8 langkah inferensi secara default.

Jenis tugas yang didukung:

"text2music": Menghasilkan musik dari prompt teks dan lirik.
"cover": Menghasilkan audio dari audio sumber / kode semantik dengan transfer timbre dari audio referensi.
"repaint": Regenerasi bagian dari audio yang sudah ada sambil mempertahankan sisanya.
"extract": Ekstrak trek tertentu (misalnya, vokal, drum) dari audio.
"lego": Menghasilkan trek tertentu berdasarkan konteks audio.
"complete": Melengkapi audio input dengan trek tambahan.

call

< source >

( prompt: typing.Union[str, typing.List[str]] = Nonelyrics: typing.Union[str, typing.List[str]] = ''audio_duration: float = 60.0vocal_language: typing.Union[str, typing.List[str]] = 'en'num_inference_steps: int = 8guidance_scale: float = 7.0shift: float = 3.0generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pt'return_dict: bool = Truecallback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = Nonecallback_steps: typing.Optional[int] = 1callback_on_step_end: typing.Optional[typing.Callable[..., dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ('latents',)instruction: typing.Optional[str] = Nonemax_text_length: int = 256max_lyric_length: int = 2048bpm: typing.Optional[int] = Nonekeyscale: typing.Optional[str] = Nonetimesignature: typing.Optional[str] = Nonetask_type: str = 'text2music'track_name: typing.Optional[str] = Nonecomplete_track_classes: typing.Optional[typing.List[str]] = Nonesrc_audio: typing.Optional[torch.Tensor] = Nonereference_audio: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Union[str, typing.List[str], NoneType] = Nonerepainting_start: typing.Optional[float] = Nonerepainting_end: typing.Optional[float] = Noneaudio_cover_strength: float = 1.0cfg_interval_start: float = 0.0cfg_interval_end: float = 1.0timesteps: typing.Optional[typing.List[float]] = Noneattention_kwargs: typing.Optional[dict] = None ) → AudioPipelineOutput or tuple

Parameter

prompt (str atau List[str], opsional) — Prompt atau prompt-prompt untuk memandu generasi musik. Mendeskripsikan gaya, genre, instrumen, dll.
lyrics (str atau List[str], opsional, default "") — Teks lirik untuk musik. Mendukung lirik terstruktur dengan tag seperti [verse], [chorus], dll.
audio_duration (float, opsional, default 60.0) — Durasi audio yang dihasilkan dalam detik.
vocal_language (str atau List[str], opsional, default "en") — Kode bahasa untuk lirik (misalnya, "en", "zh", "ja").
num_inference_steps (int, opsional, default 8) — Jumlah langkah denoising. Model turbo dirancang untuk 8 langkah.
guidance_scale (float, opsional, default 7.0) — Skala panduan untuk classifier-free guidance. Nilai 1.0 menonaktifkan CFG.
shift (float, opsional, default 3.0) — Parameter shift untuk jadwal timestep (1.0, 2.0, atau 3.0).
generator (torch.Generator atau List[torch.Generator], opsional) — Generator untuk membuat proses generasi menjadi deterministik.
latents (torch.Tensor, opsional) — Latens noise yang telah dibuat sebelumnya dengan bentuk (batch_size, latent_length, acoustic_dim).
output_type (str, opsional, default "pt") — Format output. "pt" untuk tensor PyTorch, "np" untuk array NumPy, "latent" untuk latents mentah.
return_dict (bool, opsional, default True) — Apakah akan mengembalikan AudioPipelineOutput atau tuple biasa.
callback (Callable, opsional) — Fungsi yang dipanggil setiap callback_steps langkah dengan (step, timestep, latents).
callback_steps (int, opsional, default 1) — Frekuensi fungsi callback.
callback_on_step_end (Callable, opsional) — Fungsi yang dipanggil di akhir setiap langkah denoising selama inferensi. Fungsi ini dipanggil dengan argumen berikut: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs akan berisi daftar semua tensor sesuai yang ditentukan oleh callback_on_step_end_tensor_inputs.
callback_on_step_end_tensor_inputs (List, opsional) — Daftar input tensor untuk fungsi callback_on_step_end. Tensor yang ditentukan dalam daftar akan diteruskan sebagai argumen callback_kwargs. Anda hanya dapat menyertakan variabel yang tercantum dalam atribut ._callback_tensor_inputs dari kelas pipeline Anda.
instruction (str, opsional) — Teks instruksi kustom untuk tugas generasi. Jika tidak disediakan, teks ini akan dibuat secara otomatis berdasarkan task_type.
max_text_length (int, opsional, default 256) — Panjang token maksimum untuk pengkodean prompt teks.
max_lyric_length (int, opsional, default 2048) — Panjang token maksimum untuk encoding lirik.
bpm (int, opsional) — BPM (beats per minute) untuk metadata musik. Jika None, model akan memperkirakan nilainya.
keyscale (str, opsional) — Nada musik (misalnya, "C major", "A minor"). Jika None, model akan memperkirakan nada tersebut.
timesignature (str, opsional) — Tanda waktu (misalnya, "4" untuk 4/4, "3" untuk 3/4). Jika None, model akan memperkirakan tanda waktunya.
task_type (str, opsional, default "text2music") — Jenis tugas generasi. Salah satu dari "text2music", "cover", "repaint", "extract", "lego", "complete".
track_name (str, opsional) — Nama track untuk tugas "extract" atau "lego" (misalnya, "vocals", "drums").
complete_track_classes (List[str], opsional) — Kelas track untuk tugas "complete".
src_audio (torch.Tensor, opsional) — Tensor audio sumber dengan bentuk [channels, samples] pada 48kHz untuk tugas audio-ke-audio (repaint, lego, cover, extract, complete). Audio ini dienkod melalui VAE untuk menghasilkan latens sumber.
reference_audio (torch.Tensor, opsional) — Tensor audio referensi dengan bentuk [channels, samples] pada 48kHz untuk kondisioning timbre. Digunakan untuk mengekstrak fitur timbre untuk transfer gaya.
audio_codes (str atau List[str], opsional) — String kode semantik audio (mis. "<|audio_code_123|><|audio_code_456|>..."). Jika diberikan, tugas secara otomatis beralih ke mode "cover" dan modul tokenizer / detokenizer audio ACE-Step yang terdaftar mendekodekan kode 5 Hz menjadi kondisioning akustik 25 Hz.
repainting_start (float, opsional) — Waktu mulai dalam detik untuk area repaint (untuk tugas "repaint" dan "lego").
repainting_end (float, opsional) — Waktu akhir dalam detik untuk area repaint. Gunakan -1 atau None untuk sampai akhir.
audio_cover_strength (float, opsional, default 1.0) — Kekuatan pencampuran audio cover (0.0 hingga 1.0). Ketika < 1.0, mencampurkan output yang dikondisikan oleh cover dan output yang hanya dikondisikan oleh teks. Nilai yang lebih rendah menghasilkan efek transfer gaya yang lebih kuat.
cfg_interval_start (float, opsional, default 0.0) — Rasio awal (0.0-1.0) dari rentang timestep tempat CFG diterapkan.
cfg_interval_end (float, opsional, default 1.0) — Rasio akhir (0.0-1.0) dari rentang timestep tempat CFG diterapkan.
timesteps (List[float], opsional) — Jadwal timestep kustom. Jika diberikan, menimpa num_inference_steps dan shift.
attention_kwargs (dict, opsional) — Kamus kwargs yang diteruskan ke AttentionProcessor. Digunakan untuk meneruskan skala LoRA melalui {"scale": float}.

Mengembalikan

AudioPipelineOutput atau tuple

Jika return_dict adalah True, sebuah AudioPipelineOutput dikembalikan, selain itu sebuah tuple dengan audio yang dihasilkan.

Fungsi panggilan untuk pipeline generasi musik.

Contoh:

>>> import torch
>>> import soundfile as sf
>>> from diffusers import AceStepPipeline

>>> pipe = AceStepPipeline.from_pretrained(
...     "ACE-Step/acestep-v15-xl-turbo-diffusers", torch_dtype=torch.bfloat16
... )
>>> pipe = pipe.to("cuda")

>>> # Text-to-music generation with metadata
>>> audio = pipe(
...     prompt="A beautiful piano piece with soft melodies",
...     lyrics="[verse]\nSoft notes in the morning light\n[chorus]\nMusic fills the air tonight",
...     audio_duration=30.0,
...     num_inference_steps=8,
...     bpm=120,
...     keyscale="C major",
...     timesignature="4",
... ).audios

>>> # Save the generated audio
>>> sf.write("output.wav", audio[0, 0].cpu().numpy(), 48000)

>>> # Repaint task: regenerate a section of existing stereo 48kHz audio
>>> src_audio, sr = sf.read("input.wav")
>>> src_audio = torch.from_numpy(src_audio).float().T
>>> audio = pipe(
...     prompt="Epic rock guitar solo",
...     lyrics="",
...     task_type="repaint",
...     src_audio=src_audio,
...     repainting_start=10.0,
...     repainting_end=20.0,
... ).audios

>>> # Cover task with reference audio for timbre transfer
>>> ref_audio, sr = sf.read("reference.wav")
>>> ref_audio = torch.from_numpy(ref_audio).float().T
>>> audio = pipe(
...     prompt="Pop song with bright vocals",
...     lyrics="[verse]\nHello world",
...     task_type="cover",
...     reference_audio=ref_audio,
...     audio_cover_strength=0.8,
... ).audios

check_inputs

< source >

( prompt: typing.Union[str, typing.List[str]]lyrics: typing.Union[str, typing.List[str]]task_type: strnum_inference_steps: intguidance_scale: floatshift: floataudio_cover_strength: floatcfg_interval_start: floatcfg_interval_end: floatrepainting_start: typing.Optional[float]repainting_end: typing.Optional[float] )

Validasi argumen yang berhadapan dengan pengguna sebelum kami mulai mengalokasikan tensor noise.

encode_prompt

< source >

( prompt: typing.Union[str, typing.List[str]]lyrics: typing.Union[str, typing.List[str]]device: devicevocal_language: typing.Union[str, typing.List[str]] = 'en'audio_duration: float = 60.0instruction: typing.Optional[str] = Nonebpm: typing.Optional[int] = Nonekeyscale: typing.Optional[str] = Nonetimesignature: typing.Optional[str] = Nonemax_text_length: int = 256max_lyric_length: int = 2048 )

Parameter

prompt (str atau List[str]) — Caption teks yang menggambarkan musik.
lyrics (str atau List[str]) — Teks lirik.
device (torch.device) — Perangkat untuk tensor.
vocal_language (str atau List[str], opsional, default "en") — Kode bahasa untuk lirik.
audio_duration (float, opsional, default 60.0) — Durasi audio dalam detik.
instruction (str, opsional) — Teks instruksi untuk generasi.
bpm (int, opsional) — BPM (beats per minute) untuk metadata.
keyscale (str, opsional) — Nada musik (misalnya, "C major").
timesignature (str, opsional) — Tanda waktu (misalnya, "4" untuk 4/4).
max_text_length (int, opsional, default 256) — Panjang token maksimum untuk prompt teks.
max_lyric_length (int, opsional, default 2048) — Panjang token maksimum untuk lirik.

Enkode prompt teks dan lirik menjadi embedding.

Prompt teks dikodekan melalui model pengkode teks penuh untuk menghasilkan state tersembunyi kontekstual. Lirik hanya dilewatkan melalui lapisan embedding pengkode teks (pencarian token), karena pengkode lirik di dalam pengkode kondisi menangani pengkodean kontekstual.

prepare_latents

< source >

( batch_size: intaudio_duration: floatdtype: dtypedevice: devicegenerator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = None )

Parameter

batch_size (int) — Jumlah sampel yang akan dihasilkan.
audio_duration (float) — Durasi audio dalam detik.
dtype (torch.dtype) — Tipe data untuk latents.
device (torch.device) — Perangkat untuk latents.
generator (torch.Generator atau List[torch.Generator], opsional) — Generator angka acak.
latents (torch.Tensor, opsional) — Latens yang telah dibuat sebelumnya.

Siapkan latens noise awal untuk proses flow matching.

prepare_reference_audio_latents

< source >

( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )

Parameter

reference_audio (torch.Tensor) — Tensor audio referensi dengan bentuk [channels, samples] pada self.sample_rate.
batch_size (int) — Ukuran batch.
device (torch.device) — Perangkat target.
dtype (torch.dtype) — dtype target.

Proses audio referensi menjadi latens akustik untuk encoder timbre.

Audio referensi diulang/dipotong menjadi 30 detik (3 segmen masing-masing 10 detik dari bagian depan, tengah, dan belakang), dikodekan melalui VAE, dan kemudian ditransposisikan untuk encoder timbre.

prepare_src_latents

< source >

( device: devicedtype: dtypebatch_size: int = 1src_audio: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Union[str, typing.List[str], NoneType] = Nonelatent_length: typing.Optional[int] = Nonetask_type: str = 'text2music' )

Parameter

src_audio (torch.Tensor, opsional) — Tensor audio sumber dengan bentuk [channels, samples] pada self.sample_rate.
audio_codes (str atau List[str], opsional) — String kode semantik audio.
latent_length (int, opsional) — Panjang latent target ketika tidak ada audio sumber atau kode audio yang diberikan.
device (torch.device) — Perangkat target.
dtype (torch.dtype) — dtype target.
batch_size (int) — Ukuran batch.
task_type (str) — Jenis tugas saat ini.

Siapkan latens sumber untuk tugas teks-ke-musik dan audio-ke-audio.

Update on GitHub

Diffusers

ACE-Step 1.5

Varian

Tips

AceStepPipeline

kelas diffusers.AceStepPipeline

__call__

check_inputs

encode_prompt

prepare_latents

prepare_reference_audio_latents

prepare_src_latents

call