# Stable Audio

Stable Audio 由 Zach Evans 等人在 [Stable Audio Open](https://huggingface.co/papers/2407.14358) 中提出。它以文本提示作为输入，并预测相应的声音或音乐样本。

Stable Audio Open 可根据文本提示生成长度可变（最长 47 秒）的 44.1kHz 立体声音频。它由三个组件构成：一个将波形压缩为可管理序列长度的自编码器、一个用于文本条件化的基于 T5 的文本嵌入，以及一个在自编码器潜在空间中运行的基于 Transformer 的扩散（DiT）模型。

Stable Audio 是在一个包含约 48k 条音频录音的语料库上训练的，其中约 47k 条来自 Freesound，其余来自 Free Music Archive (FMA)。所有音频文件均采用 CC0、CC BY 或 CC Sampling+ 许可。该数据用于训练 autoencoder 和 DiT。

该论文的摘要如下：*开放生成模型对社区至关重要，它允许进行微调，并在发布新模型时作为基线。然而，目前大多数文本到音频模型都是私有的，艺术家和研究人员无法在其基础上进行构建。在此，我们描述了一个新的开放权重文本到音频模型的架构和训练过程，该模型使用 Creative Commons 数据进行训练。我们的评估表明，该模型在各项指标上的性能与最先进水平具有竞争力。值得注意的是，报告的 FDopenl3 结果（衡量生成内容的真实感）展示了其在 44.1kHz 下实现高质量立体声合成的潜力。*

此流水线由 [Yoach Lacombe](https://huggingface.co/ylacombe) 贡献。原始代码库可在 [Stability-AI/stable-audio-tools](https://github.com/Stability-AI/stable-audio-tools) 中找到。

## 提示

在构建提示时，请记住：

* 描述性的提示词输入效果最佳；请使用形容词来描述声音（例如“高质量”或“清晰”），并尽可能使提示词具有具体的上下文（例如，“带有快速节拍和合成器的旋律性电子乐”比“电子乐”效果更好）。
* 使用*负面提示词*可以显著提升生成音频的质量。请尝试使用负面提示词 "low quality, average quality"。

在推理过程中：

* 生成音频样本的_质量_可以通过`num_inference_steps`参数进行控制；步数越高，音频质量越好，但推理速度会相应降低。
* 可以一次性生成多个波形：将 `num_waveforms_per_prompt` 设置为大于 1 的值即可启用。系统会在生成的波形与提示文本之间进行自动评分，并据此将音频从最佳到最差进行排序。

## 量化

量化通过以较低精度的数据类型存储模型权重，有助于降低超大模型的内存需求。不过，量化对视频质量的影响会因视频模型的不同而有所差异。

请参阅 [量化](../../quantization/overview) 概述，以了解支持的量化后端以及如何选择支持您使用场景的量化后端。下面的示例演示了如何使用 bitsandbytes 加载用于推理的量化 [StableAudioPipeline](/docs/diffusers/main/zh/api/pipelines/stable_audio#diffusers.StableAudioPipeline)。

```py
import torch
from diffusers import BitsAndBytesConfig as DiffusersBitsAndBytesConfig, StableAudioDiTModel, StableAudioPipeline
from diffusers.utils import export_to_video
from transformers import BitsAndBytesConfig as BitsAndBytesConfig, T5EncoderModel

quant_config = BitsAndBytesConfig(load_in_8bit=True)
text_encoder_8bit = T5EncoderModel.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    subfolder="text_encoder",
    quantization_config=quant_config,
    dtype=torch.float16,
)

quant_config = DiffusersBitsAndBytesConfig(load_in_8bit=True)
transformer_8bit = StableAudioDiTModel.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    subfolder="transformer",
    quantization_config=quant_config,
    dtype=torch.float16,
)

pipeline = StableAudioPipeline.from_pretrained(
    "stabilityai/stable-audio-open-1.0",
    text_encoder=text_encoder_8bit,
    transformer=transformer_8bit,
    dtype=torch.float16,
    device_map="balanced",
)

prompt = "The sound of a hammer hitting a wooden surface."
negative_prompt = "Low quality."
audio = pipeline(
    prompt,
    negative_prompt=negative_prompt,
    num_inference_steps=200,
    audio_end_in_s=10.0,
    num_waveforms_per_prompt=3,
    generator=generator,
).audios

output = audio[0].T.float().cpu().numpy()
sf.write("hammer.wav", output, pipeline.vae.sampling_rate)
```

## StableAudioPipeline[[diffusers.StableAudioPipeline]]

#### diffusers.StableAudioPipeline[[diffusers.StableAudioPipeline]]

```python
diffusers.StableAudioPipeline(vae: AutoencoderOobleck, text_encoder: T5EncoderModel, projection_model: StableAudioProjectionModel, tokenizer: T5Tokenizer, transformer: StableAudioDiTModel, scheduler: EDMDPMSolverMultistepScheduler)
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio/pipeline_stable_audio.py#L78)

**参数：**

vae ([AutoencoderOobleck](/docs/diffusers/main/zh/api/models/autoencoder_oobleck#diffusers.AutoencoderOobleck))：变分自编码器（VAE）模型，用于将图像编码为潜在表示，并从潜在表示解码回图像。

text_encoder ([T5EncoderModel](https://huggingface.co/docs/transformers/main/en/model_doc/t5#transformers.T5EncoderModel))：冻结的文本编码器。StableAudio 使用 [T5](https://huggingface.co/docs/transformers/model_doc/t5#transformers.T5EncoderModel) 的编码器，具体为 [google-t5/t5-base](https://huggingface.co/google-t5/t5-base) 变体。

projection_model (`StableAudioProjectionModel`)：一个经过训练的模型，用于对文本编码器模型的隐藏状态以及起始和结束秒数进行线性投影。将编码器投影后的隐藏状态与条件秒数拼接，作为 Transformer 模型的输入。

tokenizer ([T5Tokenizer](https://huggingface.co/docs/transformers/main/en/model_doc/t5#transformers.T5Tokenizer))：用于对冻结的文本编码器进行文本分词的 Tokenizer。

transformer ([StableAudioDiTModel](/docs/diffusers/main/zh/api/models/stable_audio_transformer#diffusers.StableAudioDiTModel))：一个用于对编码后的音频潜变量进行去噪的 `StableAudioDiTModel`。

scheduler ([EDMDPMSolverMultistepScheduler](/docs/diffusers/main/zh/api/schedulers/edm_multistep_dpm_solver#diffusers.EDMDPMSolverMultistepScheduler))：一种调度器，需与 `transformer` 配合使用，以对编码后的音频潜变量进行去噪。

使用 StableAudio 进行文本到音频生成的 Pipeline。

该模型继承自 [DiffusionPipeline](/docs/diffusers/main/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

#### __调用__[[diffusers.StableAudioPipeline.__call__]]

```python
__call__(prompt: str | list[str] = None, audio_end_in_s: float | None = None, audio_start_in_s: float | None = 0.0, num_inference_steps: int = 100, guidance_scale: float = 7.0, negative_prompt: str | list[str] | None = None, num_waveforms_per_prompt: int | None = 1, eta: float = 0.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, initial_audio_waveforms: typing.Optional[torch.Tensor] = None, initial_audio_sampling_rate: typing.Optional[torch.Tensor] = None, prompt_embeds: typing.Optional[torch.Tensor] = None, negative_prompt_embeds: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, negative_attention_mask: typing.Optional[torch.LongTensor] = None, return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: int | None = 1, output_type: str | None = 'pt')
```

[源代码](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/stable_audio/pipeline_stable_audio.py#L462)

**参数：**

prompt (`str` 或 `list[str]`，*可选*)：用于引导音频生成的提示词或提示词列表。如果未定义，则需要传入 `prompt_embeds`。

audio_end_in_s (`float`，*可选*，默认值为 47.55)：音频结束索引，单位为秒。

audio_start_in_s (`float`，*可选*，默认值为 0)：音频起始索引，单位为秒。

num_inference_steps (`int`，*可选*，默认值为 100)：去噪步数。更多的去噪步数通常能带来更高质量的音频，但代价是推理速度变慢。

guidance_scale (`float`，*可选*，默认值为 7.0)：较高的 guidance scale 值会促使模型生成与文本 `prompt` 紧密关联的音频，但代价是音质降低。当 `guidance_scale > 1` 时，guidance scale 生效。

negative_prompt (`str` 或 `list[str]`，*可选*)：用于指导音频生成中不应包含的内容的提示词或提示词列表。如果未定义，则需要改为传入 `negative_prompt_embeds`。在未使用引导（`guidance_scale < 1`）时将被忽略。

num_waveforms_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的波形数量。

eta (`float`，*可选*，默认值为 0.0)：对应 [DDIM](https://huggingface.co/papers/2010.02502) 论文中的参数 eta (η)。仅适用于 [DDIMScheduler](/docs/diffusers/main/zh/api/schedulers/ddim#diffusers.DDIMScheduler)，在其他调度器中会被忽略。

generator (`torch.Generator` 或 `list[torch.Generator]`，*可选*)：用于使生成过程确定性的 [`torch.Generator`](https://pytorch.org/docs/stable/generated/torch.Generator.html)。

latents (`torch.Tensor`, *可选*) : 从高斯分布中采样的预生成噪声潜变量，用作音频生成的输入。可用于使用不同的提示词对同一生成过程进行微调。如果未提供，则使用提供的随机`generator`进行采样来生成潜变量张量。

initial_audio_waveforms (`torch.Tensor`, *可选*) : 用于生成过程的可选初始音频波形。其形状必须为 `(batch_size, num_channels, audio_length)` 或 `(batch_size, audio_length)`，其中 `batch_size` 对应传递给模型的提示数量。

initial_audio_sampling_rate (`int`, *可选*) : 如果提供了 `initial_audio_waveforms`，则为其采样率。必须与模型相同。

prompt_embeds (`torch.Tensor`, *可选*) : 由文本编码器模型预计算得到的文本嵌入。可用于轻松调整文本输入，*例如*提示词加权。如果未提供，则会根据 `prompt` 输入参数计算文本嵌入。

negative_prompt_embeds (`torch.Tensor`, *可选*) : 由文本编码器模型预计算的负向文本嵌入。可用于轻松调整文本输入，*例如* 提示词加权。如果未提供，negative_prompt_embeds 将根据 `negative_prompt` 输入参数计算得出。

attention_mask (`torch.LongTensor`, *可选*) : 预先计算好的注意力掩码，将应用于 `prompt_embeds`。如果未提供，则会根据 `prompt` 输入参数计算注意力掩码。

negative_attention_mask (`torch.LongTensor`, *可选*) : 预先计算好的注意力掩码，用于应用于 `negative_text_audio_duration_embeds`。

return_dict (`bool`，*可选*，默认为 `True`)：是否返回 [StableDiffusionPipelineOutput](/docs/diffusers/main/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 而不是普通元组。

callback (`Callable`，*可选*)：一个在推理过程中每隔 `callback_steps` 步调用一次的函数。该函数以以下参数被调用：`callback(step: int, timestep: int, latents: torch.Tensor)`。

callback_steps (`int`，*可选*，默认为 1)：`callback` 函数的调用频率。如果未指定，则回调函数会在每一步被调用。

output_type (`str`，*可选*，默认为 `"pt"`)：生成音频的输出格式。可选择 `"np"` 以返回 NumPy `np.ndarray`，或选择 `"pt"` 以返回 PyTorch `torch.Tensor` 对象。设置为 `"latent"` 可返回潜在扩散模型（LDM）的输出。

**返回：** [StableDiffusionPipelineOutput](/docs/diffusers/main/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput) 或 `tuple`

如果 `return_dict` 为 `True`，则返回 [StableDiffusionPipelineOutput](/docs/diffusers/main/zh/api/pipelines/stable_diffusion/img2img#diffusers.pipelines.stable_diffusion.StableDiffusionPipelineOutput)；否则返回一个 `tuple`，其中第一个元素是包含生成音频的列表。

用于生成的 pipeline 的调用函数。

示例：
```py
>>> import scipy
>>> import torch
>>> import soundfile as sf
>>> from diffusers import StableAudioPipeline

>>> repo_id = "stabilityai/stable-audio-open-1.0"
>>> pipe = StableAudioPipeline.from_pretrained(repo_id, torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")

>>> # define the prompts
>>> prompt = "The sound of a hammer hitting a wooden surface."
>>> negative_prompt = "Low quality."

>>> # set the seed for generator
>>> generator = torch.Generator("cuda").manual_seed(0)

>>> # run the generation
>>> audio = pipe(
...     prompt,
...     negative_prompt=negative_prompt,
...     num_inference_steps=200,
...     audio_end_in_s=10.0,
...     num_waveforms_per_prompt=3,
...     generator=generator,
... ).audios

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