# Stable Audio 3 Stable Audio 3 (SA3) é um modelo de texto para áudio da [Stability AI](https://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](/docs/diffusers/v0.43.0/pt/api/pipelines/stable_audio_3#diffusers.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](/docs/diffusers/v0.43.0/pt/api/models/autoencoder_same#diffusers.AutoencoderSAME). Ambos os checkpoints usam [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) com um agendamento de sigma log-SNR-uniforme, diferindo apenas em `stochastic_sampling` e no número padrão de etapas: | Checkpoint | `diffusion_objective` | `stochastic_sampling` | `num_inference_steps` | |---|---|---|---| | `stable-audio-3-medium-base` | `rectified_flow` | `False` (Euler determinístico) | **100** (não destilado) | | `stable-audio-3-medium` (destilado) | `rf_denoiser` | `True` (re-ruído ping-pong) | **8** (destilado para 8 etapas) | A configuração correta do agendador 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](https://github.com/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`: ```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` é 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`](https://pypi.org/project/soundfile/) com `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) ``` O pipeline também é registrado com [AutoPipelineForText2Audio](/docs/diffusers/v0.43.0/pt/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Audio), que resolve o checkpoint para `StableAudio3Pipeline` automaticamente: ```py from diffusers import AutoPipelineForText2Audio pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32) ``` > [!NOTE] > 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ó têm utilidade 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[[diffusers.StableAudio3Pipeline]] #### diffusers.StableAudio3Pipeline[[diffusers.StableAudio3Pipeline]] ```python diffusers.StableAudio3Pipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Fonte](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 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*]) : Tokenizador 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 de 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__[[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') ``` [Fonte](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* 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*, *optional*) : Número de etapas de desruidamento. 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 cronograma de ruído — corresponde ao início de alto ruído do cronograma. logsnr_max (*float*, padrão 2.0) : Valor máximo de log-SNR para o agendamento de ruído — mapeia para a 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 fidelidade, à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*) : Embebimentos de texto negativos pré-computados, 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: ```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) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L289) **Parâmetros:** duration : Duração em segundos, aplicada a cada amostra do lote. device : Dispositivo de destino. num_waveforms_per_prompt : Fator de tile. batch_size : Número de prompts. **Retorna:** tensor `(batch * num_waveforms_per_prompt, output_dim)`. Incorpore o valor de duração no vetor de condicionamento 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) ``` [Fonte](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 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 : Incorporações de texto pré-computadas `(batch, seq_len, hidden_size)`. encoder_attention_mask : Máscara booleana `(batch, seq_len)` para incorporações pré-calculadas; `1` = token real, `0` = preenchimento. **Retorna:** `(prompt_embeds, encoder_attention_mask)` ambos tileados para `batch * num_waveforms_per_prompt`. Codifique os prompts de texto em tensores de condicionamento de atenção cruzada. #### prepare_cross_attention[[diffusers.StableAudio3Pipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L313) **Retorna:** `(context, context_mask)` com formas `(batch, T_text + 1, dim)` e `(batch, T_text + 1)`. 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[[diffusers.StableAudio3InpaintPipeline]] #### diffusers.StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]] ```python diffusers.StableAudio3InpaintPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Fonte](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 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*]) : Tokenizador 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 de 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__`): áudio (*torch.Tensor* de forma `(batch, channels, samples)`): Forma de onda de áudio de referência em `vae.config.sampling_rate` Hz. máscara (*torch.Tensor* de forma `(batch, 1, latent_length)`): Máscara binária por quadro no espaço latente. `1` = preservar o áudio original; `0` = região a ser preenchida. #### __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') ``` [Fonte](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* ou *list[str]*, *opcional*) : Prompt(s) de texto. duration (*float*, padrão 10.0) : Duração de saída em segundos. Deve corresponder ao áudio de referência. audio (*torch.Tensor*, *opcional*) : Forma de onda de referência `(batch, channels, samples)` em `vae.config.sampling_rate` Hz. Obrigatório para inpainting. mask (*torch.Tensor*, *opcional*) : Máscara do espaço latente por quadro `(batch, 1, L)` com 0 = região de inpaint, 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 remoção de ruído. 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 cronograma de ruído — corresponde ao início de alto ruído do cronograma. logsnr_max (*float*, padrão 2.0) : Valor máximo de log-SNR para o agendamento de ruído — mapeia para a extremidade de baixo ruído do agendamento. silence_padding_duration (*float*, padrão 0.0) : Espaço latente extra 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` → amostrar novo). prompt_embeds : Incorporações de texto pré-computadas. encoder_attention_mask : Máscara para incorporações pré-computadas. 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 (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"` / `"np"` / `"latent"`. **Retorna:** [*~pipelines.AudioPipelineOutput*] com `.audios`. Gere áudio reconstruído condicionado em um prompt de texto e uma referência. Exemplos: ```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) ``` [Fonte](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 : Duração em segundos, aplicada a cada amostra do lote. device : Dispositivo de destino. num_waveforms_per_prompt : Fator de tile. batch_size : Número de prompts. **Retorna:** tensor `(batch * num_waveforms_per_prompt, output_dim)`. Incorpore o valor de duração no vetor de condicionamento 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) ``` [Fonte](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 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 : Incorporações de texto pré-computadas `(batch, seq_len, hidden_size)`. encoder_attention_mask : Máscara booleana `(batch, seq_len)` para incorporações pré-calculadas; `1` = token real, `0` = preenchimento. **Retorna:** `(prompt_embeds, encoder_attention_mask)` ambos tileados para `batch * num_waveforms_per_prompt`. Codifique os prompts de texto em tensores de condicionamento de atenção cruzada. #### prepare_cross_attention[[diffusers.StableAudio3InpaintPipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L315) **Retorna:** `(context, context_mask)` com formas `(batch, T_text + 1, dim)` e `(batch, T_text + 1)`. 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[[diffusers.StableAudio3AudioToAudioPipeline]] Gera uma variação de um clipe de áudio de referência: toda a referência é adicionada com ruído até `init_noise_level` e depois desruidificada a partir desse ponto, diferentemente do condicionamento local aditivo por quadro do [StableAudio3InpaintPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/stable_audio_3#diffusers.StableAudio3InpaintPipeline), que preserva quadros específicos exatamente. #### diffusers.StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]] ```python diffusers.StableAudio3AudioToAudioPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Fonte](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 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*]) : Tokenizador 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 de 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 condição local aditiva por quadro de [*StableAudio3InpaintPipeline*]. Extensão da assinatura de chamada (veja `__call__`): áudio (*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*): Quantidade de ruído a ser misturada 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__[[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') ``` [Fonte](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* ou *list[str]*, *opcional*) : Prompt(s) de texto. duration (*float*, padrão 10.0) : Duração de saída em segundos. Deve corresponder ao áudio de referência. audio (*torch.Tensor*, *opcional*) : 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 da remoção de ruído: `x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise`. `1.0` descarta a referência por completo (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 remoção de ruído. 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 cronograma de ruído — corresponde ao início de alto ruído do cronograma. logsnr_max (*float*, padrão 2.0) : Valor máximo de log-SNR para o agendamento de ruído — mapeia para a extremidade de baixo ruído do agendamento. silence_padding_duration (*float*, padrão 0.0) : Espaço latente extra 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` → amostrar novo). prompt_embeds : Incorporações de texto pré-computadas. encoder_attention_mask : Máscara para incorporações pré-computadas. 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 (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"` / `"np"` / `"latent"`. **Retorna:** [*~pipelines.AudioPipelineOutput*] com `.audios`. Gere uma variação de áudio condicionada a um prompt de texto e a uma forma de onda de referência. Exemplos: ```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) ``` [Fonte](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 : Duração em segundos, aplicada a cada amostra do lote. device : Dispositivo de destino. num_waveforms_per_prompt : Fator de tile. batch_size : Número de prompts. **Retorna:** tensor `(batch * num_waveforms_per_prompt, output_dim)`. Incorpore o valor de duração no vetor de condicionamento 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) ``` [Fonte](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 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 : Incorporações de texto pré-computadas `(batch, seq_len, hidden_size)`. encoder_attention_mask : Máscara booleana `(batch, seq_len)` para incorporações pré-calculadas; `1` = token real, `0` = preenchimento. **Retorna:** `(prompt_embeds, encoder_attention_mask)` ambos tileados para `batch * num_waveforms_per_prompt`. Codifique os prompts de texto em tensores de condicionamento de atenção cruzada. #### prepare_cross_attention[[diffusers.StableAudio3AudioToAudioPipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Fonte](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L312) **Retorna:** `(context, context_mask)` com formas `(batch, T_text + 1, dim)` e `(batch, T_text + 1)`. 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[[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) ``` [Fonte](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*, 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 de características 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[[diffusers.StableAudio3DurationEmbedder.forward]] ```python forward(seconds: Tensor) ``` [Fonte](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 duração em segundos. **Retorna:** `torch.Tensor` de forma `(batch, output_dim)` — incorporações de duração.