# Stable Audio 3

Stable Audio 3(SA3)는 [Stability AI](https://stability.ai/)의 텍스트-오디오 모델로, 44.1 kHz에서 고품질 스테레오 오디오를 생성합니다. 두 개의 신호에 조건부화된 rectified-flow DiT를 사용합니다:

* **Text** — 동결된 T5Gemma 인코더로 인코딩된 후 크로스 어텐션을 통해 주입됩니다.
* **Duration** — [StableAudio3DurationEmbedder](/docs/diffusers/main/ko/api/pipelines/stable_audio_3#diffusers.StableAudio3DurationEmbedder)에 의해 임베드된 float(초) 값으로, 적응형 레이어 정규화(adaptive layer normalisation)의 전역 조건 벡터로 사용됩니다.

오디오는 SAME(Semantically-Aligned Music Encoder) 오토인코더인 [AutoencoderSAME](/docs/diffusers/main/ko/api/models/autoencoder_same#diffusers.AutoencoderSAME)에 의해 디코딩됩니다.

두 체크포인트 모두 [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler)를 log-SNR-uniform sigma 스케줄과 함께 사용하며, `stochastic_sampling`과 기본 스텝 수에서만 차이가 있습니다:

| 체크포인트 | `diffusion_objective` | `stochastic_sampling` | `num_inference_steps` |
|---|---|---|---|
| `stable-audio-3-medium-base` | `rectified_flow` | `False` (결정론적 오일러) | **100** (디스틸링되지 않음) |
| `stable-audio-3-medium` (디스틸드) | `rf_denoiser` | `True` (핑퐁 리노이즈) | **8** (8단계로 증류) |

올바른 스케줄러 설정은 각 변환된 체크포인트에 이미 포함되어 있으므로, `num_inference_steps`를 설정하지 않으면 기본값이 올바른 값으로 설정됩니다. 오버라이드할 때만 전달하세요.

원본 코드베이스: [Stability-AI/stable-audio-3](https://github.com/Stability-AI/stable-audio-3).

## 원본 체크포인트 변환

Stability AI의 체크포인트는 diffusers 형식으로 게시되지 않으므로 로컬에서 변환해야 합니다. 스크립트는 체크포인트의 `model_config.json`을 다운로드하고 `diffusion_objective`에서 스케줄러를 선택합니다:

```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`는 **게이트**된 저장소입니다. 변환 전에 액세스 권한이 있는 계정으로 `hf auth login`을 실행하지 않으면 401 오류로 다운로드가 실패합니다.

## 사용 예시

로컬 출력 디렉터리에서 변환된 체크포인트를 로드합니다([`soundfile`](https://pypi.org/project/soundfile/)은 `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)
```

파이프라인은 [AutoPipelineForText2Audio](/docs/diffusers/main/ko/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Audio)에도 등록되어 있으며, 체크포인트를 자동으로 `StableAudio3Pipeline`으로 해석합니다:

```py
from diffusers import AutoPipelineForText2Audio

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

> [!NOTE]
> 예제에서는 `stabilityai/stable-audio-3-medium`와 `stable-audio-3-medium-base`가 아직 diffusers 형식으로 게시되지 않았기 때문에(리포지토리 ID로 로드하면 404가 반환됨) 로컬 경로를 사용합니다. 게시가 완료되면 로컬 경로 대신 리포지토리 ID를 사용할 수 있습니다.

## 팁

* CPU 또는 MPS(Apple Silicon)에서는 `torch.float32`를 사용하세요. MPS에서 `torch.float16`을 사용하면 노이즈가 발생합니다.
* 디스틸된 모델(`stable-audio-3-medium`)은 **적대적 디스틸링**을 거쳤으며, 가이던스가 가중치에 이미 반영되어 있습니다. 해당 체크포인트의 경우 `guidance_scale=1.0`(기본값)을 유지하고 `negative_prompt`를 전달하지 마세요. 이 두 가지는 디스틸되지 않은 `stable-audio-3-medium-base` 체크포인트에서만 유용한 효과를 냅니다.
* `silence_padding_duration` (기본값 `0.0`)는 latent 시퀀스 끝에 무음 여백을 추가합니다. 모델이 해당 패딩을 마스킹하도록 학습되지 않았다면 `0.0`로 유지하세요. 그렇지 않으면 추가 프레임이 출력 에너지를 소모하여 결과가 조용해집니다.
* 프롬프트당 여러 클립을 생성하려면 `num_waveforms_per_prompt > 1`을 설정하세요.

## StableAudio3Pipeline[[diffusers.StableAudio3Pipeline]]

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

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

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

**매개변수:**

vae ([*AutoencoderSAME*]) : 오디오 latents를 인코딩 및 디코딩하는 데 사용되는 SAME autoencoder입니다.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : 고정된 T5Gemma 텍스트 인코더 (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : 텍스트 인코더용 토크나이저.

duration_embedder ([*StableAudio3DurationEmbedder*]) : `duration`을 초 단위로 각 DiT 블록의 AdaLN에 사용할 전역 조건 벡터로 매핑합니다.

transformer ([*StableAudio3DiTModel*]) : rectified-flow 속도 예측 DiT입니다.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : 반복적 노이즈 제거 루프에 사용되는 스케줄러입니다. 프로덕션(증류된) SA3 Medium 체크포인트는 정확히 8번의 ping-pong 스텝을 위해 *stochastic_sampling=True*를 사용하며, 증류되지 않은 베이스 체크포인트는 약 100번의 결정론적 Euler 스텝을 위해 *stochastic_sampling=False*를 사용합니다.

Stable Audio 3을 사용한 텍스트-오디오 생성을 위한 Pipeline입니다.

SA3는 ping-pong 샘플링을 사용하는 증류된 rectified-flow DiT를 사용합니다. 증류된 체크포인트에는 classifier-free guidance(`guidance_scale` / `negative_prompt`)가 필요하지 않으므로 `guidance_scale=1.0`(기본값)을 유지하면 되지만, 증류되지 않은 `stable-audio-3-medium-base` 체크포인트에는 의미가 있습니다.

이 모델은 *DiffusionPipeline*에서 상속됩니다. 모든 파이프라인에 구현된 일반 메서드에 대해서는 상위 클래스 문서를 확인하세요.

#### __호출__[[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')
```

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

**매개변수:**

prompt (*str* 또는 *list[str]*, *선택 사항*) : 텍스트 프롬프트입니다. 토큰화 및 인코딩을 건너뛰려면 대신 `prompt_embeds`를 전달하세요.

duration (*float*, 기본값 10.0) : 초 단위로 요청한 출력 길이.

num_inference_steps (*int*, *optional*) : 디노이징 단계 수. `None`(기본값)인 경우, 스케줄러의 *stochastic_sampling* 설정에서 단계 수가 선택됩니다: *True*일 때(디스틸된 핑퐁 스타일 체크포인트)는 **8**, *False*일 때(디스틸되지 않은 기본 체크포인트)는 **100**입니다. 값을 명시적으로 전달하여 오버라이드할 수 있습니다.

logsnr_min (*float*, 기본값 -6.2) : 노이즈 스케줄의 최소 log-SNR 값 — 스케줄의 고노이즈 시작점에 매핑됩니다.

logsnr_max (*float*, 기본값 2.0) : 노이즈 스케줄의 최대 log-SNR 값 — 스케줄의 저노이즈 끝단에 매핑됩니다.

silence_padding_duration (*float*, 기본값 0.0) : 대상 콘텐츠 외에 추가로 생성되는 잠재 컨텍스트의 초 단위입니다. 모델이 경계에서 여유를 가질 수 있도록 하며, 출력은 *duration*으로 잘립니다. 기본값은 0.0(비활성화)입니다. 모델이 이 패딩을 마스킹하도록 학습/증류된 경우에만 증가시키세요. 그렇지 않으면 추가 프레임이 출력 에너지를 소모합니다.

guidance_scale (*float*, 기본값 1.0) : Classifier-free guidance scale입니다. `1.0`은 guidance를 비활성화합니다(기본값이며, CFG가 가중치에 이미 반영된 distilled SA3 Medium checkpoint의 경우 유일한 합리적인 값입니다). `> 1.0` 값은 non-distilled `stable-audio-3-medium-base` checkpoint에서 의미가 있으며, 값이 높을수록 프롬프트를 더 밀접하게 따르지만 다양성은 감소합니다.

negative_prompt (*str* 또는 *list[str]*, *선택*) : `guidance_scale > 1.0`일 때 피해야 할 내용을 설명하는 프롬프트입니다. `guidance_scale > 1.0`이고 이 값과 *negative_prompt_embeds*가 모두 제공되지 않으면 기본값은 빈 문자열(무조건)입니다. `guidance_scale <= 1.0`인 경우 무시됩니다.

num_waveforms_per_prompt (*int*, 기본값 1) : 프롬프트당 생성할 웨이브폼의 수.

generator (*torch.Generator* 또는 *list[torch.Generator]*, *선택 사항*) : ping-pong 루프에서 결정론적 생성 및 재노이즈의 재현성을 위해 사용합니다.

latents (*torch.Tensor*, *선택 사항*) : 미리 생성된 시작 latents입니다. `None`인 경우 새로운 가우시안 텐서가 샘플링됩니다.

prompt_embeds (*torch.Tensor*, *선택*) : 사전 계산된 텍스트 임베딩 `(batch, seq_len, 768)`.

encoder_attention_mask (*torch.LongTensor*, *선택 사항*) : 사전 계산된 임베딩에 대한 불리언 마스크.

negative_prompt_embeds (*torch.Tensor*, *선택*) : *negative_prompt*의 대안으로, 미리 계산된 부정 텍스트 임베딩입니다.

negative_encoder_attention_mask (*torch.LongTensor*, *선택 사항*) : 사전 계산된 부정 임베딩에 대한 불리언 마스크.

return_dict (*bool*, 기본값 *True*) : *AudioPipelineOutput* 또는 일반 튜플을 반환합니다.

callback_on_step_end (*Callable*, *선택*) : *(self, step_idx, timestep, callback_kwargs)* 인수를 받아 각 디노이징 단계의 끝에서 호출됩니다. 여기서 *callback_kwargs*에는 *callback_on_step_end_tensor_inputs*에 나열된 텐서들이 포함됩니다. 루프의 나머지 부분에 사용할 (선택적으로 수정된) 텐서들을 담은 dict를 반환해야 합니다.

callback_on_step_end_tensor_inputs (*list[str]*, 기본값 *["latents"]*) : *callback_on_step_end*에 전달되는 텐서입니다. *self._callback_tensor_inputs*의 부분 집합이어야 합니다.

output_type (*str*, 기본값 `"pt"`) : PyTorch 텐서의 경우 `"pt"`, NumPy 배열의 경우 `"np"`, 디코딩을 건너뛰고 원시 latents를 반환하려면 `"latent"`.

**반환값:** [*~pipelines.AudioPipelineOutput*] 또는 *tuple*

`.audios`는 `(batch * num_waveforms_per_prompt, audio_channels, samples)` 형태의 텐서/배열입니다.

텍스트 프롬프트에서 오디오를 생성합니다.

예:
```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)
```

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

**매개변수:**

duration : 초 단위의 지속 시간으로, 배치의 모든 샘플에 적용됩니다.

device : 대상 장치.

num_waveforms_per_prompt : 타일 팩터.

batch_size : 프롬프트의 수.

**반환값:**

`(batch * num_waveforms_per_prompt, output_dim)` 텐서.

지속 시간 값을 전역 조건 벡터에 임베딩합니다.

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

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

**매개변수:**

prompt : 텍스트 프롬프트 또는 프롬프트 목록. `prompt_embeds`가 제공되면 무시됩니다.

device : 대상 장치.

num_waveforms_per_prompt : 프롬프트당 생성할 출력 웨이브폼의 수; 조건 텐서는 이에 따라 타일링됩니다.

prompt_embeds : 사전 계산된 텍스트 임베딩 `(batch, seq_len, hidden_size)`.

encoder_attention_mask : 사전 계산된 임베딩에 대한 Boolean 마스크 `(batch, seq_len)`; `1` = 실제 토큰, `0` = 패딩.

**반환값:**

`(prompt_embeds, encoder_attention_mask)` 모두 `batch * num_waveforms_per_prompt`으로 타일링됩니다.

텍스트 프롬프트를 크로스 어텐션 조건 텐서로 인코딩합니다.

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

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

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

**반환값:**

`(context, context_mask)`의 형태는 각각 `(batch, T_text + 1, dim)`과 `(batch, T_text + 1)`입니다.

duration 임베딩을 추가 토큰으로 추가하여 크로스 어텐션 컨텍스트를 구성합니다.

SA3은 `seconds_total` 조건자를 전역(AdaLN) 입력과 크로스 어텐션 컨텍스트(`cross_attention_cond_ids = ["prompt", "seconds_total"]`)*둘 다*에 라우팅합니다. 지속 시간 임베딩은 텍스트 토큰 뒤에 연결되고, 어텐션 마스크에는 유효한 항목 하나가 확장됩니다.

## StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]]

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

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

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

**매개변수:**

vae ([*AutoencoderSAME*]) : 오디오 latents를 인코딩 및 디코딩하는 데 사용되는 SAME autoencoder입니다.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : 고정된 T5Gemma 텍스트 인코더 (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : 텍스트 인코더용 토크나이저.

duration_embedder ([*StableAudio3DurationEmbedder*]) : `duration`을 초 단위로 각 DiT 블록의 AdaLN에 사용할 전역 조건 벡터로 매핑합니다.

transformer ([*StableAudio3DiTModel*]) : rectified-flow 속도 예측 DiT입니다.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : 반복적 노이즈 제거 루프에 사용되는 스케줄러입니다. 프로덕션(증류된) SA3 Medium 체크포인트는 정확히 8번의 ping-pong 스텝을 위해 *stochastic_sampling=True*를 사용하며, 증류되지 않은 베이스 체크포인트는 약 100번의 결정론적 Euler 스텝을 위해 *stochastic_sampling=False*를 사용합니다.

Stable Audio 3용 오디오 인페인팅 파이프라인.

Shares its text-to-audio logic with [*StableAudio3Pipeline*] (kept in sync via *# Copied from*). When `audio` and `mask` are provided, encodes the reference audio with the frozen SAME encoder and injects `masked_latent ∥ mask` as local-additive conditioning into each DiT block via the transformer's `local_add_cond` pathway (`to_local_embed`).

Call signature 확장(자세한 내용은 `__call__` 참조): audio (`(batch, channels, samples)` 형태의 *torch.Tensor*): `vae.config.sampling_rate` Hz의 기준 오디오 웨이브폼. mask (`(batch, 1, latent_length)` 형태의 *torch.Tensor*): latent space의 프레임별 바이너리 마스크. `1` = 원본 오디오 유지; `0` = inpaint할 영역.

#### __호출__[[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')
```

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

**매개변수:**

prompt (*str* 또는 *list[str]*, *선택 사항*) : 텍스트 프롬프트.

duration (*float*, 기본값 10.0) : 초 단위의 출력 길이. 참조 오디오와 일치해야 합니다.

audio (*torch.Tensor*, *선택 사항*) : `vae.config.sampling_rate` Hz에서 `(batch, channels, samples)` 형식의 참조 웨이브폼. 인페인팅에 필요합니다.

mask (*torch.Tensor*, *선택 사항*) : 0 = inpaint 영역, 1 = 보존을 나타내는 프레임별 latent-space mask `(batch, 1, L)`. `mask` 또는 `mask_start_seconds` / `mask_end_seconds` 중 하나는 제공되어야 합니다.

mask_start_seconds (*float* 또는 *list[float]*, *선택 사항*) : 초 단위로 inpaint 영역의 시작 시간입니다.

mask_end_seconds (*float* 또는 *list[float]*, *선택 사항*) : 인페인팅 영역의 종료 시간(들) (`mask_start_seconds`와 짝을 이루어야 함).

num_inference_steps (*int*, *optional*) : 디노이징 단계 수. `None`(기본값)인 경우, [*StableAudio3Pipeline*]과 일치하도록 스케줄러의 *stochastic_sampling* 설정에서 단계 수가 선택됩니다.

logsnr_min (*float*, 기본값 -6.2) : 노이즈 스케줄의 최소 log-SNR 값 — 스케줄의 고노이즈 시작점에 매핑됩니다.

logsnr_max (*float*, 기본값 2.0) : 노이즈 스케줄의 최대 log-SNR 값 — 스케줄의 저노이즈 끝단에 매핑됩니다.

silence_padding_duration (*float*, 기본값 0.0) : 대상 콘텐츠 이후의 추가 잠재 헤드룸.

num_waveforms_per_prompt (*int*, 기본값 1) : 프롬프트당 웨이브폼 수.

generator : 재현성을 위한 RNG.

latents : 사전 생성된 시작 노이즈 (`None` → 새로 샘플링).

prompt_embeds : 사전 계산된 텍스트 임베딩.

encoder_attention_mask : 사전 계산된 임베딩용 마스크.

return_dict (*bool*, 기본값 *True*) : *AudioPipelineOutput* 또는 튜플을 반환합니다.

callback_on_step_end (*Callable*, *선택 사항*) : 각 denoising 단계의 끝에서 *(self, step_idx, timestep, callback_kwargs)*와 함께 호출됩니다. 루프의 나머지 부분에 사용할 (선택적으로 수정된) 텐서를 dict로 반환해야 합니다.

callback_on_step_end_tensor_inputs (*list[str]*, 기본값 *["latents"]*) : *callback_on_step_end*에 전달되는 텐서입니다. *self._callback_tensor_inputs*의 부분 집합이어야 합니다.

output_type (*str*, 기본값 `"pt"`) : `"pt"` / `"np"` / `"latent"`.

**반환값:**

`.audios`를 가진 [*~pipelines.AudioPipelineOutput*]

텍스트 프롬프트와 참조에 조건부화된 인페인팅된 오디오를 생성합니다.

예:
```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)
```

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

**매개변수:**

duration : 초 단위의 지속 시간으로, 배치의 모든 샘플에 적용됩니다.

device : 대상 장치.

num_waveforms_per_prompt : 타일 팩터.

batch_size : 프롬프트의 수.

**반환값:**

`(batch * num_waveforms_per_prompt, output_dim)` 텐서.

지속 시간 값을 전역 조건 벡터에 임베딩합니다.

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

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

**매개변수:**

prompt : 텍스트 프롬프트 또는 프롬프트 목록. `prompt_embeds`가 제공되면 무시됩니다.

device : 대상 장치.

num_waveforms_per_prompt : 프롬프트당 생성할 출력 웨이브폼의 수; 조건 텐서는 이에 따라 타일링됩니다.

prompt_embeds : 사전 계산된 텍스트 임베딩 `(batch, seq_len, hidden_size)`.

encoder_attention_mask : 사전 계산된 임베딩에 대한 Boolean 마스크 `(batch, seq_len)`; `1` = 실제 토큰, `0` = 패딩.

**반환값:**

`(prompt_embeds, encoder_attention_mask)` 모두 `batch * num_waveforms_per_prompt`으로 타일링됩니다.

텍스트 프롬프트를 크로스 어텐션 조건 텐서로 인코딩합니다.

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

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

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

**반환값:**

`(context, context_mask)`의 형태는 각각 `(batch, T_text + 1, dim)`과 `(batch, T_text + 1)`입니다.

duration 임베딩을 추가 토큰으로 추가하여 크로스 어텐션 컨텍스트를 구성합니다.

SA3은 `seconds_total` 조건자를 전역(AdaLN) 입력과 크로스 어텐션 컨텍스트(`cross_attention_cond_ids = ["prompt", "seconds_total"]`)*둘 다*에 라우팅합니다. 지속 시간 임베딩은 텍스트 토큰 뒤에 연결되고, 어텐션 마스크에는 유효한 항목 하나가 확장됩니다.

## StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]]

참조 오디오 클립의 변형을 생성합니다. [StableAudio3InpaintPipeline](/docs/diffusers/main/ko/api/pipelines/stable_audio_3#diffusers.StableAudio3InpaintPipeline)의 프레임별 로컬 가산 조건화가 특정 프레임을 정확히 보존하는 것과 달리, 전체 참조 클립을 `init_noise_level`까지 노이즈화한 후 해당 지점부터 디노이즈합니다.

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

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

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

**매개변수:**

vae ([*AutoencoderSAME*]) : 오디오 latents를 인코딩 및 디코딩하는 데 사용되는 SAME autoencoder입니다.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : 고정된 T5Gemma 텍스트 인코더 (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : 텍스트 인코더용 토크나이저.

duration_embedder ([*StableAudio3DurationEmbedder*]) : `duration`을 초 단위로 각 DiT 블록의 AdaLN에 사용할 전역 조건 벡터로 매핑합니다.

transformer ([*StableAudio3DiTModel*]) : rectified-flow 속도 예측 DiT입니다.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : 반복적 노이즈 제거 루프에 사용되는 스케줄러입니다. 프로덕션(증류된) SA3 Medium 체크포인트는 정확히 8번의 ping-pong 스텝을 위해 *stochastic_sampling=True*를 사용하며, 증류되지 않은 베이스 체크포인트는 약 100번의 결정론적 Euler 스텝을 위해 *stochastic_sampling=False*를 사용합니다.

Stable Audio 3용 오디오-오디오 변형 파이프라인.

[*StableAudio3Pipeline*]와 텍스트-오디오 로직을 공유합니다(*# Copied from*를 통해 동기화 유지). 동결된 SAME 인코더로 참조 오디오를 인코딩하고, `init_noise_level`에 따라 새로운 노이즈와 혼합한 뒤, 해당 지점부터 디노이즈합니다. [*StableAudio3InpaintPipeline*]의 프레임별 로컬 가산 조건화와 달리, 전체 신호가 전역적으로 노이즈/디노이즈됩니다.

Call signature 확장(자세한 내용은 `__call__` 참조): audio (`(batch, channels, samples)` 형태의 *torch.Tensor*): `vae.config.sampling_rate` Hz의 기준 오디오 웨이브폼. init_noise_level (*float*): 디노이징 전에 기준 오디오에 혼합할 노이즈의 양. `1.0` = 전체 노이즈(텍스트-투-오디오와 동일); 더 낮은 값은 기준 오디오의 더 많은 부분을 유지합니다.

#### __호출__[[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')
```

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

**매개변수:**

prompt (*str* 또는 *list[str]*, *선택 사항*) : 텍스트 프롬프트.

duration (*float*, 기본값 10.0) : 초 단위의 출력 길이. 참조 오디오와 일치해야 합니다.

audio (*torch.Tensor*, *선택 사항*) : `vae.config.sampling_rate` Hz에서 `(batch, channels, samples)` 형태의 참조 웨이브폼. 필수입니다.

init_noise_level (*float*, 기본값 1.0) : 디노이징 전에 참조에 혼합되는 노이즈 레벨(`(0, 1]`): `x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise`. `1.0`은 참조를 완전히 폐기합니다([*StableAudio3Pipeline*]와 동일). 더 낮은 값은 전체 스텝 수를 실행하되 참조의 구조를 점차 더 많이 유지합니다.

num_inference_steps (*int*, *optional*) : 디노이징 단계 수. `None`(기본값)인 경우, [*StableAudio3Pipeline*]과 일치하도록 스케줄러의 *stochastic_sampling* 설정에서 단계 수가 선택됩니다.

logsnr_min (*float*, 기본값 -6.2) : 노이즈 스케줄의 최소 log-SNR 값 — 스케줄의 고노이즈 시작점에 매핑됩니다.

logsnr_max (*float*, 기본값 2.0) : 노이즈 스케줄의 최대 log-SNR 값 — 스케줄의 저노이즈 끝단에 매핑됩니다.

silence_padding_duration (*float*, 기본값 0.0) : 대상 콘텐츠 이후의 추가 잠재 헤드룸.

num_waveforms_per_prompt (*int*, 기본값 1) : 프롬프트당 웨이브폼 수.

generator : 재현성을 위한 RNG.

latents : 사전 생성된 시작 노이즈 (`None` → 새로 샘플링).

prompt_embeds : 사전 계산된 텍스트 임베딩.

encoder_attention_mask : 사전 계산된 임베딩용 마스크.

return_dict (*bool*, 기본값 *True*) : *AudioPipelineOutput* 또는 튜플을 반환합니다.

callback_on_step_end (*Callable*, *선택 사항*) : 각 denoising 단계의 끝에서 *(self, step_idx, timestep, callback_kwargs)*와 함께 호출됩니다. 루프의 나머지 부분에 사용할 (선택적으로 수정된) 텐서를 dict로 반환해야 합니다.

callback_on_step_end_tensor_inputs (*list[str]*, 기본값 *["latents"]*) : *callback_on_step_end*에 전달되는 텐서입니다. *self._callback_tensor_inputs*의 부분 집합이어야 합니다.

output_type (*str*, 기본값 `"pt"`) : `"pt"` / `"np"` / `"latent"`.

**반환값:**

`.audios`를 가진 [*~pipelines.AudioPipelineOutput*]

텍스트 프롬프트와 참조 웨이브폼에 조건부인 오디오 변형을 생성합니다.

예:
```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)
```

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

**매개변수:**

duration : 초 단위의 지속 시간으로, 배치의 모든 샘플에 적용됩니다.

device : 대상 장치.

num_waveforms_per_prompt : 타일 팩터.

batch_size : 프롬프트의 수.

**반환값:**

`(batch * num_waveforms_per_prompt, output_dim)` 텐서.

지속 시간 값을 전역 조건 벡터에 임베딩합니다.

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

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

**매개변수:**

prompt : 텍스트 프롬프트 또는 프롬프트 목록. `prompt_embeds`가 제공되면 무시됩니다.

device : 대상 장치.

num_waveforms_per_prompt : 프롬프트당 생성할 출력 웨이브폼의 수; 조건 텐서는 이에 따라 타일링됩니다.

prompt_embeds : 사전 계산된 텍스트 임베딩 `(batch, seq_len, hidden_size)`.

encoder_attention_mask : 사전 계산된 임베딩에 대한 Boolean 마스크 `(batch, seq_len)`; `1` = 실제 토큰, `0` = 패딩.

**반환값:**

`(prompt_embeds, encoder_attention_mask)` 모두 `batch * num_waveforms_per_prompt`으로 타일링됩니다.

텍스트 프롬프트를 크로스 어텐션 조건 텐서로 인코딩합니다.

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

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

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

**반환값:**

`(context, context_mask)`의 형태는 각각 `(batch, T_text + 1, dim)`과 `(batch, T_text + 1)`입니다.

duration 임베딩을 추가 토큰으로 추가하여 크로스 어텐션 컨텍스트를 구성합니다.

SA3은 `seconds_total` 조건자를 전역(AdaLN) 입력과 크로스 어텐션 컨텍스트(`cross_attention_cond_ids = ["prompt", "seconds_total"]`)*둘 다*에 라우팅합니다. 지속 시간 임베딩은 텍스트 토큰 뒤에 연결되고, 어텐션 마스크에는 유효한 항목 하나가 확장됩니다.

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

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

**매개변수:**

output_dim (*int*, 기본값 768) : 출력 임베딩의 차원. DiT의 `global_cond_dim`과 일치해야 합니다.

fourier_dim (*int*, 기본값 256) : 내부 Fourier feature 차원 (짝수여야 함).

min_val (*float*, 기본값 0.0) : 정규화 클램핑을 위한 최소 지속 시간 값.

max_val (*float*, 기본값 384.0) : 정규화 클램핑을 위한 최대 지속 시간 값입니다. 이 값을 초과하는 값은 클램핑됩니다. 384초는 `seconds_total` 컨디셔너의 프로덕션 SA3 Medium 상한값입니다.

min_freq (*float*, 기본값 0.5) : 지수 푸리에 기저의 최소 주파수.

max_freq (*float*, 기본값 10000.0) : 지수 푸리에 기저의 최대 주파수.

Stable Audio 3 DiT에서 `global_hidden_states` AdaLN 입력으로 사용되는 전역 조건 벡터에 시간 값(초 단위)을 임베딩합니다.

SA3 참조 구현의 `NumberConditioner(fourier_features_type="expo")`를 재현합니다.

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

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

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

**매개변수:**

seconds (`torch.Tensor`, shape `(batch,)`) : 초 단위 지속 시간 값.

**반환값:**

`torch.Tensor`, shape `(batch, output_dim)` — duration embeddings.