# Stable Audio 3

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

* **Teks** — dikodekan oleh encoder T5Gemma yang dibekukan dan disuntikkan melalui cross-attention.
* **Durasi** — float (detik) yang disematkan oleh [StableAudio3DurationEmbedder](/docs/diffusers/main/id/api/pipelines/stable_audio_3#diffusers.StableAudio3DurationEmbedder) dan digunakan sebagai vektor kondisioning global untuk normalisasi lapisan adaptif.

Audio didekodekan oleh autoencoder SAME (Semantically-Aligned Music Encoder), [AutoencoderSAME](/docs/diffusers/main/id/api/models/autoencoder_same#diffusers.AutoencoderSAME).

Kedua checkpoint menggunakan [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/id/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) dengan jadwal sigma log-SNR-uniform, yang hanya berbeda pada `stochastic_sampling` dan jumlah langkah default:

| Checkpoint | `diffusion_objective` | `stochastic_sampling` | `num_inference_steps` |
|---|---|---|---|
| `stable-audio-3-medium-base` | `rectified_flow` | `False` (Euler deterministik) | **100** (tidak di-distilasi) |
| `stable-audio-3-medium` (distilled) | `rf_denoiser` | `True` (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 default.

Codebase asli: [Stability-AI/stable-audio-3](https://github.com/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:

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

> [!TIP]
> `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`](https://pypi.org/project/soundfile/) dengan `pip install soundfile`):

```py
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](/docs/diffusers/main/id/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Audio), yang secara otomatis menyelesaikan checkpoint menjadi `StableAudio3Pipeline`:

```py
from diffusers import AutoPipelineForText2Audio

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

> [!NOTE]
> Contoh menggunakan jalur lokal karena `stabilityai/stable-audio-3-medium` dan `stable-audio-3-medium-base` belum dipublikasikan dalam format diffusers (memuat melalui 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 kirimkan `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 mem-mask 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[[diffusers.StableAudio3Pipeline]]

#### diffusers.StableAudio3Pipeline[[diffusers.StableAudio3Pipeline]]

```python
diffusers.StableAudio3Pipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L157)

**Parameter:**

vae ([*AutoencoderSAME*]) : autoencoder SAME yang digunakan untuk mengodekan dan mendekodekan latens audio.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : Encoder teks T5Gemma 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__[[diffusers.StableAudio3Pipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, guidance_scale: float = 1.0, negative_prompt: typing.Union[str, typing.List[str], NoneType] = None, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, negative_encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt')
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L398)

**Parameter:**

prompt (*str* atau *list[str]*, *opsional*) : Prompt teks. Gunakan `prompt_embeds` sebagai gantinya untuk melewati tokenisasi dan encoding.

duration (*float*, default 10.0) : Durasi output yang diminta dalam detik.

num_inference_steps (*int*, *optional*) : 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 basis yang tidak didistilasi). Sampaikan nilai eksplisit untuk menimpa.

logsnr_min (*float*, defaultnya -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 classifier-free. `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 ketika `guidance_scale > 1.0`. Secara default berupa string kosong (unconditional) 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*) : Latens 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 untuk *negative_prompt*.

negative_encoder_attention_mask (*torch.LongTensor*, *opsional*) : Mask boolean untuk embedding negatif yang telah 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:
```py
>>> 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[[diffusers.StableAudio3Pipeline.encode_duration]]

```python
encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L289)

**Parameter:**

duration : Durasi dalam detik, diterapkan ke setiap sampel dalam batch.

device : Perangkat target.

num_waveforms_per_prompt : Faktor ubin.

batch_size : Jumlah prompt.

**Mengembalikan:**

tensor `(batch * num_waveforms_per_prompt, output_dim)`.

Tanamkan nilai durasi ke dalam vektor kondisi global.

#### encode_prompt[[diffusers.StableAudio3Pipeline.encode_prompt]]

```python
encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L223)

**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 kondisi 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.

**Mengembalikan:**

`(prompt_embeds, encoder_attention_mask)` keduanya di-tile menjadi `batch * num_waveforms_per_prompt`.

Enkode prompt teks menjadi tensor kondisioning cross-attention.

#### prepare_cross_attention[[diffusers.StableAudio3Pipeline.prepare_cross_attention]]

```python
prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L313)

**Mengembalikan:**

`(context, context_mask)` dengan bentuk `(batch, T_text + 1, dim)` dan `(batch, T_text + 1)`.

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

SA3 merutekan kondisioner `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[[diffusers.StableAudio3InpaintPipeline]]

#### diffusers.StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]]

```python
diffusers.StableAudio3InpaintPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L158)

**Parameter:**

vae ([*AutoencoderSAME*]) : autoencoder SAME yang digunakan untuk mengodekan dan mendekodekan latens audio.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : Encoder teks T5Gemma 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` dari 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__[[diffusers.StableAudio3InpaintPipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, audio: typing.Optional[torch.Tensor] = None, mask: typing.Optional[torch.Tensor] = None, mask_start_seconds: typing.Union[float, typing.List[float], NoneType] = None, mask_end_seconds: typing.Union[float, typing.List[float], NoneType] = None, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt')
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L455)

**Parameter:**

prompt (*str* atau *list[str]*, *opsional*) : Prompt teks.

duration (*float*, default 10.0) : Durasi output dalam detik. Seharusnya sesuai dengan audio referensi.

audio (*torch.Tensor*, *opsional*) : Gelombang referensi `(batch, channels, samples)` pada `vae.config.sampling_rate` Hz. Diperlukan untuk inpainting.

mask (*torch.Tensor*, *opsional*) : Mask ruang laten per-frame `(batch, 1, L)` dengan 0 = area inpaint, 1 = simpan. 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*, defaultnya -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 latensi tambahan setelah konten target.

num_waveforms_per_prompt (*int*, defaultnya 1) : Jumlah waveform 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*) : Mengembalikan *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 opsional 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"`.

**Mengembalikan:**

[*~pipelines.AudioPipelineOutput*] dengan `.audios`.

Generate audio inpainted yang dikondisikan pada prompt teks dan referensi.

Contoh:
```py
>>> 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[[diffusers.StableAudio3InpaintPipeline.encode_duration]]

```python
encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L290)

**Parameter:**

duration : Durasi dalam detik, diterapkan ke setiap sampel dalam batch.

device : Perangkat target.

num_waveforms_per_prompt : Faktor ubin.

batch_size : Jumlah prompt.

**Mengembalikan:**

tensor `(batch * num_waveforms_per_prompt, output_dim)`.

Tanamkan nilai durasi ke dalam vektor kondisi global.

#### encode_prompt[[diffusers.StableAudio3InpaintPipeline.encode_prompt]]

```python
encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L223)

**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 kondisi 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.

**Mengembalikan:**

`(prompt_embeds, encoder_attention_mask)` keduanya di-tile menjadi `batch * num_waveforms_per_prompt`.

Enkode prompt teks menjadi tensor kondisioning cross-attention.

#### prepare_cross_attention[[diffusers.StableAudio3InpaintPipeline.prepare_cross_attention]]

```python
prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L315)

**Mengembalikan:**

`(context, context_mask)` dengan bentuk `(batch, T_text + 1, dim)` dan `(batch, T_text + 1)`.

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

SA3 merutekan kondisioner `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[[diffusers.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](/docs/diffusers/main/id/api/pipelines/stable_audio_3#diffusers.StableAudio3InpaintPipeline) yang mempertahankan frame tertentu secara persis.

#### diffusers.StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]]

```python
diffusers.StableAudio3AudioToAudioPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L154)

**Parameter:**

vae ([*AutoencoderSAME*]) : autoencoder SAME yang digunakan untuk mengodekan dan mendekodekan latens audio.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : Encoder teks T5Gemma 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__[[diffusers.StableAudio3AudioToAudioPipeline.__call__]]

```python
__call__(prompt: typing.Union[str, typing.List[str], NoneType] = None, duration: float = 10.0, audio: typing.Optional[torch.Tensor] = None, init_noise_level: float = 1.0, num_inference_steps: typing.Optional[int] = None, logsnr_min: float = -6.2, logsnr_max: float = 2.0, silence_padding_duration: float = 0.0, num_waveforms_per_prompt: int = 1, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ['latents'], output_type: str = 'pt')
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L424)

**Parameter:**

prompt (*str* atau *list[str]*, *opsional*) : Prompt teks.

duration (*float*, default 10.0) : Durasi output dalam detik. Seharusnya sesuai dengan audio referensi.

audio (*torch.Tensor*, *opsional*) : 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*, defaultnya -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 latensi tambahan setelah konten target.

num_waveforms_per_prompt (*int*, defaultnya 1) : Jumlah waveform 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*) : Mengembalikan *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 opsional 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"`.

**Mengembalikan:**

[*~pipelines.AudioPipelineOutput*] dengan `.audios`.

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

Contoh:
```py
>>> 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[[diffusers.StableAudio3AudioToAudioPipeline.encode_duration]]

```python
encode_duration(duration: float, device: device, num_waveforms_per_prompt: int, batch_size: int)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L287)

**Parameter:**

duration : Durasi dalam detik, diterapkan ke setiap sampel dalam batch.

device : Perangkat target.

num_waveforms_per_prompt : Faktor ubin.

batch_size : Jumlah prompt.

**Mengembalikan:**

tensor `(batch * num_waveforms_per_prompt, output_dim)`.

Tanamkan nilai durasi ke dalam vektor kondisi global.

#### encode_prompt[[diffusers.StableAudio3AudioToAudioPipeline.encode_prompt]]

```python
encode_prompt(prompt: typing.Union[str, typing.List[str], NoneType], device: device, num_waveforms_per_prompt: int, prompt_embeds: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L220)

**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 kondisi 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.

**Mengembalikan:**

`(prompt_embeds, encoder_attention_mask)` keduanya di-tile menjadi `batch * num_waveforms_per_prompt`.

Enkode prompt teks menjadi tensor kondisioning cross-attention.

#### prepare_cross_attention[[diffusers.StableAudio3AudioToAudioPipeline.prepare_cross_attention]]

```python
prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L312)

**Mengembalikan:**

`(context, context_mask)` dengan bentuk `(batch, T_text + 1, dim)` dan `(batch, T_text + 1)`.

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

SA3 merutekan kondisioner `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[[diffusers.StableAudio3DurationEmbedder]]

#### diffusers.StableAudio3DurationEmbedder[[diffusers.StableAudio3DurationEmbedder]]

```python
diffusers.StableAudio3DurationEmbedder(output_dim: int = 768, fourier_dim: int = 256, min_val: float = 0.0, max_val: float = 384.0, min_freq: float = 0.5, max_freq: float = 10000.0)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L43)

**Parameter:**

output_dim (*int*, defaultnya 768) : Dimensi dari embedding output. Harus cocok dengan `global_cond_dim` dari DiT.

fourier_dim (*int*, defaultnya 256) : Dimensi fitur Fourier internal (harus genap).

min_val (*float*, default 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*, default 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[[diffusers.StableAudio3DurationEmbedder.forward]]

```python
forward(seconds: Tensor)
```

[Sumber](https://github.com/huggingface/diffusers/blob/main/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L90)

**Parameter:**

seconds (`torch.Tensor` dengan bentuk `(batch,)`) : Nilai durasi dalam detik.

**Mengembalikan:**

`torch.Tensor` dengan bentuk `(batch, output_dim)` — embedding durasi.