# Stable Audio 3

Stable Audio 3 (SA3) es un modelo de texto a audio de [Stability AI](https://stability.ai/) que genera audio estéreo de alta calidad a 44,1 kHz. Utiliza un DiT de flujo rectificado condicionado por dos señales:

* **Texto** — codificado por un codificador T5Gemma congelado e inyectado mediante atención cruzada.
* **Duración** — un float (segundos) incrustado por [StableAudio3DurationEmbedder](/docs/diffusers/v0.43.0/es/api/pipelines/stable_audio_3#diffusers.StableAudio3DurationEmbedder) y utilizado como vector de condicionamiento global para la normalización de capas adaptativa.

El audio se decodifica mediante el autoencoder SAME (Semantically-Aligned Music Encoder), [AutoencoderSAME](/docs/diffusers/v0.43.0/es/api/models/autoencoder_same#diffusers.AutoencoderSAME).

Ambos puntos de control utilizan [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/es/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) con una programación de sigma uniforme en log-SNR, y solo difieren en `stochastic_sampling` y en el número de pasos predeterminado:

| Checkpoint | `diffusion_objective` | `stochastic_sampling` | `num_inference_steps` |
|---|---|---|---|
| `stable-audio-3-medium-base` | `rectified_flow` | `False` (Euler determinista) | **100** (no destilado) |
| `stable-audio-3-medium` (destilado) | `rf_denoiser` | `True` (ruido de ping-pong) | **8** (destilado en 8 pasos) |

La configuración correcta del programador está integrada en cada punto de control convertido, por lo que `num_inference_steps` toma el valor adecuado por defecto si no se establece. Solo pásalo para sobrescribirlo.

Código base original: [Stability-AI/stable-audio-3](https://github.com/Stability-AI/stable-audio-3).

## Conversión de puntos de control originales

Los puntos de control de Stability AI no se publican en formato de diffusers, por lo que conviértelos localmente. El script descarga el `model_config.json` del punto de control y selecciona el programador a partir de su `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` es un repositorio **con acceso restringido**. Ejecuta `hf auth login` con una cuenta que tenga acceso antes de convertirlo; de lo contrario, la descarga fallará con un error 401.

## Ejemplo de uso

Cargue el punto de control convertido desde su directorio de salida local (instale [`soundfile`](https://pypi.org/project/soundfile/) con `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)
```

El pipeline también está registrado con [AutoPipelineForText2Audio](/docs/diffusers/v0.43.0/es/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Audio), que resuelve el checkpoint a `StableAudio3Pipeline` automáticamente:

```py
from diffusers import AutoPipelineForText2Audio

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

> [!NOTE]
> Los ejemplos utilizan una ruta local porque `stabilityai/stable-audio-3-medium` y `stable-audio-3-medium-base` aún no se han publicado en formato diffusers (cargar por repo id devuelve un 404). Una vez publicados, el repo id funciona en lugar de la ruta local.

## Consejos

* Usa `torch.float32` en CPU o MPS (Apple Silicon) — `torch.float16` en MPS produce ruido.
* El modelo destilado (`stable-audio-3-medium`) es **destilado adversarialmente**: la guía está integrada en los pesos. Deja `guidance_scale=1.0` (el valor predeterminado) y no pases un `negative_prompt` para ese punto de control; ambos solo son útiles para el punto de control no destilado `stable-audio-3-medium-base`.
* `silence_padding_duration` (valor predeterminado `0.0`) añade un margen de silencio al final de la secuencia latente. Déjalo en `0.0` a menos que el modelo esté entrenado para enmascarar ese relleno; de lo contrario, los fotogramas adicionales drenan la energía de la salida y el resultado se vuelve más silencioso.
* Establezca `num_waveforms_per_prompt > 1` para generar varios clips por 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)
```

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

**Parámetros:**

vae ([*AutoencoderSAME*]) : autoencoder SAME utilizado para codificar y decodificar latentes de audio.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : Codificador de texto T5Gemma congelado (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : Tokenizador para el codificador de texto.

duration_embedder ([*StableAudio3DurationEmbedder*]) : Mapea `duration` en segundos a un vector de condicionamiento global para AdaLN en cada bloque DiT.

transformer ([*StableAudio3DiTModel*]) : El DiT de predicción de velocidad de flujo rectificado.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : Programador para el bucle iterativo de desruido. El punto de control SA3 Medium de producción (destilado) utiliza *stochastic_sampling=True* para exactamente 8 pasos de ping-pong; el punto de control base no destilado utiliza *stochastic_sampling=False* para ~100 pasos deterministas de Euler.

Pipeline para la generación de audio a partir de texto usando Stable Audio 3.

SA3 utiliza un DiT de flujo rectificado destilado con muestreo ping-pong. La guía sin clasificador (`guidance_scale` / `negative_prompt`) no es necesaria para el checkpoint destilado (deja `guidance_scale=1.0`, el valor predeterminado), pero sí tiene sentido para el checkpoint no destilado `stable-audio-3-medium-base`.

Este modelo hereda de [*DiffusionPipeline*]. Consulta la documentación de la superclase para los métodos genéricos implementados en todas las tuberías.

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

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

**Parámetros:**

prompt (*str* o *list[str]*, *opcional*) : Prompt(s) de texto. Pasa `prompt_embeds` en su lugar para omitir la tokenización y la codificación.

duration (*float*, por defecto 10.0) : Duración de salida solicitada en segundos.

num_inference_steps (*int*, *optional*) : Número de pasos de desruido. Cuando es `None` (valor predeterminado), la cantidad de pasos se elige a partir de la configuración *stochastic_sampling* del programador: **8** cuando es *True* (el punto de control destilado de estilo ping-pong) y **100** cuando es *False* (el punto de control base no destilado). Pase un valor explícito para sobrescribirlo.

logsnr_min (*float*, valor predeterminado: -6.2) : Valor mínimo de log-SNR para el plan de ruido; corresponde al inicio de alto ruido del plan.

logsnr_max (*float*, valor predeterminado 2.0) : Valor máximo de log-SNR para el plan de ruido; corresponde al extremo de bajo ruido del plan.

silence_padding_duration (*float*, valor predeterminado 0.0) : Segundos adicionales de contexto latente generados más allá del contenido objetivo, lo que proporciona margen al modelo en el límite; la salida se recorta hasta *duration*. El valor predeterminado es 0.0 (deshabilitado). Auméntelo solo si el modelo está entrenado o destilado para enmascarar este relleno; de lo contrario, los fotogramas adicionales agotan la energía de la salida.

guidance_scale (*float*, valor predeterminado 1.0) : Escala de guía libre de clasificador. `1.0` desactiva la guía (el valor predeterminado y el único valor razonable para el punto de control destilado SA3 Medium, cuya CFG está integrada en los pesos). Los valores `> 1.0` son significativos para el punto de control no destilado `stable-audio-3-medium-base`; los valores más altos siguen el prompt con mayor fidelidad a costa de la diversidad.

negative_prompt (*str* o *list[str]*, *opcional*) : Prompt(s) que describen desde qué se debe alejar la generación cuando `guidance_scale > 1.0`. El valor predeterminado es una cadena vacía (no condicional) cuando `guidance_scale > 1.0` y no se proporciona ni este parámetro ni *negative_prompt_embeds*. Se ignora cuando `guidance_scale <= 1.0`.

num_waveforms_per_prompt (*int*, por defecto 1) : Número de formas de onda a generar por indicación.

generator (*torch.Generator* o *list[torch.Generator]*, *opcional*) : Para la generación determinista y el re-ruido reproducible en el bucle ping-pong.

latents (*torch.Tensor*, *opcional*) : Latentes iniciales pregenerados. Si es `None`, se muestrea un tensor gaussiano nuevo.

prompt_embeds (*torch.Tensor*, *opcional*) : Embeddings de texto precalculados `(batch, seq_len, 768)`.

encoder_attention_mask (*torch.LongTensor*, *opcional*) : Máscara booleana para las incrustaciones precalculadas.

negative_prompt_embeds (*torch.Tensor*, *opcional*) : Embeddings de texto negativos precalculados, como alternativa a *negative_prompt*.

negative_encoder_attention_mask (*torch.LongTensor*, *opcional*) : Máscara booleana para los embeddings negativos precalculados.

return_dict (*bool*, por defecto *True*) : Devuelve un *AudioPipelineOutput* o una tupla simple.

callback_on_step_end (*Callable*, *opcional*) : Se llama al final de cada paso de desruido con *(self, step_idx, timestep, callback_kwargs)*, donde *callback_kwargs* contiene los tensores enumerados en *callback_on_step_end_tensor_inputs*. Debe devolver un diccionario con los tensores (posiblemente modificados) que se usarán para el resto del bucle.

callback_on_step_end_tensor_inputs (*list[str]*, por defecto *["latents"]*) : Los tensores pasados a *callback_on_step_end*. Debe ser un subconjunto de *self._callback_tensor_inputs*.

output_type (*str*, por defecto `"pt"`) : `"pt"` para un tensor de PyTorch, `"np"` para un array de NumPy, o `"latent"` para omitir la decodificación y devolver los latentes crudos.

**Devuelve:** [*~pipelines.AudioPipelineOutput*] o *tuple*

`.audios` es un tensor / array de forma `(batch * num_waveforms_per_prompt, audio_channels, samples)`.

Genera audio a partir de un prompt de texto.

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

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

**Parámetros:**

duration : Duración en segundos, aplicada a cada muestra del lote.

device : Dispositivo de destino.

num_waveforms_per_prompt : Factor de teselación.

batch_size : Número de indicaciones.

**Devuelve:**

tensor `(batch * num_waveforms_per_prompt, output_dim)`.

Incorpore el valor de duración en el vector de condicionamiento 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)
```

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

**Parámetros:**

prompt : Prompt de texto o lista de prompts. Se ignora cuando se proporciona `prompt_embeds`.

device : Dispositivo de destino.

num_waveforms_per_prompt : Número de formas de onda de salida a generar por indicación; los tensores de condicionamiento se replican en consecuencia.

prompt_embeds : Embeddings de texto precalculados `(batch, seq_len, hidden_size)`.

encoder_attention_mask : Máscara booleana `(batch, seq_len)` para incrustaciones precalculadas; `1` = token real, `0` = relleno.

**Devuelve:**

`(prompt_embeds, encoder_attention_mask)` ambos con forma `batch * num_waveforms_per_prompt`.

Codifica los prompts de texto en tensores de condicionamiento para la atención cruzada.

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

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

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

**Devuelve:**

`(context, context_mask)` de formas `(batch, T_text + 1, dim)` y `(batch, T_text + 1)`.

Construya el contexto de atención cruzada añadiendo el embedding de duración como un token adicional.

SA3 enruta el condicionador `seconds_total` a *ambos*, la entrada global (AdaLN) y el contexto de atención cruzada (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). El embedding de duración se concatena después de los tokens de texto y la máscara de atención se extiende con una entrada válida.

## StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]]

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

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

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

**Parámetros:**

vae ([*AutoencoderSAME*]) : autoencoder SAME utilizado para codificar y decodificar latentes de audio.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : Codificador de texto T5Gemma congelado (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : Tokenizador para el codificador de texto.

duration_embedder ([*StableAudio3DurationEmbedder*]) : Mapea `duration` en segundos a un vector de condicionamiento global para AdaLN en cada bloque DiT.

transformer ([*StableAudio3DiTModel*]) : El DiT de predicción de velocidad de flujo rectificado.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : Programador para el bucle iterativo de desruido. El punto de control SA3 Medium de producción (destilado) utiliza *stochastic_sampling=True* para exactamente 8 pasos de ping-pong; el punto de control base no destilado utiliza *stochastic_sampling=False* para ~100 pasos deterministas de Euler.

Pipeline de inpainting de audio para Stable Audio 3.

Comparte su lógica de texto a audio con [*StableAudio3Pipeline*] (mantenida en sincronía mediante *# Copied from*). Cuando se proporcionan `audio` y `mask`, codifica el audio de referencia con el codificador SAME congelado e inyecta `masked_latent ∥ mask` como condicionamiento local aditivo en cada bloque DiT a través de la vía `local_add_cond` del transformer (`to_local_embed`).

Extensión de la firma de llamada (ver `__call__`): audio (*torch.Tensor* de forma `(batch, channels, samples)`): Forma de onda de audio de referencia a `vae.config.sampling_rate` Hz. mask (*torch.Tensor* de forma `(batch, 1, latent_length)`): Máscara binaria por marco en el espacio latente. `1` = conservar el audio original; `0` = región que se rellenará.

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

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

**Parámetros:**

prompt (*str* o *list[str]*, *opcional*) : Prompt(s) de texto.

duration (*float*, valor predeterminado 10.0) : Duración de salida en segundos. Debe coincidir con el audio de referencia.

audio (*torch.Tensor*, *opcional*) : Forma de onda de referencia `(batch, channels, samples)` a `vae.config.sampling_rate` Hz. Obligatorio para el inpainting.

mask (*torch.Tensor*, *opcional*) : Máscara del espacio latente por fotograma `(batch, 1, L)` donde 0 = región de inpainting, 1 = conservar. Debe proporcionarse `mask` o `mask_start_seconds` / `mask_end_seconds`.

mask_start_seconds (*float* o *list[float]*, *opcional*) : Tiempo(s) de inicio de la región de inpaint en segundos.

mask_end_seconds (*float* o *list[float]*, *opcional*) : Tiempo(s) final(es) de la región de inpaint (debe emparejarse con `mask_start_seconds`).

num_inference_steps (*int*, *optional*) : Número de pasos de desruido. Cuando es `None` (valor predeterminado), la cantidad de pasos se elige a partir de la configuración *stochastic_sampling* del programador, coincidiendo con [*StableAudio3Pipeline*].

logsnr_min (*float*, valor predeterminado: -6.2) : Valor mínimo de log-SNR para el plan de ruido; corresponde al inicio de alto ruido del plan.

logsnr_max (*float*, valor predeterminado 2.0) : Valor máximo de log-SNR para el plan de ruido; corresponde al extremo de bajo ruido del plan.

silence_padding_duration (*float*, valor predeterminado 0.0) : Margen latente adicional después del contenido objetivo.

num_waveforms_per_prompt (*int*, valor predeterminado 1) : Formas de onda por indicación.

generator : RNG para la reproducibilidad.

latents : Ruido inicial pregenerado (`None` → muestrear uno nuevo).

prompt_embeds : Embeddings de texto precalculados.

encoder_attention_mask : Máscara para las incrustaciones precalculadas.

return_dict (*bool*, por defecto *True*) : Devuelve *AudioPipelineOutput* o una tupla.

callback_on_step_end (*Callable*, *opcional*) : Se llama al final de cada paso de desruido con *(self, step_idx, timestep, callback_kwargs)*. Debe devolver un diccionario con los tensores (posiblemente modificados) que se usarán para el resto del bucle.

callback_on_step_end_tensor_inputs (*list[str]*, por defecto *["latents"]*) : Los tensores pasados a *callback_on_step_end*. Debe ser un subconjunto de *self._callback_tensor_inputs*.

output_type (*str*, por defecto `"pt"`) : `"pt"` / `"np"` / `"latent"`.

**Devuelve:**

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

Genera audio reconstruido condicionado por un prompt de texto y una referencia.

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

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

**Parámetros:**

duration : Duración en segundos, aplicada a cada muestra del lote.

device : Dispositivo de destino.

num_waveforms_per_prompt : Factor de teselación.

batch_size : Número de indicaciones.

**Devuelve:**

tensor `(batch * num_waveforms_per_prompt, output_dim)`.

Incorpore el valor de duración en el vector de condicionamiento 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)
```

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

**Parámetros:**

prompt : Prompt de texto o lista de prompts. Se ignora cuando se proporciona `prompt_embeds`.

device : Dispositivo de destino.

num_waveforms_per_prompt : Número de formas de onda de salida a generar por indicación; los tensores de condicionamiento se replican en consecuencia.

prompt_embeds : Embeddings de texto precalculados `(batch, seq_len, hidden_size)`.

encoder_attention_mask : Máscara booleana `(batch, seq_len)` para incrustaciones precalculadas; `1` = token real, `0` = relleno.

**Devuelve:**

`(prompt_embeds, encoder_attention_mask)` ambos con forma `batch * num_waveforms_per_prompt`.

Codifica los prompts de texto en tensores de condicionamiento para la atención cruzada.

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

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

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

**Devuelve:**

`(context, context_mask)` de formas `(batch, T_text + 1, dim)` y `(batch, T_text + 1)`.

Construya el contexto de atención cruzada añadiendo el embedding de duración como un token adicional.

SA3 enruta el condicionador `seconds_total` a *ambos*, la entrada global (AdaLN) y el contexto de atención cruzada (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). El embedding de duración se concatena después de los tokens de texto y la máscara de atención se extiende con una entrada válida.

## StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]]

Genera una variación de un clip de audio de referencia: toda la referencia se ruidifica hasta `init_noise_level` y se desruidifica desde ahí, a diferencia de la condición local aditiva por fotograma de [StableAudio3InpaintPipeline](/docs/diffusers/v0.43.0/es/api/pipelines/stable_audio_3#diffusers.StableAudio3InpaintPipeline), que preserva ciertos fotogramas de forma exacta.

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

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

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

**Parámetros:**

vae ([*AutoencoderSAME*]) : autoencoder SAME utilizado para codificar y decodificar latentes de audio.

text_encoder ([*~transformers.T5GemmaEncoderModel*]) : Codificador de texto T5Gemma congelado (`google/t5gemma-b-b-ul2`).

tokenizer ([*~transformers.GemmaTokenizerFast*]) : Tokenizador para el codificador de texto.

duration_embedder ([*StableAudio3DurationEmbedder*]) : Mapea `duration` en segundos a un vector de condicionamiento global para AdaLN en cada bloque DiT.

transformer ([*StableAudio3DiTModel*]) : El DiT de predicción de velocidad de flujo rectificado.

scheduler ([*FlowMatchEulerDiscreteScheduler*]) : Programador para el bucle iterativo de desruido. El punto de control SA3 Medium de producción (destilado) utiliza *stochastic_sampling=True* para exactamente 8 pasos de ping-pong; el punto de control base no destilado utiliza *stochastic_sampling=False* para ~100 pasos deterministas de Euler.

Pipeline de variación de audio a audio para Stable Audio 3.

Comparte su lógica de texto a audio con [*StableAudio3Pipeline*] (mantenida sincronizada mediante *# Copied from*). Codifica el audio de referencia con el codificador SAME congelado, lo mezcla con ruido nuevo según `init_noise_level` y desruidiza a partir de ahí: toda la señal se ruidiza/desruidiza de forma global, a diferencia de la condición local aditiva por marco de [*StableAudio3InpaintPipeline*].

Extensión de la firma de llamada (ver `__call__`): audio (*torch.Tensor* de forma `(batch, channels, samples)`): Forma de onda de audio de referencia a `vae.config.sampling_rate` Hz. init_noise_level (*float*): Cantidad de ruido que se mezcla en la referencia antes de la eliminación de ruido. `1.0` = ruido completo (equivalente a texto-audio); los valores más bajos conservan más de la referencia.

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

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

**Parámetros:**

prompt (*str* o *list[str]*, *opcional*) : Prompt(s) de texto.

duration (*float*, valor predeterminado 10.0) : Duración de salida en segundos. Debe coincidir con el audio de referencia.

audio (*torch.Tensor*, *opcional*) : Forma de onda de referencia `(batch, channels, samples)` a `vae.config.sampling_rate` Hz. Obligatorio.

init_noise_level (*float*, valor predeterminado 1.0) : Nivel de ruido (en `(0, 1]`) que se mezcla en la referencia antes del desruido: `x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise`. `1.0` descarta por completo la referencia (equivalente a [*StableAudio3Pipeline*]); los valores más bajos conservan progresivamente más de la estructura de la referencia, mientras se ejecuta el número completo de pasos.

num_inference_steps (*int*, *optional*) : Número de pasos de desruido. Cuando es `None` (valor predeterminado), la cantidad de pasos se elige a partir de la configuración *stochastic_sampling* del programador, coincidiendo con [*StableAudio3Pipeline*].

logsnr_min (*float*, valor predeterminado: -6.2) : Valor mínimo de log-SNR para el plan de ruido; corresponde al inicio de alto ruido del plan.

logsnr_max (*float*, valor predeterminado 2.0) : Valor máximo de log-SNR para el plan de ruido; corresponde al extremo de bajo ruido del plan.

silence_padding_duration (*float*, valor predeterminado 0.0) : Margen latente adicional después del contenido objetivo.

num_waveforms_per_prompt (*int*, valor predeterminado 1) : Formas de onda por indicación.

generator : RNG para la reproducibilidad.

latents : Ruido inicial pregenerado (`None` → muestrear uno nuevo).

prompt_embeds : Embeddings de texto precalculados.

encoder_attention_mask : Máscara para las incrustaciones precalculadas.

return_dict (*bool*, por defecto *True*) : Devuelve *AudioPipelineOutput* o una tupla.

callback_on_step_end (*Callable*, *opcional*) : Se llama al final de cada paso de desruido con *(self, step_idx, timestep, callback_kwargs)*. Debe devolver un diccionario con los tensores (posiblemente modificados) que se usarán para el resto del bucle.

callback_on_step_end_tensor_inputs (*list[str]*, por defecto *["latents"]*) : Los tensores pasados a *callback_on_step_end*. Debe ser un subconjunto de *self._callback_tensor_inputs*.

output_type (*str*, por defecto `"pt"`) : `"pt"` / `"np"` / `"latent"`.

**Devuelve:**

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

Genera una variación de audio condicionada en un prompt de texto y una forma de onda de referencia.

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

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

**Parámetros:**

duration : Duración en segundos, aplicada a cada muestra del lote.

device : Dispositivo de destino.

num_waveforms_per_prompt : Factor de teselación.

batch_size : Número de indicaciones.

**Devuelve:**

tensor `(batch * num_waveforms_per_prompt, output_dim)`.

Incorpore el valor de duración en el vector de condicionamiento 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)
```

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

**Parámetros:**

prompt : Prompt de texto o lista de prompts. Se ignora cuando se proporciona `prompt_embeds`.

device : Dispositivo de destino.

num_waveforms_per_prompt : Número de formas de onda de salida a generar por indicación; los tensores de condicionamiento se replican en consecuencia.

prompt_embeds : Embeddings de texto precalculados `(batch, seq_len, hidden_size)`.

encoder_attention_mask : Máscara booleana `(batch, seq_len)` para incrustaciones precalculadas; `1` = token real, `0` = relleno.

**Devuelve:**

`(prompt_embeds, encoder_attention_mask)` ambos con forma `batch * num_waveforms_per_prompt`.

Codifica los prompts de texto en tensores de condicionamiento para la atención cruzada.

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

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

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

**Devuelve:**

`(context, context_mask)` de formas `(batch, T_text + 1, dim)` y `(batch, T_text + 1)`.

Construya el contexto de atención cruzada añadiendo el embedding de duración como un token adicional.

SA3 enruta el condicionador `seconds_total` a *ambos*, la entrada global (AdaLN) y el contexto de atención cruzada (`cross_attention_cond_ids = ["prompt", "seconds_total"]`). El embedding de duración se concatena después de los tokens de texto y la máscara de atención se extiende con una entrada válida.

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

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

**Parámetros:**

output_dim (*int*, por defecto 768) : Dimensión del embedding de salida. Debe coincidir con `global_cond_dim` del DiT.

fourier_dim (*int*, por defecto 256) : Dimensión interna de características de Fourier (debe ser par).

min_val (*float*, valor predeterminado 0.0) : Valor mínimo de duración para el recorte de normalización.

max_val (*float*, valor predeterminado 384.0) : Valor máximo de duración para el recorte de normalización. Los valores superiores a este se recortan. 384 segundos es el límite superior de producción SA3 Medium para el condicionador `seconds_total`.

min_freq (*float*, por defecto 0.5) : Frecuencia mínima para la base exponencial de Fourier.

max_freq (*float*, por defecto 10000.0) : Frecuencia máxima para la base exponencial de Fourier.

Incorpora un valor de duración (en segundos) en un vector de condicionamiento global para Stable Audio 3 DiT (utilizado como entrada AdaLN de `global_hidden_states`).

Replica `NumberConditioner(fourier_features_type="expo")` de la implementación de referencia de SA3.

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

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

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

**Parámetros:**

seconds (`torch.Tensor` de forma `(batch,)`) : Valores de duración en segundos.

**Devuelve:**

`torch.Tensor` de forma `(batch, output_dim)` — embeddings de duración.