Hugging Face's logo

Diffusers documentation

Stable Audio 3

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.42.1).
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→