Diffusers documentation
Stable Audio 3
Stable Audio 3
Stable Audio 3 (SA3) es un modelo de texto a audio de 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 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.
Ambos puntos de control utilizan 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 correcto de forma predeterminada si no lo estableces. Solo pásalo para sobrescribirlo.
Código base original: 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:
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
stable-audio-3-medium-basees un repositorio con acceso restringido. Ejecutahf auth logincon 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 con pip install soundfile):
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, que resuelve el checkpoint a StableAudio3Pipeline automáticamente:
from diffusers import AutoPipelineForText2Audio
pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)Los ejemplos utilizan una ruta local porque
stabilityai/stable-audio-3-mediumystable-audio-3-medium-baseaú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.float32en CPU o MPS (Apple Silicon) —torch.float16en MPS produce ruido. - El modelo destilado (
stable-audio-3-medium) es destilado adversarialmente: la guía está integrada en los pesos. Dejaguidance_scale=1.0(el valor predeterminado) y no pases unnegative_promptpara ese punto de control; ambos solo son útiles para el punto de control no destiladostable-audio-3-medium-base. silence_padding_duration(valor predeterminado0.0) añade silencio al final de la secuencia latente. Déjalo en0.0a 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 > 1para generar varios clips por prompt.
StableAudio3Pipeline
clase diffusers.StableAudio3Pipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
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
durationen 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í es significativa 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__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0guidance_scale: float = 1.0negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_encoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' ) → [~pipelines.AudioPipelineOutput] or tuple
Parámetros
- prompt (str o list[str], opcional) —
Prompts de texto. Pasa
prompt_embedsen 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, opcional) —
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). Pasa un valor explícito para sobrescribirlo. - logsnr_min (float, por defecto -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 — se corresponde con el 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éntalo solo si el modelo se ha 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.0desactiva la guía (el valor predeterminado y el único valor sensato para el punto de control destilado SA3 Medium, cuya CFG está integrada en los pesos). Los valores> 1.0son significativos para el punto de control no destiladostable-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 qué evitar cuando
guidance_scale > 1.0. Por defecto, es una cadena vacía (no condicional) cuandoguidance_scale > 1.0y no se proporciona ni este parámetro ni negative_prompt_embeds. Se ignora cuandoguidance_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) —
Incrustaciones de texto precalculadas
(batch, seq_len, 768). - encoder_attention_mask (torch.LongTensor, opcional) — Máscara booleana para incrustaciones precalculadas.
- negative_prompt_embeds (torch.Tensor, opcional) — Incrustaciones de texto negativo precalculadas, como alternativa a negative_prompt.
- negative_encoder_attention_mask (torch.LongTensor, opcional) — Máscara booleana para las incrustaciones negativas precalculadas.
- 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 dict con los tensores (posiblemente modificados) para usarlos en el resto del bucle.
- callback_on_step_end_tensor_inputs (list[str], por defecto [“latents”]) — Los tensores que se pasan 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:
>>> 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
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Incorpore el valor de duración en el vector de condicionamiento global.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
Parámetros
- prompt — Texto de indicación o lista de indicaciones. Se ignora cuando se proporciona
prompt_embeds. - device — Dispositivo de destino.
- num_waveforms_per_prompt — Número de formas de onda de salida que se generan por indicación; los tensores de condicionamiento se replican en consecuencia.
- prompt_embeds — Incrustaciones de texto precalculadas
(batch, seq_len, hidden_size). - encoder_attention_mask — Máscara booleana
(batch, seq_len)para embeddings precalculados;1= token real,0= relleno.
Codifica los prompts de texto en tensores de condicionamiento para la atención cruzada.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
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 ambas la entrada global (AdaLN) y el contexto de atención cruzada (cross_attention_cond_ids = ["prompt", "seconds_total"]). El embebido 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
clase diffusers.StableAudio3InpaintPipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
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
durationen 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 sincronizada 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__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Nonemask: typing.Optional[torch.Tensor] = Nonemask_start_seconds: typing.Union[float, typing.List[float], NoneType] = Nonemask_end_seconds: typing.Union[float, typing.List[float], NoneType] = Nonenum_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )
Parámetros
- prompt (str o list[str], opcional) — Prompts de texto.
- duration (float, por defecto 10.0) — Duración de la salida en segundos. Debe coincidir con el audio de referencia.
- audio (torch.Tensor, optional) —
Forma de onda de referencia
(batch, channels, samples)avae.config.sampling_rateHz. Obligatorio para inpainting. - mask (torch.Tensor, optional) —
Máscara en el espacio latente por fotograma
(batch, 1, L)donde 0 = región de inpainting y 1 = conservar. Debe proporcionarsemaskomask_start_seconds/mask_end_seconds. - mask_start_seconds (float o list[float], opcional) — Tiempo 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 ir junto con
mask_start_seconds). - num_inference_steps (int, opcional) —
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, en concordancia con [StableAudio3Pipeline]. - logsnr_min (float, por defecto -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 — se corresponde con el 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, por defecto 1) — Formas de onda por indicación.
- generator — RNG para la reproducibilidad.
- latents — Ruido inicial pregenerado (
None→ muestrear uno nuevo). - prompt_embeds — Incrustaciones de texto precalculadas.
- 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 que se pasan a callback_on_step_end. Debe ser un subconjunto de self._callback_tensor_inputs.
- output_type (str, por defecto
"pt") —"pt"/"np"/"latent".
Genera audio reconstruido condicionado por un prompt de texto y una referencia.
Ejemplos:
>>> 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
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Incorpore el valor de duración en el vector de condicionamiento global.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
Parámetros
- prompt — Texto de indicación o lista de indicaciones. Se ignora cuando se proporciona
prompt_embeds. - device — Dispositivo de destino.
- num_waveforms_per_prompt — Número de formas de onda de salida que se generan por indicación; los tensores de condicionamiento se replican en consecuencia.
- prompt_embeds — Incrustaciones de texto precalculadas
(batch, seq_len, hidden_size). - encoder_attention_mask — Máscara booleana
(batch, seq_len)para embeddings precalculados;1= token real,0= relleno.
Codifica los prompts de texto en tensores de condicionamiento para la atención cruzada.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
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 ambas la entrada global (AdaLN) y el contexto de atención cruzada (cross_attention_cond_ids = ["prompt", "seconds_total"]). El embebido 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
Genera una variación de un clip de audio de referencia: toda la referencia se ruidifica hasta init_noise_level y se desruidifica a partir de ahí, a diferencia de la condición local aditiva por fotograma de StableAudio3InpaintPipeline, que preserva ciertos fotogramas de forma exacta.
clase diffusers.StableAudio3AudioToAudioPipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
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
durationen 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 elimina el ruido a partir de ahí: toda la señal se ruidiza/denoisea 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__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Noneinit_noise_level: float = 1.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )
Parámetros
- prompt (str o list[str], opcional) — Prompts de texto.
- duration (float, por defecto 10.0) — Duración de la salida en segundos. Debe coincidir con el audio de referencia.
- audio (torch.Tensor, optional) —
Forma de onda de referencia
(batch, channels, samples)avae.config.sampling_rateHz. Obligatorio. - init_noise_level (float, valor predeterminado 1.0) —
Nivel de ruido (en
(0, 1]) que se mezcla con la referencia antes del desruido:x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise.1.0descarta la referencia por completo (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, opcional) —
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, en concordancia con [StableAudio3Pipeline]. - logsnr_min (float, por defecto -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 — se corresponde con el 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, por defecto 1) — Formas de onda por indicación.
- generator — RNG para la reproducibilidad.
- latents — Ruido inicial pregenerado (
None→ muestrear uno nuevo). - prompt_embeds — Incrustaciones de texto precalculadas.
- 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 que se pasan a callback_on_step_end. Debe ser un subconjunto de self._callback_tensor_inputs.
- output_type (str, por defecto
"pt") —"pt"/"np"/"latent".
Genera una variación de audio condicionada en un prompt de texto y una forma de onda de referencia.
Ejemplos:
>>> 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
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Incorpore el valor de duración en el vector de condicionamiento global.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
Parámetros
- prompt — Texto de indicación o lista de indicaciones. Se ignora cuando se proporciona
prompt_embeds. - device — Dispositivo de destino.
- num_waveforms_per_prompt — Número de formas de onda de salida que se generan por indicación; los tensores de condicionamiento se replican en consecuencia.
- prompt_embeds — Incrustaciones de texto precalculadas
(batch, seq_len, hidden_size). - encoder_attention_mask — Máscara booleana
(batch, seq_len)para embeddings precalculados;1= token real,0= relleno.
Codifica los prompts de texto en tensores de condicionamiento para la atención cruzada.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
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 ambas la entrada global (AdaLN) y el contexto de atención cruzada (cross_attention_cond_ids = ["prompt", "seconds_total"]). El embebido 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
clase diffusers.StableAudio3DurationEmbedder
< source >( output_dim: int = 768fourier_dim: int = 256min_val: float = 0.0max_val: float = 384.0min_freq: float = 0.5max_freq: float = 10000.0 )
Parámetros
- output_dim (int, por defecto 768) —
Dimensión del embedding de salida. Debe coincidir con
global_cond_dimdel DiT. - fourier_dim (int, por defecto 256) — Dimensión interna de características de Fourier (debe ser par).
- min_val (float, por defecto 0.0) — Valor mínimo de duración para el recorte de normalización.
- max_val (float, por defecto 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 acondicionador
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
< source >( seconds: Tensor )