Hugging Face's logo

Diffusers documentation

ACE-Step 1.5

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

ACE-Step 1.5

ACE-Step 1.5, ACE-Step Ekibi (ACE Studio ve StepFun) tarafından ACE-Step 1.5: Açık Kaynak Müzik Üretiminde Sınırları Zorlama başlıklı çalışmada tanıtılmıştır. Metin istemlerinden sözleri olan, ticari kalitede stereo müzik üreten açık kaynak bir müzik temel modelidir.

ACE-Step 1.5, metin istemleri ve isteğe bağlı sözlerden 48 kHz'de değişken uzunlukta stereo ses (10 saniyeden 10 dakikaya kadar) üretir. Tam sistem, bir Dil Modeli planlayıcıyı bir Diffusion Transformer (DiT) sentezleyiciyle eşleştirir; bu pipeline, o yığınların DiT yarısını sarmalar ve üç bileşenden oluşur: dalga formlarını 25 Hz stereo latentlere sıkıştıran bir AutoencoderOobleck VAE, istem ve söz koşullandırması için Qwen3 tabanlı bir metin kodlayıcı ve VAE latent uzayında akış eşleştirmesi (flow matching) kullanarak çalışan bir AceStepTransformer1DModel DiT.

Model, şarkı sözleri için 50'den fazla dili destekler — İngilizce, Çince, Japonca, Korece, Fransızca, Almanca, İspanyolca, İtalyanca, Portekizce ve Rusça dahil — ve tüketici GPU'larında çalışır (offload edildiğinde 4 GB VRAM'in altında).

Bu pipeline, ACE-Step Team tarafından katkı sağlanmıştır. Orijinal kod tabanı ace-step/ACE-Step-1.5 adresinde bulunabilir.

Varyantlar

ACE-Step 1.5, aynı transformer mimarisini paylaşan ancak yönlendirme davranışları farklı olan üç DiT checkpoint'i ile birlikte gelir; pipeline, yüklü transformer yapılandırmasından turbo checkpoint'lerini otomatik olarak algılar ve bu yönlendirme-distilled ağırlıklar için CFG yönlendirmesini yok sayar.

VaryantCFGVarsayılan adımlarVarsayılan guidance_scaleVarsayılan shiftHF deposu
turbo (guidance-distilled)kapalı8yoksayıldı3.0ACE-Step/acestep-v15-xl-turbo-diffusers
baseaçık87.03.0ACE-Step/acestep-v15-base
sftaçık87.03.0ACE-Step/acestep-v15-sft

Base ve SFT, sınıflandırıcı-ücretsiz yönlendirme (APG, vanilla CFG değil) için öğrenilen null_condition_emb değerini kullanır. Kullanıcılar, daha yüksek kalite için base/sft üzerinde num_inference_steps değerini genellikle 30–60 aralığına geçersiz kılar.

İpuçları

Bir istem oluştururken şunları göz önünde bulundurun:

  • Açıklayıcı istem girdileri en iyi sonucu verir; müzik tarzını, enstrümanları, ruh halini ve temposu betimlemek için sıfatlar kullanın.
  • İstem, genel müzikal özellikleri (ör. “elektrik gitar ve davullu neşeli bir pop şarkısı”) açıklamalıdır.
  • Şarkı sözleri, [verse], [chorus], [bridge] gibi etiketlerle yapılandırılmalıdır.

Çıkarım sırasında:

  • num_inference_steps, guidance_scale ve shift varsayılan olarak yukarıda gösterilen değerlere ayarlanır. Turbo kontrol noktaları için, rehberlik ağırlıklara damıtıldığından guidance_scale > 1.0 bir uyarıyla yok sayılır.
  • audio_duration parametresi, üretilen müziğin saniye cinsinden uzunluğunu kontrol eder.
  • vocal_language parametresi, sözlerin diliyle eşleşmelidir.
  • pipe.sample_rate ve pipe.latents_per_second, VAE yapılandırmasından alınır (yayınlanan kontrol noktaları için 48000 Hz ve 25 fps).
  • Ses-ses görevleri için src_audio ve reference_audio değerlerini, pipe.sample_rate örnekleme hızında ön işlenmiş stereo tensörler olarak iletin.
  • flash ve flash_hub, ACE-Step’in öz-dikkat (self-attention) mekanizması için FlashAttention’ın yerel kayan pencere (sliding-window) desteğini kullanır ve dolgusuz (unpadded) metin toplamları bekler. Toplu bir istemde dolgu (padding) varsa bunun yerine flash_varlen veya flash_varlen_hub kullanın. padding="longest" ile tek istemli çıkarım (inference) genellikle dolgusuzdur.
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

sınıf diffusers.AceStepPipeline

< >

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

Parametreler

  • vae (AutoencoderOobleck) — Ses dalga formlarını latent temsillere kodlamak ve bu temsillerden çözmek için kullanılan Varyasyonel Oto-Kodlayıcı (VAE) modeli.
  • text_encoder (AutoModel) — Metin istemlerini ve sözleri kodlamak için metin kodlayıcı modeli (ör. Qwen3-Embedding-0.6B).
  • tokenizer (AutoTokenizer) — Metin kodlayıcı için sınıflandırıcı.
  • transformer (AceStepTransformer1DModel) — Ses latentlerini gürültüden arındırmak için kullanılan Diffusion Transformer (DiT) modeli.
  • condition_encoder (AceStepConditionEncoder) — Çapraz dikkat için metin, söz ve timbre gömme vektörlerini birleştiren koşul kodlayıcı.
  • scheduler (FlowMatchEulerDiscreteScheduler) — Flow-matching Euler zamanlayıcısı. ACE-Step, DiT zaman adımlarını [0, 1] aralığında beslediği için zamanlayıcı num_train_timesteps=1 ve shift=1.0 ile yapılandırılır — pipeline, kaydırılmış / turbo sigma zaman çizelgesini kendi hesaplar ve set_timesteps(sigmas=...) üzerinden iletir.

ACE-Step 1.5 kullanarak metinden müziğe üretim için Pipeline.

Bu model DiffusionPipeline sınıfından devralır. Tüm pipeline'lar için uygulanan genel yöntemlerin (indirme, kaydetme, belirli bir cihazda çalıştırma vb.) belgelerini üst sınıfın dokümantasyonunda bulabilirsiniz.

Pipeline, difüzyon süreci için özel bir zaman adımı planı kullanan akış eşleştirmesini (flow matching) kullanır. Turbo model varyantı varsayılan olarak 8 çıkarım adımı kullanır.

Desteklenen görev türleri:

  • "text2music": Metin istemleri ve sözlerden müzik üretin.
  • "cover": Kaynak ses / semantik kodlardan, referans sesin ton aktarımıyla ses üretir.
  • "repaint": Mevcut sesin bir bölümünü yeniden oluştururken geri kalanını korur.
  • "extract": Ses dosyasından belirli bir parçayı (ör. vokal, davul) ayıklayın.
  • "lego": Ses bağlamına dayalı olarak belirli bir parça üretir.
  • "complete": Girdi sesini ek parçalarla tamamlayın.

__call__

< >

( 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

Parametreler

  • prompt (str veya List[str], isteğe bağlı) — Müzik üretimini yönlendirmek için kullanılan istem veya istemler. Tarzı, türü, enstrümanları vb. açıklar.
  • lyrics (str veya List[str], isteğe bağlı, varsayılan "") — Müzik için söz metni. [verse], [chorus] gibi etiketlere sahip yapılandırılmış sözleri destekler.
  • audio_duration (float, isteğe bağlı, varsayılan 60.0) — Üretilen sesin saniye cinsinden süresi.
  • vocal_language (str veya List[str], isteğe bağlı, varsayılan "en") — Şarkı sözleri için dil kodu (ör. "en", "zh", "ja").
  • num_inference_steps (int, isteğe bağlı, varsayılan 8) — Gürültü azaltma adım sayısı. Turbo modeli 8 adım için tasarlanmıştır.
  • guidance_scale (float, isteğe bağlı, varsayılan 7.0) — Sınıflandırıcı-özgürlü yönlendirme için yönlendirme ölçeği. 1.0 değeri CFG'yi devre dışı bırakır.
  • shift (float, isteğe bağlı, varsayılan 3.0) — Zaman adımı zaman çizelgesi için kaydırma parametresi (1.0, 2.0 veya 3.0).
  • generator (torch.Generator veya List[torch.Generator], isteğe bağlı) — Üretimi deterministik hale getirmek için bir üreteç.
  • latents (torch.Tensor, isteğe bağlı) — (batch_size, latent_length, acoustic_dim) biçiminde önceden oluşturulmuş gürültü latentleri.
  • output_type (str, isteğe bağlı, varsayılan "pt") — Çıktı biçimi. PyTorch tensörü için "pt", NumPy dizisi için "np", ham latentler için "latent".
  • return_dict (bool, isteğe bağlı, varsayılan True) — AudioPipelineOutput mu yoksa düz bir tuple mı döndürüleceğini belirtir.
  • callback (Callable, isteğe bağlı) — Her callback_steps adımda (step, timestep, latents) ile çağrılan bir fonksiyon.
  • callback_steps (int, isteğe bağlı, varsayılan 1) — Çağrı geri (callback) fonksiyonunun sıklığı.
  • callback_on_step_end (Callable, isteğe bağlı) — Çıkarım sırasında her gürültü azaltma adımının sonunda çağrılan bir işlev. İşlev aşağıdaki argümanlarla çağrılır: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs, callback_on_step_end_tensor_inputs tarafından belirtilen tüm tensörlerin listesini içerir.
  • callback_on_step_end_tensor_inputs (List, optional) — The list of tensor inputs for the callback_on_step_end function. The tensors specified in the list will be passed as callback_kwargs argument. You will only be able to include variables listed in the ._callback_tensor_inputs attribute of your pipeline class.
  • instruction (str, isteğe bağlı) — Üretim görevi için özel talimat metni. Sağlanmazsa, task_type temel alınarak otomatik olarak oluşturulur.
  • max_text_length (int, isteğe bağlı, varsayılan 256) — Metin istemi kodlaması için maksimum jeton uzunluğu.
  • max_lyric_length (int, isteğe bağlı, varsayılan 2048) — Şarkı sözleri kodlaması için maksimum token uzunluğu.
  • bpm (int, isteğe bağlı) — Müzik metaverisi için BPM (dakikadaki vuruş sayısı). None ise model bunu tahmin eder.
  • keyscale (str, isteğe bağlı) — Müzikal anahtar (ör. "C major", "A minor"). None ise model bunu tahmin eder.
  • timesignature (str, isteğe bağlı) — Zaman imzası (ör. 4/4 için "4", 3/4 için "3"). None ise model bunu tahmin eder.
  • task_type (str, isteğe bağlı, varsayılan "text2music") — Üretim görevi türü. "text2music", "cover", "repaint", "extract", "lego", "complete" değerlerinden biri.
  • track_name (str, isteğe bağlı) — "extract" veya "lego" görevleri için iz adı (ör. "vocals", "drums").
  • complete_track_classes (List[str], isteğe bağlı) — "complete" görevi için izleme sınıfları.
  • src_audio (torch.Tensor, isteğe bağlı) — Sesten sese görevler (repaint, lego, cover, extract, complete) için 48kHz'de [channels, samples] biçiminde kaynak ses tensörü. Ses, kaynak latentleri üretmek için VAE üzerinden kodlanır.
  • reference_audio (torch.Tensor, isteğe bağlı) — Tonlama (timbre) koşullandırma için 48kHz'de [channels, samples] biçiminde referans ses tensörü. Stil transferi için tonlama özelliklerini çıkarmak üzere kullanılır.
  • audio_codes (str veya List[str], isteğe bağlı) — Ses semantik kod dizgeleri (ör. "<|audio_code_123|><|audio_code_456|>..."). Sağlandığında, görev otomatik olarak "cover" moduna geçilir ve kayıtlı ACE-Step ses tokenizer / detokenizer modülleri 5 Hz kodları 25 Hz akustik koşullandırmaya çözer.
  • repainting_start (float, isteğe bağlı) — Yeniden boyama bölgesi için saniye cinsinden başlangıç zamanı ("repaint" ve "lego" görevleri için).
  • repainting_end (float, isteğe bağlı) — Boya bölgesi için saniye cinsinden bitiş zamanı. Bitişe kadar için -1 veya None kullanın.
  • audio_cover_strength (float, isteğe bağlı, varsayılan 1.0) — Ses kapağı karıştırma gücü (0.0 ile 1.0 arasında). < 1.0 olduğunda, kapak koşullu ve yalnızca metin koşullu çıktıları karıştırır. Daha düşük değerler daha fazla stil aktarımı etkisi üretir.
  • cfg_interval_start (float, isteğe bağlı, varsayılan 0.0) — CFG'nin uygulandığı timestep aralığının başlangıç oranı (0.0-1.0).
  • cfg_interval_end (float, isteğe bağlı, varsayılan 1.0) — CFG'nin uygulandığı timestep aralığının son oranı (0.0-1.0).
  • timesteps (List[float], isteğe bağlı) — Özel timestep zamanlaması. Verildiğinde num_inference_steps ve shift değerlerini geçersiz kılar.
  • attention_kwargs (dict, isteğe bağlı) — AttentionProcessor'a iletilen bir kwargs sözlüğü. LoRA ölçeğini {"scale": float} üzerinden geçirmek için kullanılır.

Dönüş değeri

AudioPipelineOutput veya tuple

return_dict True ise bir AudioPipelineOutput döndürülür, aksi halde üretilen ses içeren bir tuple döndürülür.

Müzik üretimi için pipeline'in call fonksiyonu.

Örnekler:

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

< >

( 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] )

Gürültü tensörlerini tahsis etmeye başlamadan önce kullanıcıya yönelik argümanları doğrulayın.

encode_prompt

< >

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

Parametreler

  • prompt (str veya List[str]) — Müziği tanımlayan metin açıklama(lar)ı.
  • lyrics (str veya List[str]) — Şarkı sözleri.
  • device (torch.device) — Tensörler için cihaz.
  • vocal_language (str veya List[str], isteğe bağlı, varsayılan "en") — Şarkı sözleri için dil kodu(ları).
  • audio_duration (float, isteğe bağlı, varsayılan 60.0) — Sesin saniye cinsinden süresi.
  • instruction (str, isteğe bağlı) — Üretim için talimat metni.
  • bpm (int, isteğe bağlı) — Üst veriler için BPM (dakikadaki vuruş sayısı).
  • keyscale (str, isteğe bağlı) — Müzikal anahtar (ör. "C major").
  • timesignature (str, isteğe bağlı) — Zaman imzası (ör. 4/4 için "4").
  • max_text_length (int, isteğe bağlı, varsayılan 256) — Metin istemleri için maksimum jeton uzunluğu.
  • max_lyric_length (int, isteğe bağlı, varsayılan 2048) — Şarkı sözleri için maksimum token uzunluğu.

Metin istemlerini ve sözleri gömme (embedding) olarak kodlayın.

Metin istemleri, bağlamsal gizli durumları üretmek için tam metin kodlayıcı modeli üzerinden kodlanır. Şarkı sözleri, bağlamsal kodlamayı koşul kodlayıcısındaki söz kodlayıcısının üstlenmesi nedeniyle yalnızca metin kodlayıcısının gömme katmanından (token arama) geçirilir.

prepare_latents

< >

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

Parametreler

  • batch_size (int) — Üretilecek örnek sayısı.
  • audio_duration (float) — Sesin saniye cinsinden süresi.
  • dtype (torch.dtype) — Latentler için veri türü.
  • device (torch.device) — Latentler için cihaz.
  • generator (torch.Generator veya List[torch.Generator], isteğe bağlı) — Rastgele sayı üreteçleri.
  • latents (torch.Tensor, isteğe bağlı) — Önceden oluşturulmuş latensler.

Akış eşleştirme süreci için başlangıç gürültü latentlerini hazırlar.

prepare_reference_audio_latents

< >

( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )

Parametreler

  • reference_audio (torch.Tensor) — self.sample_rate örnekleme hızında, [channels, samples] biçiminde referans ses tensörü.
  • batch_size (int) — Toplu işlem boyutu.
  • device (torch.device) — Hedef cihaz.
  • dtype (torch.dtype) — Hedef dtype.

Timbre kodlayıcısı için referans sesleri akustik latentlere dönüştürün.

Referans ses, 30 saniyeye (ön, orta ve arka kısımlardan 10'ar saniyelik 3 segment) tekrarlanır/kırpılır, VAE üzerinden kodlanır ve ardından timbre kodlayıcısı için transpoze edilir.

prepare_src_latents

< >

( 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' )

Parametreler

  • src_audio (torch.Tensor, isteğe bağlı) — self.sample_rate örnekleme hızında, [channels, samples] biçiminde kaynak ses tensörü.
  • audio_codes (str veya List[str], isteğe bağlı) — Ses semantik kod dizgileri.
  • latent_length (int, isteğe bağlı) — Kaynak ses veya ses kodları verilmediğinde hedef latent uzunluğu.
  • device (torch.device) — Hedef cihaz.
  • dtype (torch.dtype) — Hedef dtype.
  • batch_size (int) — Toplu işlem boyutu.
  • task_type (str) — Güncel görev türü.

Metinden müziğe ve sesden sese görevleri için kaynak latentleri hazırlar.

Update on GitHub

←AutoPipeline AudioLDM 2→