Hugging Face's logo

Diffusers documentation

Stable Audio 3

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

Stable Audio 3

Stable Audio 3 (SA3) adalah model teks-ke-audio dari Stability AI yang menghasilkan audio stereo berkualitas tinggi pada 44,1 kHz. Model ini menggunakan rectified-flow DiT yang dikondisikan oleh dua sinyal:

  • Teks — dikodekan oleh encoder T5Gemma yang dibekukan dan disuntikkan melalui cross-attention.
  • Durasi — float (detik) yang disematkan oleh StableAudio3DurationEmbedder dan digunakan sebagai vektor kondisioning global untuk normalisasi lapisan adaptif.

Audio didekodekan oleh autoencoder SAME (Semantically-Aligned Music Encoder), AutoencoderSAME.

Kedua checkpoint menggunakan FlowMatchEulerDiscreteScheduler dengan jadwal sigma log-SNR-uniform, yang hanya berbeda pada stochastic_sampling dan jumlah langkah default:

Checkpointdiffusion_objectivestochastic_samplingnum_inference_steps
stable-audio-3-medium-baserectified_flowFalse (Euler deterministik)100 (tidak di-distilasi)
stable-audio-3-medium (distilled)rf_denoiserTrue (re-noise ping-pong)8 (distilasi selama 8 langkah)

Konfigurasi scheduler yang benar sudah tertanam di setiap checkpoint yang dikonversi, sehingga num_inference_steps secara default akan mengambil nilai yang tepat jika Anda tidak menyetelnya. Hanya berikan parameter ini jika Anda ingin menimpa nilai tersebut.

Codebase asli: Stability-AI/stable-audio-3.

Mengonversi checkpoint asli

Checkpoint Stability AI tidak dipublikasikan dalam format diffusers, jadi konversikan secara lokal. Skrip ini mengunduh model_config.json dari checkpoint dan memilih scheduler berdasarkan diffusion_objective-nya:

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 adalah repo bergerbang. Jalankan hf auth login dengan akun yang memiliki akses sebelum melakukan konversi, jika tidak unduhan akan gagal dengan 401.

Contoh penggunaan

Muat checkpoint yang telah dikonversi dari direktori output lokalnya (instal soundfile dengan pip install soundfile):

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 juga terdaftar dengan AutoPipelineForText2Audio, yang secara otomatis menyelesaikan checkpoint menjadi StableAudio3Pipeline:

from diffusers import AutoPipelineForText2Audio

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

Contoh menggunakan jalur lokal karena stabilityai/stable-audio-3-medium dan stable-audio-3-medium-base belum dipublikasikan dalam format diffusers (memuat dengan repo id mengembalikan 404). Setelah dipublikasikan, repo id dapat digunakan sebagai pengganti jalur lokal.

Tips

  • Gunakan torch.float32 pada CPU atau MPS (Apple Silicon) — torch.float16 pada MPS menghasilkan noise.
  • Model terdistilasi (stable-audio-3-medium) adalah adversarially distilled — guidance sudah tertanam ke dalam bobot. Biarkan guidance_scale=1.0 (default) dan jangan lewatkan negative_prompt untuk checkpoint tersebut; keduanya hanya berguna untuk checkpoint stable-audio-3-medium-base yang tidak terdistilasi.
  • silence_padding_duration (default 0.0) menambahkan ruang hening di akhir urutan latent. Biarkan tetap 0.0 kecuali model dilatih untuk memasking padding tersebut — jika tidak, frame tambahan akan menguras energi output dan hasilnya menjadi lebih pelan.
  • Setel num_waveforms_per_prompt > 1 untuk menghasilkan beberapa klip per prompt.

StableAudio3Pipeline

kelas diffusers.StableAudio3Pipeline

< >

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

Parameter

  • vae ([AutoencoderSAME]) — Autoencoder SAME yang digunakan untuk mengodekan dan mendekodekan latens audio.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — T5Gemma text encoder yang dibekukan (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Tokenizer untuk text encoder.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Memetakan duration dalam detik ke vektor kondisioning global untuk AdaLN di setiap blok DiT.
  • transformer ([StableAudio3DiTModel]) — DiT prediksi kecepatan rectified-flow.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — Scheduler untuk loop denoising iteratif. Checkpoint SA3 Medium produksi (distilled) menggunakan stochastic_sampling=True untuk tepat 8 langkah ping-pong; checkpoint base non-distilled menggunakan stochastic_sampling=False untuk ~100 langkah Euler deterministik.

Pipeline untuk generasi teks-ke-audio menggunakan Stable Audio 3.

SA3 menggunakan DiT rectified-flow yang telah didistil dengan sampling ping-pong. Panduan bebas-klasifikator (guidance_scale / negative_prompt) tidak diperlukan untuk checkpoint yang telah didistil (biarkan guidance_scale=1.0, nilai default), tetapi bermakna untuk checkpoint stable-audio-3-medium-base yang tidak didistil.

Model ini mewarisi dari [DiffusionPipeline]. Periksa dokumentasi kelas induk untuk metode generik yang diimplementasikan untuk semua pipeline.

__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

Parameter

  • prompt (str atau list[str], opsional) — Prompt teks. Lewati tokenisasi dan enkoding dengan meneruskan prompt_embeds sebagai gantinya.
  • duration (float, defaultnya 10.0) — Durasi output yang diminta dalam detik.
  • num_inference_steps (int, opsional) — Jumlah langkah denoising. Ketika None (default), jumlah langkah dipilih dari konfigurasi stochastic_sampling scheduler: 8 ketika True (checkpoint bergaya ping-pong yang telah didistilasi) dan 100 ketika False (checkpoint dasar yang tidak didistilasi). Sampaikan nilai eksplisit untuk menimpa.
  • logsnr_min (float, default -6.2) — Nilai log-SNR minimum untuk jadwal noise — memetakan ke awal jadwal dengan noise tinggi.
  • logsnr_max (float, default 2.0) — Nilai log-SNR maksimum untuk jadwal noise — memetakan ke ujung ber-noise rendah dari jadwal.
  • silence_padding_duration (float, default 0.0) — Detik tambahan konteks laten yang dihasilkan melampaui konten target, memberikan ruang bagi model di batas; output akan dipangkas kembali ke duration. Default 0.0 (nonaktif). Tingkatkan hanya jika model dilatih/distil untuk memasking padding ini — jika tidak, frame tambahan akan menguras energi output.
  • guidance_scale (float, default 1.0) — Skala panduan bebas klasifikator. 1.0 menonaktifkan panduan (nilai default, dan satu-satunya nilai yang masuk akal untuk checkpoint SA3 Medium yang telah didistilasi, karena CFG-nya sudah tertanam dalam bobot). Nilai > 1.0 bermakna untuk checkpoint stable-audio-3-medium-base yang tidak didistilasi; nilai yang lebih tinggi mengikuti prompt dengan lebih ketat dengan mengorbankan keragaman.
  • negative_prompt (str atau list[str], opsional) — Prompt yang menggambarkan apa yang harus dihindari saat guidance_scale > 1.0. Nilainya secara default adalah string kosong (tanpa kondisi) ketika guidance_scale > 1.0 dan baik parameter ini maupun negative_prompt_embeds tidak diberikan. Diabaikan ketika guidance_scale <= 1.0.
  • num_waveforms_per_prompt (int, defaultnya 1) — Jumlah waveform yang akan dihasilkan per prompt.
  • generator (torch.Generator atau list[torch.Generator], opsional) — Untuk generasi deterministik dan re-noise yang dapat direproduksi dalam loop ping-pong.
  • latents (torch.Tensor, opsional) — Latents awal yang telah dibuat sebelumnya. Jika None, tensor Gaussian baru akan diambil.
  • prompt_embeds (torch.Tensor, opsional) — Embedding teks yang sudah dihitung sebelumnya (batch, seq_len, 768).
  • encoder_attention_mask (torch.LongTensor, opsional) — Mask boolean untuk embedding yang sudah dihitung sebelumnya.
  • negative_prompt_embeds (torch.Tensor, opsional) — Embedding teks negatif yang sudah dihitung sebelumnya, sebagai alternatif dari negative_prompt.
  • negative_encoder_attention_mask (torch.LongTensor, opsional) — Mask boolean untuk embedding negatif yang sudah dihitung sebelumnya.
  • return_dict (bool, defaultnya True) — Mengembalikan AudioPipelineOutput atau tuple biasa.
  • callback_on_step_end (Callable, opsional) — Dipanggil di akhir setiap langkah denoising dengan (self, step_idx, timestep, callback_kwargs), di mana callback_kwargs berisi tensor yang tercantum dalam callback_on_step_end_tensor_inputs. Harus mengembalikan dict dengan tensor (yang mungkin telah dimodifikasi) untuk digunakan di sisa loop.
  • callback_on_step_end_tensor_inputs (list[str], defaultnya [“latents”]) — Tensor yang diteruskan ke callback_on_step_end. Harus berupa subset dari self._callback_tensor_inputs.
  • output_type (str, defaultnya "pt") — "pt" untuk tensor PyTorch, "np" untuk array NumPy, atau "latent" untuk melewati decoding dan mengembalikan latents mentah.

Mengembalikan

[~pipelines.AudioPipelineOutput] atau tuple

.audios adalah tensor / array dengan bentuk (batch * num_waveforms_per_prompt, audio_channels, samples).

Generate audio dari prompt teks.

Contoh:

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

Parameter

  • duration — Durasi dalam detik, diterapkan ke setiap sampel dalam batch.
  • device — Perangkat target.
  • num_waveforms_per_prompt — Faktor ubin.
  • batch_size — Jumlah prompt.

Tanamkan nilai durasi ke dalam vektor kondisi global.

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 )

Parameter

  • prompt — Prompt teks atau daftar prompt. Diabaikan saat prompt_embeds disediakan.
  • device — Perangkat target.
  • num_waveforms_per_prompt — Berapa banyak waveform output yang akan dihasilkan per prompt; tensor conditioning akan di-tile sesuai dengan itu.
  • prompt_embeds — Embedding teks yang sudah dihitung sebelumnya (batch, seq_len, hidden_size).
  • encoder_attention_mask — Mask Boolean (batch, seq_len) untuk embedding yang sudah dihitung sebelumnya; 1 = token asli, 0 = pad.

Enkode prompt teks menjadi tensor kondisioning cross-attention.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Bangun konteks cross-attention dengan menambahkan durasi embedding sebagai token tambahan.

SA3 merutekan conditioner seconds_total ke keduanya, yaitu input global (AdaLN) dan konteks cross-attention (cross_attention_cond_ids = ["prompt", "seconds_total"]). Embedding durasi digabungkan setelah token teks, dan attention mask diperluas dengan satu entri valid.

StableAudio3InpaintPipeline

kelas diffusers.StableAudio3InpaintPipeline

< >

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

Parameter

  • vae ([AutoencoderSAME]) — Autoencoder SAME yang digunakan untuk mengodekan dan mendekodekan latens audio.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — T5Gemma text encoder yang dibekukan (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Tokenizer untuk text encoder.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Memetakan duration dalam detik ke vektor kondisioning global untuk AdaLN di setiap blok DiT.
  • transformer ([StableAudio3DiTModel]) — DiT prediksi kecepatan rectified-flow.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — Scheduler untuk loop denoising iteratif. Checkpoint SA3 Medium produksi (distilled) menggunakan stochastic_sampling=True untuk tepat 8 langkah ping-pong; checkpoint base non-distilled menggunakan stochastic_sampling=False untuk ~100 langkah Euler deterministik.

Pipeline inpainting audio untuk Stable Audio 3.

Berbagi logika teks-ke-audio dengan [StableAudio3Pipeline] (dijaga sinkron melalui # Copied from). Ketika audio dan mask disediakan, mengodekan audio referensi dengan encoder SAME yang dibekukan dan menyuntikkan masked_latent ∥ mask sebagai kondisioning aditif lokal ke setiap blok DiT melalui jalur local_add_cond transformer (to_local_embed).

Ekstensi tanda panggil (lihat __call__): audio (torch.Tensor dengan bentuk (batch, channels, samples)): Gelombang audio referensi pada vae.config.sampling_rate Hz. mask (torch.Tensor dengan bentuk (batch, 1, latent_length)): Mask biner per-frame di ruang laten. 1 = pertahankan audio asli; 0 = wilayah yang akan di-inpaint.

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

Parameter

  • prompt (str atau list[str], opsional) — Prompt teks.
  • duration (float, defaultnya 10.0) — Durasi output dalam detik. Seharusnya sesuai dengan audio referensi.
  • audio (torch.Tensor, optional) — Gelombang referensi (batch, channels, samples) pada vae.config.sampling_rate Hz. Diperlukan untuk inpainting.
  • mask (torch.Tensor, optional) — Mask ruang laten per-frame (batch, 1, L) dengan 0 = area inpaint, 1 = pertahankan. Salah satu dari mask atau mask_start_seconds / mask_end_seconds harus disediakan.
  • mask_start_seconds (float atau list[float], opsional) — Waktu mulai (dalam detik) dari area inpaint.
  • mask_end_seconds (float atau list[float], opsional) — Waktu akhir dari region inpaint (harus berpasangan dengan mask_start_seconds).
  • num_inference_steps (int, opsional) — Jumlah langkah denoising. Ketika None (default), jumlah langkah dipilih dari konfigurasi stochastic_sampling scheduler, sesuai dengan [StableAudio3Pipeline].
  • logsnr_min (float, default -6.2) — Nilai log-SNR minimum untuk jadwal noise — memetakan ke awal jadwal dengan noise tinggi.
  • logsnr_max (float, default 2.0) — Nilai log-SNR maksimum untuk jadwal noise — memetakan ke ujung ber-noise rendah dari jadwal.
  • silence_padding_duration (float, default 0.0) — Ruang cadangan laten tambahan setelah konten target.
  • num_waveforms_per_prompt (int, defaultnya 1) — Bentuk gelombang per prompt.
  • generator — RNG untuk reproduktibilitas.
  • latents — Noise awal yang sudah dibuat sebelumnya (None → ambil sampel baru).
  • prompt_embeds — Embedding teks yang sudah dihitung sebelumnya.
  • encoder_attention_mask — Mask untuk embedding yang sudah dihitung sebelumnya.
  • return_dict (bool, defaultnya True) — Kembalikan AudioPipelineOutput atau tuple.
  • callback_on_step_end (Callable, opsional) — Dipanggil di akhir setiap langkah denoising dengan (self, step_idx, timestep, callback_kwargs). Harus mengembalikan dict dengan tensor (yang mungkin telah dimodifikasi) untuk digunakan di sisa loop.
  • callback_on_step_end_tensor_inputs (list[str], defaultnya [“latents”]) — Tensor yang diteruskan ke callback_on_step_end. Harus berupa subset dari self._callback_tensor_inputs.
  • output_type (str, defaultnya "pt") — "pt" / "np" / "latent".

Generate audio inpainted yang dikondisikan pada prompt teks dan referensi.

Contoh:

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

Parameter

  • duration — Durasi dalam detik, diterapkan ke setiap sampel dalam batch.
  • device — Perangkat target.
  • num_waveforms_per_prompt — Faktor ubin.
  • batch_size — Jumlah prompt.

Tanamkan nilai durasi ke dalam vektor kondisi global.

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 )

Parameter

  • prompt — Prompt teks atau daftar prompt. Diabaikan saat prompt_embeds disediakan.
  • device — Perangkat target.
  • num_waveforms_per_prompt — Berapa banyak waveform output yang akan dihasilkan per prompt; tensor conditioning akan di-tile sesuai dengan itu.
  • prompt_embeds — Embedding teks yang sudah dihitung sebelumnya (batch, seq_len, hidden_size).
  • encoder_attention_mask — Mask Boolean (batch, seq_len) untuk embedding yang sudah dihitung sebelumnya; 1 = token asli, 0 = pad.

Enkode prompt teks menjadi tensor kondisioning cross-attention.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Bangun konteks cross-attention dengan menambahkan durasi embedding sebagai token tambahan.

SA3 merutekan conditioner seconds_total ke keduanya, yaitu input global (AdaLN) dan konteks cross-attention (cross_attention_cond_ids = ["prompt", "seconds_total"]). Embedding durasi digabungkan setelah token teks, dan attention mask diperluas dengan satu entri valid.

StableAudio3AudioToAudioPipeline

Membuat variasi dari klip audio referensi: seluruh referensi diberi noise hingga init_noise_level dan kemudian dinoise dari titik tersebut, berbeda dengan kondisioning aditif lokal per-frame pada StableAudio3InpaintPipeline yang mempertahankan frame tertentu secara persis.

kelas diffusers.StableAudio3AudioToAudioPipeline

< >

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

Parameter

  • vae ([AutoencoderSAME]) — Autoencoder SAME yang digunakan untuk mengodekan dan mendekodekan latens audio.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — T5Gemma text encoder yang dibekukan (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Tokenizer untuk text encoder.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Memetakan duration dalam detik ke vektor kondisioning global untuk AdaLN di setiap blok DiT.
  • transformer ([StableAudio3DiTModel]) — DiT prediksi kecepatan rectified-flow.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — Scheduler untuk loop denoising iteratif. Checkpoint SA3 Medium produksi (distilled) menggunakan stochastic_sampling=True untuk tepat 8 langkah ping-pong; checkpoint base non-distilled menggunakan stochastic_sampling=False untuk ~100 langkah Euler deterministik.

Pipeline variasi audio-ke-audio untuk Stable Audio 3.

Berbagi logika teks-ke-audio dengan [StableAudio3Pipeline] (dijaga sinkron melalui # Copied from). Mengenkod audio referensi dengan encoder SAME yang dibekukan, mencampurnya dengan noise baru sesuai init_noise_level, dan melakukan denoising dari titik tersebut — seluruh sinyal di-noise/denoise secara global, berbeda dengan kondisioning aditif lokal per-frame pada [StableAudio3InpaintPipeline].

Ekstensi tanda panggil (lihat __call__): audio (torch.Tensor dengan bentuk (batch, channels, samples)): Gelombang audio referensi pada vae.config.sampling_rate Hz. init_noise_level (float): Seberapa banyak noise yang dicampurkan ke referensi sebelum denoising. 1.0 = noise penuh (setara dengan text-to-audio); nilai yang lebih rendah mempertahankan lebih banyak dari referensi.

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

Parameter

  • prompt (str atau list[str], opsional) — Prompt teks.
  • duration (float, defaultnya 10.0) — Durasi output dalam detik. Seharusnya sesuai dengan audio referensi.
  • audio (torch.Tensor, optional) — Gelombang referensi (batch, channels, samples) pada vae.config.sampling_rate Hz. Wajib diisi.
  • init_noise_level (float, default 1.0) — Tingkat noise (dalam (0, 1]) yang dicampurkan ke referensi sebelum denoising: x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise. 1.0 membuang referensi sepenuhnya (setara dengan [StableAudio3Pipeline]); nilai yang lebih rendah mempertahankan semakin banyak struktur referensi sambil tetap menjalankan jumlah langkah penuh.
  • num_inference_steps (int, opsional) — Jumlah langkah denoising. Ketika None (default), jumlah langkah dipilih dari konfigurasi stochastic_sampling scheduler, sesuai dengan [StableAudio3Pipeline].
  • logsnr_min (float, default -6.2) — Nilai log-SNR minimum untuk jadwal noise — memetakan ke awal jadwal dengan noise tinggi.
  • logsnr_max (float, default 2.0) — Nilai log-SNR maksimum untuk jadwal noise — memetakan ke ujung ber-noise rendah dari jadwal.
  • silence_padding_duration (float, default 0.0) — Ruang cadangan laten tambahan setelah konten target.
  • num_waveforms_per_prompt (int, defaultnya 1) — Bentuk gelombang per prompt.
  • generator — RNG untuk reproduktibilitas.
  • latents — Noise awal yang sudah dibuat sebelumnya (None → ambil sampel baru).
  • prompt_embeds — Embedding teks yang sudah dihitung sebelumnya.
  • encoder_attention_mask — Mask untuk embedding yang sudah dihitung sebelumnya.
  • return_dict (bool, defaultnya True) — Kembalikan AudioPipelineOutput atau tuple.
  • callback_on_step_end (Callable, opsional) — Dipanggil di akhir setiap langkah denoising dengan (self, step_idx, timestep, callback_kwargs). Harus mengembalikan dict dengan tensor (yang mungkin telah dimodifikasi) untuk digunakan di sisa loop.
  • callback_on_step_end_tensor_inputs (list[str], defaultnya [“latents”]) — Tensor yang diteruskan ke callback_on_step_end. Harus berupa subset dari self._callback_tensor_inputs.
  • output_type (str, defaultnya "pt") — "pt" / "np" / "latent".

Buat variasi audio yang dikondisikan pada prompt teks dan waveform referensi.

Contoh:

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

Parameter

  • duration — Durasi dalam detik, diterapkan ke setiap sampel dalam batch.
  • device — Perangkat target.
  • num_waveforms_per_prompt — Faktor ubin.
  • batch_size — Jumlah prompt.

Tanamkan nilai durasi ke dalam vektor kondisi global.

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 )

Parameter

  • prompt — Prompt teks atau daftar prompt. Diabaikan saat prompt_embeds disediakan.
  • device — Perangkat target.
  • num_waveforms_per_prompt — Berapa banyak waveform output yang akan dihasilkan per prompt; tensor conditioning akan di-tile sesuai dengan itu.
  • prompt_embeds — Embedding teks yang sudah dihitung sebelumnya (batch, seq_len, hidden_size).
  • encoder_attention_mask — Mask Boolean (batch, seq_len) untuk embedding yang sudah dihitung sebelumnya; 1 = token asli, 0 = pad.

Enkode prompt teks menjadi tensor kondisioning cross-attention.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Bangun konteks cross-attention dengan menambahkan durasi embedding sebagai token tambahan.

SA3 merutekan conditioner seconds_total ke keduanya, yaitu input global (AdaLN) dan konteks cross-attention (cross_attention_cond_ids = ["prompt", "seconds_total"]). Embedding durasi digabungkan setelah token teks, dan attention mask diperluas dengan satu entri valid.

StableAudio3DurationEmbedder

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

Parameter

  • output_dim (int, defaultnya 768) — Dimensi dari output embedding. Harus cocok dengan global_cond_dim dari DiT.
  • fourier_dim (int, defaultnya 256) — Dimensi fitur Fourier internal (harus genap).
  • min_val (float, defaultnya 0.0) — Nilai durasi minimum untuk clamping normalisasi.
  • max_val (float, defaultnya 384.0) — Nilai durasi maksimum untuk clamping normalisasi. Nilai di atas ambang ini akan di-clamp. 384 detik adalah batas atas produksi SA3 Medium untuk conditioner seconds_total.
  • min_freq (float, defaultnya 0.5) — Frekuensi minimum untuk basis Fourier eksponensial.
  • max_freq (float, defaultnya 10000.0) — Frekuensi maksimum untuk basis Fourier eksponensial.

Menanamkan nilai durasi (dalam detik) ke dalam vektor kondisioning global untuk Stable Audio 3 DiT (digunakan sebagai input AdaLN global_hidden_states).

Mereplikasi NumberConditioner(fourier_features_type="expo") dari implementasi referensi SA3.

forward

< >

( seconds: Tensor )

Parameter

  • seconds (torch.Tensor dengan bentuk (batch,)) — Nilai durasi dalam detik.
Update on GitHub

←Stable Audio Anima→