# Stable Audio 3

Stable Audio 3 (SA3) 是 [Stability AI](https://stability.ai/) 推出的文本生成音频模型，可生成 44.1 kHz 的高质量立体声音频。它使用基于两个信号条件的 rectified-flow DiT：

* **文本** — 由冻结的 T5Gemma 编码器进行编码，并通过交叉注意力机制注入。
* **Duration** — 一个浮点数（单位：秒），由 [StableAudio3DurationEmbedder](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_audio_3#diffusers.StableAudio3DurationEmbedder) 嵌入，并用作自适应层归一化的全局条件向量。

音频由 SAME（Semantically-Aligned Music Encoder）自编码器 [AutoencoderSAME](/docs/diffusers/v0.43.0/zh/api/models/autoencoder_same#diffusers.AutoencoderSAME) 进行解码。

两个检查点均使用 [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) 并采用对数 SNR 均匀 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 错误而失败。

## 使用示例

从其本地输出目录加载转换后的检查点（使用 `pip install soundfile` 安装 [`soundfile`](https://pypi.org/project/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 还注册在 [AutoPipelineForText2Audio](/docs/diffusers/v0.43.0/zh/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Audio) 中，它会自动将 checkpoint 解析为 `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 格式发布（通过 repo id 加载会返回 404）。一旦发布，即可使用 repo 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`）会在潜在序列的末尾添加一段静音余量。除非模型经过专门训练以对该填充进行掩码处理，否则请保持为 `0.0`，否则额外的帧会消耗输出能量，导致结果音量变低。
* 将 `num_waveforms_per_prompt > 1` 设置为大于 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/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L157)

**参数：**

vae ([*AutoencoderSAME*]) : 用于编码和解码音频潜变量的 SAME 自编码器。

text_encoder ([*~transformers.T5GemmaEncoderModel*])：冻结的 T5Gemma 文本编码器（`google/t5gemma-b-b-ul2`）。

tokenizer ([*~transformers.GemmaTokenizerFast*])：文本编码器的分词器。

duration_embedder ([*StableAudio3DurationEmbedder*]) : 将秒为单位的 `duration` 映射为每个 DiT 块中 AdaLN 的全局条件向量。

transformer ([*StableAudio3DiTModel*])：用于校正流速度预测的 DiT。

scheduler （*FlowMatchEulerDiscreteScheduler*）：用于迭代去噪循环的调度器。生产环境（蒸馏版）SA3 Medium 检查点使用 *stochastic_sampling=True*，恰好执行 8 步乒乓采样；非蒸馏的基础检查点使用 *stochastic_sampling=False*，执行约 100 步确定性 Euler 步骤。

使用 Stable Audio 3 进行文本到音频生成的 Pipeline。

SA3 采用蒸馏后的 rectified-flow DiT，并使用 ping-pong 采样。对于蒸馏检查点，无需使用无分类器引导（`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/v0.43.0/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**（蒸馏后的 ping-pong 风格检查点），当 *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 的缩放系数。`1.0` 会禁用 guidance（这是默认值，也是蒸馏版 SA3 Medium 检查点唯一合理的取值，因为其 CFG 已固化在权重中）。对于未蒸馏的 `stable-audio-3-medium-base` 检查点，`> 1.0` 的取值才有意义；数值越高，生成结果越严格地遵循提示词，但多样性会降低。

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]*，*可选*)：用于在乒乓循环中实现确定性生成和可复现的重新加噪。

latents (*torch.Tensor*, *可选*) : 预生成的起始潜变量。如果为 `None`，则采样一个新的 Gaussian 张量。

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* 中列出的张量。必须返回一个字典，其中包含用于循环剩余部分的（可选修改后的）张量。

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"`，或 `"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/v0.43.0/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/v0.43.0/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 : 用于预计算嵌入的布尔掩码 `(batch, seq_len)`；`1` = 真实 token，`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/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L313)

**返回值：**

形状为 `(batch, T_text + 1, dim)` 和 `(batch, T_text + 1)` 的 `(context, context_mask)`。

通过追加时长嵌入作为额外标记，构建交叉注意力上下文。

SA3 将 `seconds_total` 条件器路由到*两者*：全局（AdaLN）输入和交叉注意力上下文（`cross_attention_cond_ids = ["prompt", "seconds_total"]`）。时长嵌入拼接在文本 token 之后，注意力掩码扩展一个有效条目。

## 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/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L158)

**参数：**

vae ([*AutoencoderSAME*]) : 用于编码和解码音频潜变量的 SAME 自编码器。

text_encoder ([*~transformers.T5GemmaEncoderModel*])：冻结的 T5Gemma 文本编码器（`google/t5gemma-b-b-ul2`）。

tokenizer ([*~transformers.GemmaTokenizerFast*])：文本编码器的分词器。

duration_embedder ([*StableAudio3DurationEmbedder*]) : 将秒为单位的 `duration` 映射为每个 DiT 块中 AdaLN 的全局条件向量。

transformer ([*StableAudio3DiTModel*])：用于校正流速度预测的 DiT。

scheduler （*FlowMatchEulerDiscreteScheduler*）：用于迭代去噪循环的调度器。生产环境（蒸馏版）SA3 Medium 检查点使用 *stochastic_sampling=True*，恰好执行 8 步乒乓采样；非蒸馏的基础检查点使用 *stochastic_sampling=False*，执行约 100 步确定性 Euler 步骤。

Stable Audio 3 的音频修复（inpainting）流水线。

与 [*StableAudio3Pipeline*] 共享其文本到音频的逻辑（通过 *# Copied from* 保持同步）。当提供 `audio` 和 `mask` 时，使用冻结的 SAME 编码器对参考音频进行编码，并通过 transformer 的 `local_add_cond` 路径（`to_local_embed`）将 `masked_latent ∥ mask` 作为局部加性条件注入到每个 DiT 块中。

调用签名扩展（参见 `__call__`）：audio (*torch.Tensor*，形状为 `(batch, channels, samples)`)：采样率为 `vae.config.sampling_rate` Hz 的参考音频波形。mask (*torch.Tensor*，形状为 `(batch, 1, latent_length)`)：潜在空间中的逐帧二值掩码。`1` = 保留原始音频；`0` = 需要修复的区域。

#### __调用__[[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/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L455)

**参数：**

prompt （*str* 或 *list[str]*，*可选*）：文本提示。

duration (*float*，默认值为 10.0)：输出时长（以秒为单位）。应与参考音频的时长一致。

audio (*torch.Tensor*, *可选*) : 参考波形 `(batch, channels, samples)`，采样率为 `vae.config.sampling_rate` Hz。执行修复（inpainting）时必填。

mask (*torch.Tensor*, *可选*) : 逐帧潜在空间掩码 `(batch, 1, L)`，其中 0 表示重绘区域，1 表示保留区域。必须提供 `mask` 或 `mask_start_seconds` / `mask_end_seconds` 之一。

mask_start_seconds (*float* 或 *list[float]*，*可选*)：重绘区域在秒为单位的起始时间。

mask_end_seconds (*float* 或 *list[float]*，*可选*)：重绘区域的结束时间（必须与 `mask_start_seconds` 配对使用）。

num_inference_steps (*int*, *optional*) : 去噪步数。当为 `None`（默认值）时，步数将从调度器的 *stochastic_sampling* 配置中选取，与 [*StableAudio3Pipeline*] 保持一致。

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 : 用于可复现性的随机数生成器。

latents : 预生成的起始噪声（`None` → 重新采样）。

prompt_embeds : 预计算文本嵌入。

encoder_attention_mask : 预计算嵌入的掩码。

return_dict (*bool*，默认为 *True*)：返回 *AudioPipelineOutput* 或元组。

callback_on_step_end (*Callable*，*可选*)：在每个去噪步骤结束时调用，参数为 *(self, step_idx, timestep, callback_kwargs)*。必须返回一个字典，其中包含用于循环剩余部分的（可选修改后的）张量。

callback_on_step_end_tensor_inputs (*list[str]*，默认为 *["latents"]*)：传递给 *callback_on_step_end* 的张量。必须是 *self._callback_tensor_inputs* 的子集。

output_type (*str*，默认为 `"pt"`) : `"pt"` / `"np"` / `"latent"`。

**返回值：**

[*~pipelines.AudioPipelineOutput*] 以及 `.audios`。

根据文本提示和参考音频生成修复后的音频。

示例：
```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/v0.43.0/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/v0.43.0/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 : 用于预计算嵌入的布尔掩码 `(batch, seq_len)`；`1` = 真实 token，`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/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L315)

**返回值：**

形状为 `(batch, T_text + 1, dim)` 和 `(batch, T_text + 1)` 的 `(context, context_mask)`。

通过追加时长嵌入作为额外标记，构建交叉注意力上下文。

SA3 将 `seconds_total` 条件器路由到*两者*：全局（AdaLN）输入和交叉注意力上下文（`cross_attention_cond_ids = ["prompt", "seconds_total"]`）。时长嵌入拼接在文本 token 之后，注意力掩码扩展一个有效条目。

## StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]]

生成参考音频片段的变体：整个参考音频被加噪至 `init_noise_level`，然后从该状态进行去噪；这与 [StableAudio3InpaintPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/stable_audio_3#diffusers.StableAudio3InpaintPipeline) 的逐帧局部加性条件不同，后者会精确保留特定帧。

#### 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/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L154)

**参数：**

vae ([*AutoencoderSAME*]) : 用于编码和解码音频潜变量的 SAME 自编码器。

text_encoder ([*~transformers.T5GemmaEncoderModel*])：冻结的 T5Gemma 文本编码器（`google/t5gemma-b-b-ul2`）。

tokenizer ([*~transformers.GemmaTokenizerFast*])：文本编码器的分词器。

duration_embedder ([*StableAudio3DurationEmbedder*]) : 将秒为单位的 `duration` 映射为每个 DiT 块中 AdaLN 的全局条件向量。

transformer ([*StableAudio3DiTModel*])：用于校正流速度预测的 DiT。

scheduler （*FlowMatchEulerDiscreteScheduler*）：用于迭代去噪循环的调度器。生产环境（蒸馏版）SA3 Medium 检查点使用 *stochastic_sampling=True*，恰好执行 8 步乒乓采样；非蒸馏的基础检查点使用 *stochastic_sampling=False*，执行约 100 步确定性 Euler 步骤。

Stable Audio 3 的音频到音频变体流水线。

与 [*StableAudio3Pipeline*] 共享其文本到音频的逻辑（通过 *# Copied from* 保持同步）。使用冻结的 SAME 编码器对参考音频进行编码，根据 `init_noise_level` 将其与新的噪声混合，然后从该状态开始去噪——整个信号是全局加噪/去噪的，这与 [*StableAudio3InpaintPipeline*] 的逐帧局部加性条件不同。

调用签名扩展（参见 `__call__`）：audio (*torch.Tensor*，形状为 `(batch, channels, samples)`)：采样率为 `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/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L424)

**参数：**

prompt （*str* 或 *list[str]*，*可选*）：文本提示。

duration (*float*，默认值为 10.0)：输出时长（以秒为单位）。应与参考音频的时长一致。

audio (*torch.Tensor*, *可选*) : 参考波形 `(batch, channels, samples)`，采样率为 `vae.config.sampling_rate` Hz。必填。

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`（默认值）时，步数将从调度器的 *stochastic_sampling* 配置中选取，与 [*StableAudio3Pipeline*] 保持一致。

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 : 用于可复现性的随机数生成器。

latents : 预生成的起始噪声（`None` → 重新采样）。

prompt_embeds : 预计算文本嵌入。

encoder_attention_mask : 预计算嵌入的掩码。

return_dict (*bool*，默认为 *True*)：返回 *AudioPipelineOutput* 或元组。

callback_on_step_end (*Callable*，*可选*)：在每个去噪步骤结束时调用，参数为 *(self, step_idx, timestep, callback_kwargs)*。必须返回一个字典，其中包含用于循环剩余部分的（可选修改后的）张量。

callback_on_step_end_tensor_inputs (*list[str]*，默认为 *["latents"]*)：传递给 *callback_on_step_end* 的张量。必须是 *self._callback_tensor_inputs* 的子集。

output_type (*str*，默认为 `"pt"`) : `"pt"` / `"np"` / `"latent"`。

**返回值：**

[*~pipelines.AudioPipelineOutput*] 以及 `.audios`。

根据文本提示和参考波形生成音频变体。

示例：
```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/v0.43.0/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/v0.43.0/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 : 用于预计算嵌入的布尔掩码 `(batch, seq_len)`；`1` = 真实 token，`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/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L312)

**返回值：**

形状为 `(batch, T_text + 1, dim)` 和 `(batch, T_text + 1)` 的 `(context, context_mask)`。

通过追加时长嵌入作为额外标记，构建交叉注意力上下文。

SA3 将 `seconds_total` 条件器路由到*两者*：全局（AdaLN）输入和交叉注意力上下文（`cross_attention_cond_ids = ["prompt", "seconds_total"]`）。时长嵌入拼接在文本 token 之后，注意力掩码扩展一个有效条目。

## 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/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L43)

**参数：**

output_dim (*int*，默认值为 768)：输出嵌入的维度。必须与 DiT 的 `global_cond_dim` 相匹配。

fourier_dim (*int*，默认为 256)：内部傅里叶特征维度（必须为偶数）。

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/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L90)

**参数：**

seconds (`torch.Tensor`，形状为 `(batch,)`)：以秒为时长的值。

**返回值：**

形状为 `(batch, output_dim)` 的 `torch.Tensor` — 持续时间嵌入。