Hugging Face's logo

Diffusers documentation

Stable Audio 3

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Stable Audio 3

Stable Audio 3 (SA3) é um modelo de texto para áudio da Stability AI que gera áudio estéreo de alta qualidade a 44,1 kHz. Ele usa um DiT de fluxo retificado condicionado em dois sinais:

  • Texto — codificado por um codificador T5Gemma congelado e injetado via atenção cruzada.
  • Duração — um float (segundos) incorporado por StableAudio3DurationEmbedder e usado como um vetor de condicionamento global para a normalização de camada adaptativa.

O áudio é decodificado pelo autoencoder SAME (Semantically-Aligned Music Encoder), AutoencoderSAME.

Ambos os checkpoints usam FlowMatchEulerDiscreteScheduler com um agendamento de sigma log-SNR-uniforme, diferindo apenas em stochastic_sampling e no número padrão de etapas:

Checkpointdiffusion_objectivestochastic_samplingnum_inference_steps
stable-audio-3-medium-baserectified_flowFalse (Euler determinístico)100 (não destilado)
stable-audio-3-medium (destilado)rf_denoiserTrue (re-ruído ping-pong)8 (destilado para 8 etapas)

A configuração correta do scheduler está embutida em cada checkpoint convertido, portanto num_inference_steps assume o valor correto por padrão quando você não o define. Passe-o apenas para sobrescrever.

Base de código original: Stability-AI/stable-audio-3.

Convertendo checkpoints originais

Os checkpoints da Stability AI não são publicados no formato diffusers, portanto converta-os localmente. O script baixa o model_config.json do checkpoint e seleciona o scheduler a partir do seu 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-base é um repositório com acesso restrito. Execute hf auth login com uma conta que tenha acesso antes de converter; caso contrário, o download falhará com um erro 401.

Exemplo de uso

Carregue o checkpoint convertido do seu diretório de saída local (instale soundfile com 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)

O pipeline também é registrado com AutoPipelineForText2Audio, que resolve o checkpoint para StableAudio3Pipeline automaticamente:

from diffusers import AutoPipelineForText2Audio

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

Os exemplos usam um caminho local porque stabilityai/stable-audio-3-medium e stable-audio-3-medium-base ainda não foram publicados no formato diffusers (carregar pelo repo id retorna um 404). Uma vez publicados, o repo id funciona no lugar do caminho local.

Dicas

  • Use torch.float32 em CPU ou MPS (Apple Silicon) — torch.float16 em MPS gera ruído.
  • O modelo destilado (stable-audio-3-medium) é destilado adversarialmente — o guidance é incorporado nos pesos. Mantenha guidance_scale=1.0 (o padrão) e não passe um negative_prompt para esse checkpoint; ambos só fazem algo útil para o checkpoint não destilado stable-audio-3-medium-base.
  • silence_padding_duration (padrão 0.0) adiciona um espaço silencioso no final da sequência latente. Mantenha-o em 0.0, a menos que o modelo tenha sido treinado para mascarar esse padding — caso contrário, os quadros extras drenam a energia da saída e o resultado fica mais baixo.
  • Defina num_waveforms_per_prompt > 1 para gerar vários clipes por prompt.

StableAudio3Pipeline

classe diffusers.StableAudio3Pipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Parâmetros

  • vae ([AutoencoderSAME]) — Autoencoder SAME usado para codificar e decodificar latentes de áudio.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Codificador de texto T5Gemma congelado (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Tokenizer para o codificador de texto.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Mapeia duration em segundos para um vetor de condicionamento global para AdaLN em cada bloco DiT.
  • transformer ([StableAudio3DiTModel]) — O DiT de previsão de velocidade do fluxo retificado.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — Agendador para o loop iterativo de remoção de ruído. O checkpoint SA3 Medium de produção (destilado) usa stochastic_sampling=True para exatamente 8 passos de ping-pong; o checkpoint base não destilado usa stochastic_sampling=False para ~100 passos determinísticos de Euler.

Pipeline para geração de texto para áudio usando Stable Audio 3.

O SA3 usa um DiT de fluxo retificado destilado com amostragem ping-pong. O classifier-free guidance (guidance_scale / negative_prompt) não é necessário para o checkpoint destilado (deixe guidance_scale=1.0, o padrão), mas é significativo para o checkpoint não destilado stable-audio-3-medium-base.

Este modelo herda de [DiffusionPipeline]. Consulte a documentação da superclasse para os métodos genéricos implementados para todos os pipelines.

__call__

< >

( 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 ou list[str], opcional) — Prompt(s) de texto. Passe prompt_embeds em vez disso para pular a tokenização e a codificação.
  • duration (float, padrão 10.0) — Duração de saída solicitada em segundos.
  • num_inference_steps (int, opcional) — Número de etapas de desruido. Quando None (padrão), a contagem de etapas é escolhida a partir da configuração stochastic_sampling do agendador: 8 quando True (o checkpoint destilado estilo ping-pong) e 100 quando False (o checkpoint base não destilado). Passe um valor explícito para sobrescrever.
  • logsnr_min (float, padrão -6.2) — Valor mínimo de log-SNR para o agendamento de ruído — corresponde ao início de alto ruído do agendamento.
  • logsnr_max (float, padrão 2.0) — Valor máximo de log-SNR para o agendamento de ruído — corresponde à extremidade de baixo ruído do agendamento.
  • silence_padding_duration (float, padrão 0.0) — Segundos extras de contexto latente gerados além do conteúdo alvo, dando ao modelo folga na fronteira; a saída é aparada de volta para duration. Padrão 0.0 (desativado). Aumente apenas se o modelo for treinado/destilado para mascarar esse preenchimento — caso contrário, os quadros extras drenam a energia da saída.
  • guidance_scale (float, padrão 1.0) — Escala de orientação sem classificador. 1.0 desativa a orientação (o padrão, e o único valor sensato para o checkpoint destilado SA3 Medium, cuja CFG está incorporada aos pesos). Valores > 1.0 são significativos para o checkpoint não destilado stable-audio-3-medium-base; valores mais altos seguem o prompt com mais proximidade, às custas da diversidade.
  • negative_prompt (str ou list[str], opcional) — Prompt(s) descrevendo o que evitar quando guidance_scale > 1.0. O padrão é uma string vazia (não condicional) quando guidance_scale > 1.0 e nem este nem negative_prompt_embeds é fornecido. Ignorado quando guidance_scale <= 1.0.
  • num_waveforms_per_prompt (int, padrão 1) — Número de formas de onda a serem geradas por prompt.
  • generator (torch.Generator ou list[torch.Generator], opcional) — Para geração determinística e re-ruído reproduzível no loop ping-pong.
  • latents (torch.Tensor, opcional) — Latentes iniciais pré-gerados. Se None, um tensor gaussiano novo é amostrado.
  • prompt_embeds (torch.Tensor, opcional) — Incorporações de texto pré-computadas (batch, seq_len, 768).
  • encoder_attention_mask (torch.LongTensor, opcional) — Máscara booleana para incorporações pré-calculadas.
  • negative_prompt_embeds (torch.Tensor, opcional) — Incorporações de texto negativo pré-computadas, como alternativa para negative_prompt.
  • negative_encoder_attention_mask (torch.LongTensor, opcional) — Máscara booleana para embeddings negativos pré-computados.
  • return_dict (bool, padrão True) — Retorna um AudioPipelineOutput ou uma tupla simples.
  • callback_on_step_end (Callable, opcional) — Chamado no final de cada etapa de desruidamento com (self, step_idx, timestep, callback_kwargs), onde callback_kwargs contém os tensores listados em callback_on_step_end_tensor_inputs. Deve retornar um dicionário com os tensores (opcionalmente modificados) a serem usados para o restante do loop.
  • callback_on_step_end_tensor_inputs (list[str], padrão [“latents”]) — Os tensores passados para callback_on_step_end. Deve ser um subconjunto de self._callback_tensor_inputs.
  • output_type (str, padrão "pt") — "pt" para um tensor do PyTorch, "np" para um array do NumPy, ou "latent" para pular a decodificação e retornar os latentes brutos.

Retorna

[~pipelines.AudioPipelineOutput] ou tuple

.audios é um tensor / array de forma (batch * num_waveforms_per_prompt, audio_channels, samples).

Gere áudio a partir de um prompt de texto.

Exemplos:

>>> 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

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Parâmetros

  • duration — Duração em segundos, aplicada a cada amostra do lote.
  • device — Dispositivo de destino.
  • num_waveforms_per_prompt — Fator de mosaico.
  • batch_size — Número de prompts.

Incorpore o valor de duração no vetor de condicionamento global.

encode_prompt

< >

( 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 — Prompt de texto ou lista de prompts. Ignorado quando prompt_embeds é fornecido.
  • device — Dispositivo de destino.
  • num_waveforms_per_prompt — Quantas formas de onda de saída gerar por prompt; os tensores de condicionamento são replicados de acordo.
  • prompt_embeds — Embeddings de texto pré-computados (batch, seq_len, hidden_size).
  • encoder_attention_mask — Máscara booleana (batch, seq_len) para embeddings pré-computados; 1 = token real, 0 = padding.

Codifique os prompts de texto em tensores de condicionamento de atenção cruzada.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Construa o contexto de atenção cruzada adicionando o embedding de duração como um token extra.

SA3 encaminha o condicionador seconds_total para ambos a entrada global (AdaLN) e o contexto de atenção cruzada (cross_attention_cond_ids = ["prompt", "seconds_total"]). O embedding de duração é concatenado após os tokens de texto, e a máscara de atenção é estendida com uma entrada válida.

StableAudio3InpaintPipeline

classe diffusers.StableAudio3InpaintPipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Parâmetros

  • vae ([AutoencoderSAME]) — Autoencoder SAME usado para codificar e decodificar latentes de áudio.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Codificador de texto T5Gemma congelado (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Tokenizer para o codificador de texto.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Mapeia duration em segundos para um vetor de condicionamento global para AdaLN em cada bloco DiT.
  • transformer ([StableAudio3DiTModel]) — O DiT de previsão de velocidade do fluxo retificado.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — Agendador para o loop iterativo de remoção de ruído. O checkpoint SA3 Medium de produção (destilado) usa stochastic_sampling=True para exatamente 8 passos de ping-pong; o checkpoint base não destilado usa stochastic_sampling=False para ~100 passos determinísticos de Euler.

Pipeline de inpainting de áudio para Stable Audio 3.

Compartilha sua lógica de texto para áudio com [StableAudio3Pipeline] (mantida em sincronia via # Copied from). Quando audio e mask são fornecidos, codifica o áudio de referência com o codificador SAME congelado e injeta masked_latent ∥ mask como condicionamento local aditivo em cada bloco DiT por meio do caminho local_add_cond do transformer (to_local_embed).

Extensão da assinatura de chamada (veja __call__): audio (torch.Tensor de forma (batch, channels, samples)): Forma de onda de áudio de referência em vae.config.sampling_rate Hz. mask (torch.Tensor de forma (batch, 1, latent_length)): Máscara binária por quadro no espaço latente. 1 = preserva o áudio original; 0 = região a ser preenchida.

__call__

< >

( 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 ou list[str], opcional) — Prompt(s) de texto.
  • duration (float, padrão 10.0) — Duração da saída em segundos. Deve corresponder ao áudio de referência.
  • audio (torch.Tensor, optional) — Forma de onda de referência (batch, channels, samples) em vae.config.sampling_rate Hz. Obrigatório para inpainting.
  • mask (torch.Tensor, optional) — Máscara no espaço latente por quadro (batch, 1, L) em que 0 = região de inpainting e 1 = preservar. É necessário fornecer mask ou mask_start_seconds / mask_end_seconds.
  • mask_start_seconds (float ou list[float], opcional) — Tempo(s) de início da região de inpaint em segundos.
  • mask_end_seconds (float ou list[float], opcional) — Tempo(s) final(is) da região de inpaint (deve ser usado em conjunto com mask_start_seconds).
  • num_inference_steps (int, opcional) — Número de etapas de desruidamento. Quando None (padrão), a contagem de etapas é escolhida a partir da configuração stochastic_sampling do agendador, correspondendo a [StableAudio3Pipeline].
  • logsnr_min (float, padrão -6.2) — Valor mínimo de log-SNR para o agendamento de ruído — corresponde ao início de alto ruído do agendamento.
  • logsnr_max (float, padrão 2.0) — Valor máximo de log-SNR para o agendamento de ruído — corresponde à extremidade de baixo ruído do agendamento.
  • silence_padding_duration (float, padrão 0.0) — Margem extra de latência após o conteúdo alvo.
  • num_waveforms_per_prompt (int, padrão 1) — Formas de onda por prompt.
  • generator — RNG para reprodutibilidade.
  • latents — Ruído inicial pré-gerado (None → amostra novo).
  • prompt_embeds — Embeddings de texto pré-computados.
  • encoder_attention_mask — Máscara para incorporações pré-calculadas.
  • return_dict (bool, padrão True) — Retorna AudioPipelineOutput ou tupla.
  • callback_on_step_end (Callable, opcional) — Chamado no final de cada etapa de desruidamento com (self, step_idx, timestep, callback_kwargs). Deve retornar um dicionário com os tensores (eventualmente modificados) a serem usados para o restante do loop.
  • callback_on_step_end_tensor_inputs (list[str], padrão [“latents”]) — Os tensores passados para callback_on_step_end. Deve ser um subconjunto de self._callback_tensor_inputs.
  • output_type (str, padrão "pt") — "pt" / "np" / "latent".

Gere áudio reconstruído condicionado em um prompt de texto e uma referência.

Exemplos:

>>> 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

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Parâmetros

  • duration — Duração em segundos, aplicada a cada amostra do lote.
  • device — Dispositivo de destino.
  • num_waveforms_per_prompt — Fator de mosaico.
  • batch_size — Número de prompts.

Incorpore o valor de duração no vetor de condicionamento global.

encode_prompt

< >

( 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 — Prompt de texto ou lista de prompts. Ignorado quando prompt_embeds é fornecido.
  • device — Dispositivo de destino.
  • num_waveforms_per_prompt — Quantas formas de onda de saída gerar por prompt; os tensores de condicionamento são replicados de acordo.
  • prompt_embeds — Embeddings de texto pré-computados (batch, seq_len, hidden_size).
  • encoder_attention_mask — Máscara booleana (batch, seq_len) para embeddings pré-computados; 1 = token real, 0 = padding.

Codifique os prompts de texto em tensores de condicionamento de atenção cruzada.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Construa o contexto de atenção cruzada adicionando o embedding de duração como um token extra.

SA3 encaminha o condicionador seconds_total para ambos a entrada global (AdaLN) e o contexto de atenção cruzada (cross_attention_cond_ids = ["prompt", "seconds_total"]). O embedding de duração é concatenado após os tokens de texto, e a máscara de atenção é estendida com uma entrada válida.

StableAudio3AudioToAudioPipeline

Gera uma variação de um clipe de áudio de referência: todo o áudio de referência é adicionado com ruído até init_noise_level e depois dessoneado a partir desse ponto, diferentemente do condicionamento local aditivo por quadro do StableAudio3InpaintPipeline, que preserva quadros específicos exatamente.

classe diffusers.StableAudio3AudioToAudioPipeline

< >

( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )

Parâmetros

  • vae ([AutoencoderSAME]) — Autoencoder SAME usado para codificar e decodificar latentes de áudio.
  • text_encoder ([~transformers.T5GemmaEncoderModel]) — Codificador de texto T5Gemma congelado (google/t5gemma-b-b-ul2).
  • tokenizer ([~transformers.GemmaTokenizerFast]) — Tokenizer para o codificador de texto.
  • duration_embedder ([StableAudio3DurationEmbedder]) — Mapeia duration em segundos para um vetor de condicionamento global para AdaLN em cada bloco DiT.
  • transformer ([StableAudio3DiTModel]) — O DiT de previsão de velocidade do fluxo retificado.
  • scheduler ([FlowMatchEulerDiscreteScheduler]) — Agendador para o loop iterativo de remoção de ruído. O checkpoint SA3 Medium de produção (destilado) usa stochastic_sampling=True para exatamente 8 passos de ping-pong; o checkpoint base não destilado usa stochastic_sampling=False para ~100 passos determinísticos de Euler.

Pipeline de variação de áudio para áudio para Stable Audio 3.

Compartilha sua lógica de texto para áudio com [StableAudio3Pipeline] (mantida em sincronia via # Copied from). Codifica o áudio de referência com o codificador SAME congelado, mistura-o com ruído novo de acordo com init_noise_level e remove o ruído a partir daí — o sinal inteiro é adicionado/removido de ruído globalmente, ao contrário da condicionamento local aditivo por quadro de [StableAudio3InpaintPipeline].

Extensão da assinatura de chamada (veja __call__): audio (torch.Tensor de forma (batch, channels, samples)): Forma de onda de áudio de referência em vae.config.sampling_rate Hz. init_noise_level (float): Quanto ruído misturar na referência antes da remoção de ruído. 1.0 = ruído total (equivalente a texto-para-áudio); valores menores retêm mais da referência.

__call__

< >

( 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 ou list[str], opcional) — Prompt(s) de texto.
  • duration (float, padrão 10.0) — Duração da saída em segundos. Deve corresponder ao áudio de referência.
  • audio (torch.Tensor, optional) — Forma de onda de referência (batch, channels, samples) em vae.config.sampling_rate Hz. Obrigatório.
  • init_noise_level (float, padrão 1.0) — Nível de ruído (em (0, 1]) misturado na referência antes do desruído: x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise. 1.0 descarta a referência inteiramente (equivalente a [StableAudio3Pipeline]); valores menores retêm progressivamente mais da estrutura da referência, mantendo o número total de etapas.
  • num_inference_steps (int, opcional) — Número de etapas de desruidamento. Quando None (padrão), a contagem de etapas é escolhida a partir da configuração stochastic_sampling do agendador, correspondendo a [StableAudio3Pipeline].
  • logsnr_min (float, padrão -6.2) — Valor mínimo de log-SNR para o agendamento de ruído — corresponde ao início de alto ruído do agendamento.
  • logsnr_max (float, padrão 2.0) — Valor máximo de log-SNR para o agendamento de ruído — corresponde à extremidade de baixo ruído do agendamento.
  • silence_padding_duration (float, padrão 0.0) — Margem extra de latência após o conteúdo alvo.
  • num_waveforms_per_prompt (int, padrão 1) — Formas de onda por prompt.
  • generator — RNG para reprodutibilidade.
  • latents — Ruído inicial pré-gerado (None → amostra novo).
  • prompt_embeds — Embeddings de texto pré-computados.
  • encoder_attention_mask — Máscara para incorporações pré-calculadas.
  • return_dict (bool, padrão True) — Retorna AudioPipelineOutput ou tupla.
  • callback_on_step_end (Callable, opcional) — Chamado no final de cada etapa de desruidamento com (self, step_idx, timestep, callback_kwargs). Deve retornar um dicionário com os tensores (eventualmente modificados) a serem usados para o restante do loop.
  • callback_on_step_end_tensor_inputs (list[str], padrão [“latents”]) — Os tensores passados para callback_on_step_end. Deve ser um subconjunto de self._callback_tensor_inputs.
  • output_type (str, padrão "pt") — "pt" / "np" / "latent".

Gere uma variação de áudio condicionada a um prompt de texto e a uma forma de onda de referência.

Exemplos:

>>> 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

< >

( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )

Parâmetros

  • duration — Duração em segundos, aplicada a cada amostra do lote.
  • device — Dispositivo de destino.
  • num_waveforms_per_prompt — Fator de mosaico.
  • batch_size — Número de prompts.

Incorpore o valor de duração no vetor de condicionamento global.

encode_prompt

< >

( 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 — Prompt de texto ou lista de prompts. Ignorado quando prompt_embeds é fornecido.
  • device — Dispositivo de destino.
  • num_waveforms_per_prompt — Quantas formas de onda de saída gerar por prompt; os tensores de condicionamento são replicados de acordo.
  • prompt_embeds — Embeddings de texto pré-computados (batch, seq_len, hidden_size).
  • encoder_attention_mask — Máscara booleana (batch, seq_len) para embeddings pré-computados; 1 = token real, 0 = padding.

Codifique os prompts de texto em tensores de condicionamento de atenção cruzada.

prepare_cross_attention

< >

( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )

Construa o contexto de atenção cruzada adicionando o embedding de duração como um token extra.

SA3 encaminha o condicionador seconds_total para ambos a entrada global (AdaLN) e o contexto de atenção cruzada (cross_attention_cond_ids = ["prompt", "seconds_total"]). O embedding de duração é concatenado após os tokens de texto, e a máscara de atenção é estendida com uma entrada válida.

StableAudio3DurationEmbedder

classe diffusers.StableAudio3DurationEmbedder

< >

( 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, padrão 768) — Dimensão do embedding de saída. Deve corresponder ao global_cond_dim do DiT.
  • fourier_dim (int, padrão 256) — Dimensão interna do recurso de Fourier (deve ser par).
  • min_val (float, padrão 0.0) — Valor mínimo de duração para o clamping de normalização.
  • max_val (float, padrão 384.0) — Valor máximo de duração para o clamping de normalização. Valores acima disso são limitados. 384 segundos é o limite superior de produção do SA3 Medium para o condicionador seconds_total.
  • min_freq (float, padrão 0.5) — Frequência mínima para a base exponencial de Fourier.
  • max_freq (float, padrão 10000.0) — Frequência máxima para a base exponencial de Fourier.

Incorpora um valor de duração (em segundos) em um vetor de condicionamento global para o Stable Audio 3 DiT (usado como entrada AdaLN de global_hidden_states).

Replica o NumberConditioner(fourier_features_type="expo") da implementação de referência do SA3.

forward

< >

( seconds: Tensor )

Parâmetros

  • seconds (torch.Tensor de forma (batch,)) — Valores de duração em segundos.
Update on GitHub

←Stable Audio Anima→