Hugging Face's logo

Diffusers documentation

Stable Audio 3

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Stable Audio 3

Stable Audio 3 (SA3), Stability AI tarafından geliştirilen, 44,1 kHz'de yüksek kaliteli stereo ses üreten bir metinden sese modelidir. İki sinyale koşullanan bir rectified-flow DiT kullanır:

  • Metin — dondurulmuş bir T5Gemma kodlayıcı tarafından kodlanır ve çapraz dikkat (cross-attention) yoluyla enjekte edilir.
  • Süre — StableAudio3DurationEmbedder tarafından gömülen ve uyumlu katman normalizasyonu için küresel koşullandırma vektörü olarak kullanılan bir ondalık sayı (saniye).

Ses, AutoencoderSAME otomatik kodlayıcısı tarafından SAME (Semantically-Aligned Music Encoder) ile çözümlenir.

Her iki kontrol noktası da log-SNR-uniform sigma zamanlamasıyla FlowMatchEulerDiscreteScheduler kullanır; yalnızca stochastic_sampling ve varsayılan adım sayısı açısından farklılık gösterirler:

Kontrol Noktasıdiffusion_objectivestochastic_samplingnum_inference_steps
stable-audio-3-medium-baserectified_flowFalse (deterministik Euler)100 (damıtılmamış)
stable-audio-3-medium (damıtılmış)rf_denoiserTrue (ping-pong yeniden gürültü)8 (8 adımda damıtıldı)

Doğru zamanlayıcı yapılandırması, dönüştürülen her kontrol noktasına gömülüdür; bu nedenle num_inference_steps parametresini ayarlamazsanız varsayılan olarak doğru değeri alır. Yalnızca bu değeri geçersiz kılmak istediğinizde parametreyi iletin.

Orijinal kod tabanı: Stability-AI/stable-audio-3.

Orijinal denetim noktalarını dönüştürme

Stability AI kontrol noktaları diffusers biçiminde yayımlanmadığından, bunları yerel olarak dönüştürün. Betik, kontrol noktasının model_config.json dosyasını indirir ve zamanlayıcıyı diffusion_objective alanından seçer:

python scripts/convert_stable_audio_3_to_diffusers.py \
  --checkpoint_path stabilityai/stable-audio-3-medium-base \
  --text_encoder_repo google/t5gemma-b-b-ul2 \
  --output_dir /tmp/sa3-diffusers-euler \
  --dtype float32

stable-audio-3-medium-base bir gated depodur. Dönüştürmeden önce, erişimi olan bir hesapla hf auth login komutunu çalıştırın; aksi takdirde indirme 401 hatasıyla başarısız olur.

Kullanım örneği

Dönüştürülen kontrol noktasını yerel çıktı dizininden yükleyin (soundfile paketini pip install soundfile ile yükleyin):

import torch
import soundfile as sf
from diffusers import StableAudio3Pipeline

pipe = StableAudio3Pipeline.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

generator = torch.Generator("cuda").manual_seed(0)
audio = pipe(
    "A gentle piano melody with soft strings in a concert hall",
    duration=10.0,  # seconds; latent length is computed automatically
    generator=generator,
).audios

sf.write("sa3_output.wav", audio[0].T.cpu().float().numpy(), samplerate=44100)

Pipeline ayrıca AutoPipelineForText2Audio ile de kayıtlıdır ve bu, checkpoint'i otomatik olarak StableAudio3Pipeline olarak çözer:

from diffusers import AutoPipelineForText2Audio

pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)

Örnekler, stabilityai/stable-audio-3-medium ve stable-audio-3-medium-base henüz diffusers formatında yayımlanmadığı için (repo kimliğiyle yükleme 404 döndürüyor) yerel bir yol kullanır. Yayımlandıktan sonra, repo kimliği yerel yolun yerine geçer.

İpuçları

  • CPU veya MPS (Apple Silicon) üzerinde torch.float32 kullanın — MPS üzerinde torch.float16 gürültü üretir.
  • Distilled model (stable-audio-3-medium) adversarially distilled — guidance, ağırlıklara gömülüdür. guidance_scale=1.0 değerini (varsayılan) bırakın ve bu checkpoint için negative_prompt geçmeyin; her ikisi de yalnızca distilled olmayan stable-audio-3-medium-base checkpoint için işe yarar.
  • silence_padding_duration (varsayılan 0.0), latent dizinin sonuna sessiz bir pay bırakır. Model bu dolguyu maskelemek üzere eğitilmediyse 0.0 olarak bırakın; aksi halde ek kareler çıktı enerjisini tüketir ve sonuç kısılır.
  • Her istem başına birden fazla klip oluşturmak için num_waveforms_per_prompt > 1 değerini ayarlayın.

StableAudio3Pipeline

sınıf diffusers.StableAudio3Pipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Parametreler

  • vae ([AutoencoderSAME]) — Ses latentlerini kodlamak ve çözmek için kullanılan SAME otoenkoderi.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Donmuş T5Gemma metin kodlayıcısı (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Metin kodlayıcı için tokenizer.
  • duration_embedder ([StableAudio3DurationEmbedder]) — duration değerini saniye cinsinden, her DiT bloğundaki AdaLN için küresel bir koşullandırma vektörüne eşler.
  • transformer ([StableAudio3DiTModel]) — Düzeltme akışı hız tahmini DiT.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — İteratif gürültü azaltma döngüsü için zamanlayıcı. Üretim (damıtılmış) SA3 Medium kontrol noktası tam olarak 8 ping-pong adımı için stochastic_sampling=True kullanır; damıtılmamış temel kontrol noktası ise ~100 deterministik Euler adımı için stochastic_sampling=False kullanır.

Stable Audio 3 kullanılarak metinden ses üretimi için Pipeline.

SA3, ping-pong örneklemeye sahip damıtılmış rectified-flow DiT kullanır. Damıtılmış checkpoint için classifier-free guidance (guidance_scale / negative_prompt) gereksizdir (guidance_scale=1.0, varsayılan değer bırakılmalıdır) ancak damıtılmamış stable-audio-3-medium-base checkpoint için anlamlıdır.

Bu model, [DiffusionPipeline] sınıfından devralır. Tüm pipeline'lar için uygulanan genel yöntemler için üst sınıf belgelendirmesini kontrol edin.

__call__

< >

( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0guidance_scale: float = 1.0negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_encoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' ) → [~pipelines.AudioPipelineOutput] or tuple

Parametreler

  • prompt (str veya list[str], isteğe bağlı) — Metin istemcileri. Tokenizasyonu ve kodlamayı atlamak için bunun yerine prompt_embeds geçirin.
  • duration (float, varsayılan 10.0) — İstenen çıktı süresi, saniye cinsinden.
  • num_inference_steps (int, isteğe bağlı) — Gürültü azaltma adım sayısı. None (varsayılan) olduğunda, adım sayısı zamanlayıcının stochastic_sampling yapılandırmasından seçilir: True ise 8 (damıtılmış ping-pong tarzı kontrol noktası) ve False ise 100 (damıtılmamış temel kontrol noktası). Değiştirmek için açık bir değer geçirin.
  • logsnr_min (float, varsayılan -6.2) — Gürültü zamanlaması için minimum log-SNR değeri — zamanlamanın yüksek gürültülü başlangıcına eşlenir.
  • logsnr_max (float, varsayılan 2.0) — Gürültü zamanlaması için maksimum log-SNR değeri — zamanlamanın düşük gürültülü ucuna eşlenir.
  • silence_padding_duration (float, varsayılan 0.0) — Hedef içeriğin ötesinde üretilen ek saniye cinsinden latent bağlam; modele sınırda bir pay bırakır; çıktı duration değerine geri kırpılır. Varsayılan 0.0 (devre dışı). Yalnızca model bu dolguyu maskelemek üzere eğitilmiş/distille edilmişse artırın — aksi halde ek kareler çıktı enerjisini tüketir.
  • guidance_scale (float, varsayılan 1.0) — Sınıflandırıcı-ücretsiz yönlendirme ölçeği. 1.0 yönlendirmeyi devre dışı bırakır (varsayılan değer ve damıtılmış SA3 Medium checkpoint için tek mantıklı değer, çünkü CFG'si ağırlıklara gömülüdür). > 1.0 değerleri, damıtılmamış stable-audio-3-medium-base checkpoint için anlamlıdır; daha yüksek değerler, çeşitlilikten ödün vererek istemi daha yakından takip eder.
  • negative_prompt (str veya list[str], isteğe bağlı) — guidance_scale > 1.0 olduğunda uzaklaşılmak istenen unsurları tanımlayan istem(ler). guidance_scale > 1.0 ve ne bu parametre ne de negative_prompt_embeds verildiğinde varsayılan olarak boş bir dize (koşulsuz) kullanılır. guidance_scale <= 1.0 olduğunda yok sayılır.
  • num_waveforms_per_prompt (int, varsayılan 1) — Her istem için oluşturulacak dalga formu sayısı.
  • generator (torch.Generator veya list[torch.Generator], isteğe bağlı) — Ping-pong döngüsünde deterministik üretim ve yeniden gürültüleme için.
  • latents (torch.Tensor, opsiyonel) — Önceden oluşturulmuş başlangıç latensleri. None ise yeni bir Gauss tensörü örneklenir.
  • prompt_embeds (torch.Tensor, opsiyonel) — Önceden hesaplanmış metin gömlemeleri (batch, seq_len, 768).
  • encoder_attention_mask (torch.LongTensor, opsiyonel) — Önceden hesaplanmış gömme (embedding) için mantıksal maske.
  • negative_prompt_embeds (torch.Tensor, isteğe bağlı) — negative_prompt yerine kullanılacak şekilde önceden hesaplanmış negatif metin gömme değerleri.
  • negative_encoder_attention_mask (torch.LongTensor, isteğe bağlı) — Önceden hesaplanmış negatif gömme (embedding) için mantıksal maske.
  • return_dict (bool, varsayılan True) — Bir AudioPipelineOutput veya düz bir tuple döndürür.
  • callback_on_step_end (Callable, isteğe bağlı) — Her gürültü azaltma adımının sonunda (self, step_idx, timestep, callback_kwargs) ile çağrılır; burada callback_kwargs, callback_on_step_end_tensor_inputs içinde listelenen tensörleri içerir. Döngünün geri kalanında kullanılacak (isteğe bağlı olarak değiştirilmiş) tensörleri içeren bir dict döndürmelidir.
  • callback_on_step_end_tensor_inputs (list[str], varsayılan [“latents”]) — callback_on_step_end'e iletilen tensörler. self._callback_tensor_inputs'ün bir alt kümesi olmalıdır.
  • output_type (str, varsayılan "pt") — "pt" bir PyTorch tensörü için, "np" bir NumPy dizisi için veya "latent" çözümlemeyi atlayıp ham latentleri döndürmek için.

Dönüş değeri

[~pipelines.AudioPipelineOutput] veya tuple

.audios, (batch * num_waveforms_per_prompt, audio_channels, samples) biçiminde bir tensör/dizidir.

Bir metin komutundan ses üretin.

Örnekler:

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

>>> pipe = StableAudio3Pipeline.from_pretrained("stabilityai/stable-audio-3-medium", torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)

encode_duration

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Parametreler

  • duration — Saniye cinsinden süre, batch'teki her örneğe uygulanır.
  • device — Hedef cihaz.
  • num_waveforms_per_prompt — Karo çarpanı.
  • batch_size — İstek sayısı.

Süre değerini küresel koşullandırma vektörüne gömün.

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )

Parametreler

  • prompt — Metin istemi veya istemler listesi. prompt_embeds sağlandığında yok sayılır.
  • device — Hedef cihaz.
  • num_waveforms_per_prompt — Her prompt için üretilecek çıktı dalga formu sayısı; koşullama tensörleri buna göre çoğaltılır.
  • prompt_embeds — Ön hesaplanmış metin gömme değerleri (batch, seq_len, hidden_size).
  • encoder_attention_mask — önceden hesaplanmış gömceler için Boole maskesi (batch, seq_len); 1 = gerçek token, 0 = dolgu.

Metin istemlerini çapraz dikkat koşullama tensörlerine kodlayın.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Çapraz dikkat bağlamını, süre gömme değerini ek bir jeton olarak ekleyerek oluşturun.

SA3, seconds_total koşullandırıcısını hem küresel (AdaLN) girdiye hem de ikisine de olan çapraz dikkat bağlamına (cross_attention_cond_ids = ["prompt", "seconds_total"]) yönlendirir. Süre gömme (embedding) metin jetonlarının ardından birleştirilir ve dikkat maskesi bir geçerli girişle genişletilir.

StableAudio3InpaintPipeline

sınıf diffusers.StableAudio3InpaintPipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Parametreler

  • vae ([AutoencoderSAME]) — Ses latentlerini kodlamak ve çözmek için kullanılan SAME otoenkoderi.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Donmuş T5Gemma metin kodlayıcısı (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Metin kodlayıcı için tokenizer.
  • duration_embedder ([StableAudio3DurationEmbedder]) — duration değerini saniye cinsinden, her DiT bloğundaki AdaLN için küresel bir koşullandırma vektörüne eşler.
  • transformer ([StableAudio3DiTModel]) — Düzeltme akışı hız tahmini DiT.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — İteratif gürültü azaltma döngüsü için zamanlayıcı. Üretim (damıtılmış) SA3 Medium kontrol noktası tam olarak 8 ping-pong adımı için stochastic_sampling=True kullanır; damıtılmamış temel kontrol noktası ise ~100 deterministik Euler adımı için stochastic_sampling=False kullanır.

Stable Audio 3 için ses inpainting hattı.

Metin-ses mantığını [StableAudio3Pipeline] ile paylaşır (# Copied from ile senkronize tutulur). audio ve mask sağlandığında, referans ses dondurulmuş SAME kodlayıcı ile kodlanır ve masked_latent ∥ mask, transformer'ın local_add_cond yolu (to_local_embed) üzerinden her DiT bloğuna yerel-eklemeli koşullama olarak enjekte edilir.

Çağrı imzası uzantısı (bkz. __call__): audio (torch.Tensor, şekli (batch, channels, samples)): vae.config.sampling_rate Hz'de referans ses dalgası. mask (torch.Tensor, şekli (batch, 1, latent_length)): Latent uzayda çerçeve başına ikili maske. 1 = orijinal sesi koru; 0 = doldurulacak bölge.

__call__

< >

( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Nonemask: typing.Optional[torch.Tensor] = Nonemask_start_seconds: typing.Union[float, typing.List[float], NoneType] = Nonemask_end_seconds: typing.Union[float, typing.List[float], NoneType] = Nonenum_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )

Parametreler

  • prompt (str veya list[str], isteğe bağlı) — Metin istemleri.
  • duration (float, varsayılan 10.0) — Saniye cinsinden çıktı süresi. Referans sesle eşleşmelidir.
  • audio (torch.Tensor, optional) — vae.config.sampling_rate Hz'de (batch, channels, samples) boyutlu referans dalga formu. Inpainting için gereklidir.
  • mask (torch.Tensor, optional) — 0 = inpaint bölgesi, 1 = koru olacak şekilde kare başına latent uzay maskesi (batch, 1, L). mask veya mask_start_seconds / mask_end_seconds parametrelerinden biri sağlanmalıdır.
  • mask_start_seconds (float veya list[float], isteğe bağlı) — İnpaint bölgesinin saniye cinsinden başlangıç zaman(lar)ı.
  • mask_end_seconds (float veya list[float], isteğe bağlı) — Inpaint bölgesinin bitiş zaman(lar)ı (mask_start_seconds ile eşleşmelidir).
  • num_inference_steps (int, isteğe bağlı) — Gürültü azaltma adım sayısı. None (varsayılan) olduğunda, adım sayısı zamanlayıcının stochastic_sampling yapılandırmasından seçilir ve [StableAudio3Pipeline] ile eşleşir.
  • logsnr_min (float, varsayılan -6.2) — Gürültü zamanlaması için minimum log-SNR değeri — zamanlamanın yüksek gürültülü başlangıcına eşlenir.
  • logsnr_max (float, varsayılan 2.0) — Gürültü zamanlaması için maksimum log-SNR değeri — zamanlamanın düşük gürültülü ucuna eşlenir.
  • silence_padding_duration (float, varsayılan 0.0) — Hedef içeriğin ardından eklenen sessizlik payı.
  • num_waveforms_per_prompt (int, varsayılan 1) — İstek başına dalga formu sayısı.
  • generator — Yeniden üretilebilirlik için RNG.
  • latents — Önceden oluşturulmuş başlangıç gürültüsü (None → taze örnek).
  • prompt_embeds — Ön hesaplanmış metin gömümleri.
  • encoder_attention_mask — Ön hesaplanmış gömceler için maske.
  • return_dict (bool, varsayılan True) — AudioPipelineOutput veya tuple döndürür.
  • callback_on_step_end (Callable, isteğe bağlı) — Her gürültü azaltma adımının sonunda (self, step_idx, timestep, callback_kwargs) ile çağrılır. Döngünün geri kalanında kullanılacak (isteğe bağlı olarak değiştirilmiş) tensörleri içeren bir sözlük döndürmelidir.
  • callback_on_step_end_tensor_inputs (list[str], varsayılan [“latents”]) — callback_on_step_end'e iletilen tensörler. self._callback_tensor_inputs'ün bir alt kümesi olmalıdır.
  • output_type (str, varsayılan "pt") — "pt" / "np" / "latent".

Bir metin istemi ve referans koşullu olarak inpainted ses üretin.

Örnekler:

>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3InpaintPipeline

>>> pipe = StableAudio3InpaintPipeline.from_pretrained(
...     "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")

>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     audio=audio,
...     mask_start_seconds=4.0,
...     mask_end_seconds=6.0,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)

encode_duration

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Parametreler

  • duration — Saniye cinsinden süre, batch'teki her örneğe uygulanır.
  • device — Hedef cihaz.
  • num_waveforms_per_prompt — Karo çarpanı.
  • batch_size — İstek sayısı.

Süre değerini küresel koşullandırma vektörüne gömün.

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )

Parametreler

  • prompt — Metin istemi veya istemler listesi. prompt_embeds sağlandığında yok sayılır.
  • device — Hedef cihaz.
  • num_waveforms_per_prompt — Her prompt için üretilecek çıktı dalga formu sayısı; koşullama tensörleri buna göre çoğaltılır.
  • prompt_embeds — Ön hesaplanmış metin gömme değerleri (batch, seq_len, hidden_size).
  • encoder_attention_mask — önceden hesaplanmış gömceler için Boole maskesi (batch, seq_len); 1 = gerçek token, 0 = dolgu.

Metin istemlerini çapraz dikkat koşullama tensörlerine kodlayın.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Çapraz dikkat bağlamını, süre gömme değerini ek bir jeton olarak ekleyerek oluşturun.

SA3, seconds_total koşullandırıcısını hem küresel (AdaLN) girdiye hem de ikisine de olan çapraz dikkat bağlamına (cross_attention_cond_ids = ["prompt", "seconds_total"]) yönlendirir. Süre gömme (embedding) metin jetonlarının ardından birleştirilir ve dikkat maskesi bir geçerli girişle genişletilir.

StableAudio3AudioToAudioPipeline

Referans ses kliplerinin bir varyasyonunu üretir: tüm referans, init_noise_level seviyesine kadar gürültülenir ve oradan gürültüsü giderilir; bu, belirli kareleri tam olarak koruyan StableAudio3InpaintPipeline'ın kare bazlı yerel-eklemeli koşullandırmasından farklıdır.

sınıf diffusers.StableAudio3AudioToAudioPipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Parametreler

  • vae ([AutoencoderSAME]) — Ses latentlerini kodlamak ve çözmek için kullanılan SAME otoenkoderi.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Donmuş T5Gemma metin kodlayıcısı (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Metin kodlayıcı için tokenizer.
  • duration_embedder ([StableAudio3DurationEmbedder]) — duration değerini saniye cinsinden, her DiT bloğundaki AdaLN için küresel bir koşullandırma vektörüne eşler.
  • transformer ([StableAudio3DiTModel]) — Düzeltme akışı hız tahmini DiT.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — İteratif gürültü azaltma döngüsü için zamanlayıcı. Üretim (damıtılmış) SA3 Medium kontrol noktası tam olarak 8 ping-pong adımı için stochastic_sampling=True kullanır; damıtılmamış temel kontrol noktası ise ~100 deterministik Euler adımı için stochastic_sampling=False kullanır.

Stable Audio 3 için sesten sese varyasyon hattı.

Metin-ses mantığını [StableAudio3Pipeline] ile paylaşır (# Copied from üzerinden senkronize tutulur). Referans sesi dondurulmuş SAME kodlayıcıyla kodlar, init_noise_level'ye göre taze gürültüyle karıştırır ve oradan gürültü giderme işlemine başlar — [StableAudio3InpaintPipeline]'ın çerçeve başına yerel-eklemeli koşullandırmasının aksine, tüm sinyal küresel olarak gürültülenir/gürültüsü giderilir.

Çağrı imzası uzantısı (bkz. __call__): audio (torch.Tensor, şekli (batch, channels, samples)): vae.config.sampling_rate Hz'de referans ses dalgası. init_noise_level (float): Gürültü azaltma işleminden önce referansa karıştırılacak gürültü miktarı. 1.0 = tam gürültü (text-to-audio ile eşdeğer); daha düşük değerler referansın daha büyük bir kısmını korur.

__call__

< >

( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Noneinit_noise_level: float = 1.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )

Parametreler

  • prompt (str veya list[str], isteğe bağlı) — Metin istemleri.
  • duration (float, varsayılan 10.0) — Saniye cinsinden çıktı süresi. Referans sesle eşleşmelidir.
  • audio (torch.Tensor, optional) — vae.config.sampling_rate Hz'de (batch, channels, samples) referans dalga formu. Zorunludur.
  • init_noise_level (float, varsayılan 1.0) — Gürültü seviyesi ((0, 1] aralığında), gürültüden arındırma öncesinde referansa karıştırılır: x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise. 1.0 değeri referansı tamamen atlar ([StableAudio3Pipeline] ile eşdeğerdir); daha düşük değerler, tam adım sayısını çalıştırmaya devam ederken referansın yapısını giderek daha fazla korur.
  • num_inference_steps (int, isteğe bağlı) — Gürültü azaltma adım sayısı. None (varsayılan) olduğunda, adım sayısı zamanlayıcının stochastic_sampling yapılandırmasından seçilir ve [StableAudio3Pipeline] ile eşleşir.
  • logsnr_min (float, varsayılan -6.2) — Gürültü zamanlaması için minimum log-SNR değeri — zamanlamanın yüksek gürültülü başlangıcına eşlenir.
  • logsnr_max (float, varsayılan 2.0) — Gürültü zamanlaması için maksimum log-SNR değeri — zamanlamanın düşük gürültülü ucuna eşlenir.
  • silence_padding_duration (float, varsayılan 0.0) — Hedef içeriğin ardından eklenen sessizlik payı.
  • num_waveforms_per_prompt (int, varsayılan 1) — İstek başına dalga formu sayısı.
  • generator — Yeniden üretilebilirlik için RNG.
  • latents — Önceden oluşturulmuş başlangıç gürültüsü (None → taze örnek).
  • prompt_embeds — Ön hesaplanmış metin gömümleri.
  • encoder_attention_mask — Ön hesaplanmış gömceler için maske.
  • return_dict (bool, varsayılan True) — AudioPipelineOutput veya tuple döndürür.
  • callback_on_step_end (Callable, isteğe bağlı) — Her gürültü azaltma adımının sonunda (self, step_idx, timestep, callback_kwargs) ile çağrılır. Döngünün geri kalanında kullanılacak (isteğe bağlı olarak değiştirilmiş) tensörleri içeren bir sözlük döndürmelidir.
  • callback_on_step_end_tensor_inputs (list[str], varsayılan [“latents”]) — callback_on_step_end'e iletilen tensörler. self._callback_tensor_inputs'ün bir alt kümesi olmalıdır.
  • output_type (str, varsayılan "pt") — "pt" / "np" / "latent".

Bir metin komutu ve bir referans dalga formuna koşullu bir ses varyasyonu oluşturun.

Örnekler:

>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3AudioToAudioPipeline

>>> pipe = StableAudio3AudioToAudioPipeline.from_pretrained(
...     "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")

>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")

>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
...     "A gentle piano melody with soft strings in a concert hall",
...     duration=10.0,
...     audio=audio,
...     init_noise_level=0.6,
...     generator=generator,
... ).audios

>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)

encode_duration

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Parametreler

  • duration — Saniye cinsinden süre, batch'teki her örneğe uygulanır.
  • device — Hedef cihaz.
  • num_waveforms_per_prompt — Karo çarpanı.
  • batch_size — İstek sayısı.

Süre değerini küresel koşullandırma vektörüne gömün.

encode_prompt

< >

( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )

Parametreler

  • prompt — Metin istemi veya istemler listesi. prompt_embeds sağlandığında yok sayılır.
  • device — Hedef cihaz.
  • num_waveforms_per_prompt — Her prompt için üretilecek çıktı dalga formu sayısı; koşullama tensörleri buna göre çoğaltılır.
  • prompt_embeds — Ön hesaplanmış metin gömme değerleri (batch, seq_len, hidden_size).
  • encoder_attention_mask — önceden hesaplanmış gömceler için Boole maskesi (batch, seq_len); 1 = gerçek token, 0 = dolgu.

Metin istemlerini çapraz dikkat koşullama tensörlerine kodlayın.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Çapraz dikkat bağlamını, süre gömme değerini ek bir jeton olarak ekleyerek oluşturun.

SA3, seconds_total koşullandırıcısını hem küresel (AdaLN) girdiye hem de ikisine de olan çapraz dikkat bağlamına (cross_attention_cond_ids = ["prompt", "seconds_total"]) yönlendirir. Süre gömme (embedding) metin jetonlarının ardından birleştirilir ve dikkat maskesi bir geçerli girişle genişletilir.

StableAudio3DurationEmbedder

sınıf diffusers.StableAudio3DurationEmbedder

< >

( output_dim: int = 768fourier_dim: int = 256min_val: float = 0.0max_val: float = 384.0min_freq: float = 0.5max_freq: float = 10000.0 )

Parametreler

  • output_dim (int, varsayılan 768) — Çıktı gömme boyutu. DiT'nin global_cond_dim değeriyle eşleşmelidir.
  • fourier_dim (int, varsayılan 256) — Dahili Fourier özellik boyutu (çift olmalıdır).
  • min_val (float, varsayılan 0.0) — Normalizasyon sınırlama işlemi için minimum süre değeri.
  • max_val (float, varsayılan 384.0) — Normalizasyon sınırlaması için maksimum süre değeri. Bu değerin üzerindeki değerler sınırlanır. 384 saniye, seconds_total koşullandırıcısı için üretim SA3 Medium üst sınırıdır.
  • min_freq (float, varsayılan 0.5) — Üstel Fourier tabanı için minimum frekans.
  • max_freq (float, varsayılan 10000.0) — Üstel Fourier tabanı için maksimum frekans.

Süre değerini (saniye cinsinden) Stable Audio 3 DiT için küresel koşullandırma vektörüne gömer (AdaLN girdisi olarak global_hidden_states kullanılır).

SA3 referans uygulamasındaki NumberConditioner(fourier_features_type="expo") bileşenini yeniden oluşturur.

forward

< >

( seconds: Tensor )

Parametreler

  • seconds (torch.Tensor, şekli (batch,)) — Saniye cinsinden süre değerleri.
Update on GitHub

←Stable Audio Anima→