Diffusers documentation
Stable Audio 3
Stable Audio 3
Stable Audio 3 (SA3) est un modèle de texte vers audio de Stability AI qui génère de l’audio stéréo de haute qualité à 44,1 kHz. Il utilise un DiT à flux rectifié conditionné par deux signaux :
- Texte — encodé par un encodeur T5Gemma figé et injecté via l'attention croisée.
- Durée — un float (secondes) intégré par StableAudio3DurationEmbedder et utilisé comme vecteur de conditionnement global pour la normalisation de couche adaptative.
L'audio est décodé par l'autoencodeur SAME (Semantically-Aligned Music Encoder), AutoencoderSAME.
Les deux points de contrôle utilisent FlowMatchEulerDiscreteScheduler avec un calendrier de sigma uniforme en log-SNR, ne différant que par stochastic_sampling et le nombre de pas par défaut :
| Point de contrôle | diffusion_objective | stochastic_sampling | num_inference_steps |
|---|---|---|---|
stable-audio-3-medium-base | rectified_flow | False (Euler déterministe) | 100 (non distillé) |
stable-audio-3-medium (distillé) | rf_denoiser | True (bruitage ping-pong) | 8 (distillé sur 8 étapes) |
La configuration du planificateur correcte est intégrée à chaque point de contrôle converti, de sorte que num_inference_steps prend par défaut la bonne valeur si vous ne la définissez pas. Ne la passez que pour l’écraser.
Base de code originale : Stability-AI/stable-audio-3.
Conversion des points de contrôle d'origine
Les points de contrôle de Stability AI ne sont pas publiés au format diffusers, il faut donc les convertir localement. Le script télécharge le model_config.json du point de contrôle et sélectionne le planificateur à partir de son 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-baseest un dépôt restreint. Exécutezhf auth loginavec un compte ayant accès avant la conversion, sinon le téléchargement échouera avec une erreur 401.
Exemple d'utilisation
Chargez le point de contrôle converti depuis son répertoire de sortie local (installez soundfile avec 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)Le pipeline est également enregistré avec AutoPipelineForText2Audio, qui résout automatiquement le point de contrôle vers StableAudio3Pipeline :
from diffusers import AutoPipelineForText2Audio
pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32)Les exemples utilisent un chemin local car
stabilityai/stable-audio-3-mediumetstable-audio-3-medium-basene sont pas encore publiés au format diffusers (le chargement par identifiant de dépôt renvoie une erreur 404). Une fois publiés, l'identifiant de dépôt fonctionne à la place du chemin local.
Astuces
- Utilisez
torch.float32sur CPU ou MPS (Apple Silicon) —torch.float16sur MPS génère du bruit. - Le modèle distillé (
stable-audio-3-medium) est distillé de manière adversariale — le guidage est intégré dans les poids. Laissezguidance_scale=1.0(la valeur par défaut) et ne passez pas denegative_promptpour ce point de contrôle ; ces deux paramètres ne sont utiles que pour le point de contrôle non distilléstable-audio-3-medium-base. silence_padding_duration(par défaut0.0) ajoute une marge de silence à la fin de la séquence latente. Laissez cette valeur à0.0sauf si le modèle est entraîné à masquer ce bourrage — sinon, les images supplémentaires drainent l'énergie de la sortie et le résultat devient silencieux.- Définissez
num_waveforms_per_prompt > 1pour générer plusieurs clips par invite.
StableAudio3Pipeline
classe diffusers.StableAudio3Pipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
Paramètres
- vae ([AutoencoderSAME]) — Autoencodeur SAME utilisé pour encoder et décoder les latents audio.
- text_encoder ([~transformers.T5GemmaEncoderModel]) —
Encodeur de texte T5Gemma figé (
google/t5gemma-b-b-ul2). - tokenizer ([~transformers.GemmaTokenizerFast]) — Jetoniseur pour l'encodeur de texte.
- duration_embedder ([StableAudio3DurationEmbedder]) —
Mappe
durationen secondes vers un vecteur de conditionnement global pour AdaLN dans chaque bloc DiT. - transformer ([StableAudio3DiTModel]) — Le DiT de prédiction de vitesse rectifiée du flux.
- scheduler ([FlowMatchEulerDiscreteScheduler]) — Planificateur pour la boucle itérative de débruitage. Le point de contrôle SA3 Medium de production (distillé) utilise stochastic_sampling=True pour exactement 8 étapes ping-pong ; le point de contrôle de base non distillé utilise stochastic_sampling=False pour environ 100 étapes déterministes d’Euler.
Pipeline pour la génération de texte en audio utilisant Stable Audio 3.
SA3 utilise un DiT de flux rectifié distillé avec un échantillonnage ping-pong. Le guidage sans classifieur (guidance_scale / negative_prompt) n’est pas nécessaire pour le point de contrôle distillé (laissez guidance_scale=1.0, la valeur par défaut), mais il est pertinent pour le point de contrôle non distillé stable-audio-3-medium-base.
Ce modèle hérite de [DiffusionPipeline]. Consultez la documentation de la classe parente pour les méthodes génériques implémentées pour tous les pipelines.
__call__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0guidance_scale: float = 1.0negative_prompt: typing.Union[str, typing.List[str], NoneType] = Nonenum_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonenegative_prompt_embeds: typing.Optional[torch.Tensor] = Nonenegative_encoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' ) → [~pipelines.AudioPipelineOutput] or tuple
Paramètres
- prompt (str ou list[str], facultatif) —
Prompt(s) texte. Passez
prompt_embedsà la place pour ignorer la tokenisation et l’encodage. - duration (float, par défaut 10.0) — Durée de sortie demandée, en secondes.
- num_inference_steps (int, facultatif) —
Nombre d’étapes de débruitage. Lorsque la valeur est
None(par défaut), le nombre d’étapes est choisi à partir de la configuration stochastic_sampling du planificateur : 8 si True (point de contrôle distillé de type ping-pong) et 100 si False (point de contrôle de base non distillé). Transmettez une valeur explicite pour l’écraser. - logsnr_min (float, par défaut -6.2) — Valeur minimale de log-SNR pour le calendrier de bruit — correspond au début du calendrier, à forte intensité de bruit.
- logsnr_max (float, par défaut 2.0) — Valeur maximale de log-SNR pour le calendrier de bruit — correspond à l'extrémité à faible bruit du calendrier.
- silence_padding_duration (float, par défaut 0.0) — Secondes supplémentaires de contexte latent générées au-delà du contenu cible, offrant au modèle une marge de manœuvre à la frontière ; la sortie est ensuite rognée à duration. Par défaut 0.0 (désactivé). N’augmentez cette valeur que si le modèle est entraîné ou distillé pour masquer ce bourrage — sinon, les images supplémentaires drainent l’énergie de la sortie.
- guidance_scale (float, par défaut 1.0) —
Échelle de guidage sans classifieur.
1.0désactive le guidage (valeur par défaut, et seule valeur pertinente pour le point de contrôle SA3 Medium distillé, dont le CFG est intégré aux poids). Les valeurs> 1.0sont pertinentes pour le point de contrôlestable-audio-3-medium-basenon distillé ; des valeurs plus élevées suivent le prompt plus fidèlement au détriment de la diversité. - negative_prompt (str ou list[str], facultatif) —
Prompt(s) décrivant ce qu’il faut éviter lorsque
guidance_scale > 1.0. Par défaut, une chaîne vide (non conditionnelle) est utilisée lorsqueguidance_scale > 1.0et que ni ce paramètre ni negative_prompt_embeds n’est fourni. Ignoré lorsqueguidance_scale <= 1.0. - num_waveforms_per_prompt (int, par défaut 1) — Nombre de formes d'onde à générer par invite.
- generator (torch.Generator ou list[torch.Generator], facultatif) — Pour une génération déterministe et un re-bruitage reproductible dans la boucle ping-pong.
- latents (torch.Tensor, facultatif) —
Latents de départ pré-générés. Si
None, un tenseur gaussien est échantillonné. - prompt_embeds (torch.Tensor, facultatif) —
Embeddings de texte précalculés
(batch, seq_len, 768). - encoder_attention_mask (torch.LongTensor, facultatif) — Masque booléen pour les embeddings précalculés.
- negative_prompt_embeds (torch.Tensor, facultatif) — Embeddings de texte négatifs précalculés, en alternative à negative_prompt.
- negative_encoder_attention_mask (torch.LongTensor, facultatif) — Masque booléen pour les négatifs précalculés.
- return_dict (bool, par défaut True) — Retourne un AudioPipelineOutput ou un simple tuple.
- callback_on_step_end (Callable, facultatif) — Appelé à la fin de chaque étape de débruitage avec (self, step_idx, timestep, callback_kwargs), où callback_kwargs contient les tenseurs listés dans callback_on_step_end_tensor_inputs. Doit retourner un dictionnaire avec les tenseurs (éventuellement modifiés) à utiliser pour le reste de la boucle.
- callback_on_step_end_tensor_inputs (list[str], par défaut [“latents”]) — Les tenseurs transmis à callback_on_step_end. Doit être un sous-ensemble de self._callback_tensor_inputs.
- output_type (str, par défaut
"pt") —"pt"pour un tenseur PyTorch,"np"pour un tableau NumPy, ou"latent"pour ignorer le décodage et renvoyer les latents bruts.
Retourne
[~pipelines.AudioPipelineOutput] ou tuple
.audios est un tenseur / un tableau de forme (batch * num_waveforms_per_prompt, audio_channels, samples).
Générer de l'audio à partir d'un prompt texte.
Exemples :
>>> import torch
>>> import soundfile as sf
>>> from diffusers import StableAudio3Pipeline
>>> pipe = StableAudio3Pipeline.from_pretrained("stabilityai/stable-audio-3-medium", torch_dtype=torch.float16)
>>> pipe = pipe.to("cuda")
>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
... "A gentle piano melody with soft strings in a concert hall",
... duration=10.0,
... generator=generator,
... ).audios
>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)encode_duration
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Intégrez la valeur de durée dans le vecteur de conditionnement global.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
Paramètres
- prompt — Invite de texte ou liste d'invites. Ignoré lorsque
prompt_embedsest fourni. - device — Appareil cible.
- num_waveforms_per_prompt — Nombre de formes d’onde de sortie à générer par invite ; les tenseurs de conditionnement sont dupliqués en conséquence.
- prompt_embeds — Embeddings de texte précalculés
(batch, seq_len, hidden_size). - encoder_attention_mask — masque booléen
(batch, seq_len)pour les embeddings précalculés ;1= jeton réel,0= bourrage.
Encode les prompts de texte en tenseurs de conditionnement pour l'attention croisée.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
Construisez le contexte de l'attention croisée en ajoutant l'embedding de durée en tant que jeton supplémentaire.
SA3 achemine le conditionneur seconds_total à la fois vers l’entrée globale (AdaLN) et vers le contexte d’attention croisée (cross_attention_cond_ids = ["prompt", "seconds_total"]). L’embedding de durée est concaténé après les jetons de texte, et le masque d’attention est étendu avec une entrée valide supplémentaire.
StableAudio3InpaintPipeline
classe diffusers.StableAudio3InpaintPipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
Paramètres
- vae ([AutoencoderSAME]) — Autoencodeur SAME utilisé pour encoder et décoder les latents audio.
- text_encoder ([~transformers.T5GemmaEncoderModel]) —
Encodeur de texte T5Gemma figé (
google/t5gemma-b-b-ul2). - tokenizer ([~transformers.GemmaTokenizerFast]) — Jetoniseur pour l'encodeur de texte.
- duration_embedder ([StableAudio3DurationEmbedder]) —
Mappe
durationen secondes vers un vecteur de conditionnement global pour AdaLN dans chaque bloc DiT. - transformer ([StableAudio3DiTModel]) — Le DiT de prédiction de vitesse rectifiée du flux.
- scheduler ([FlowMatchEulerDiscreteScheduler]) — Planificateur pour la boucle itérative de débruitage. Le point de contrôle SA3 Medium de production (distillé) utilise stochastic_sampling=True pour exactement 8 étapes ping-pong ; le point de contrôle de base non distillé utilise stochastic_sampling=False pour environ 100 étapes déterministes d’Euler.
Pipeline de restauration audio pour Stable Audio 3.
Partage sa logique de texte vers audio avec [StableAudio3Pipeline] (maintenu synchronisé via # Copied from). Lorsque audio et mask sont fournis, encode l’audio de référence avec l’encodeur SAME figé et injecte masked_latent ∥ mask comme conditionnement local additif dans chaque bloc DiT via le chemin local_add_cond du transformeur
(to_local_embed).
Extension de la signature d’appel (voir __call__) :
audio (torch.Tensor de forme (batch, channels, samples)) :
Forme d’onde audio de référence à vae.config.sampling_rate Hz.
mask (torch.Tensor de forme (batch, 1, latent_length)) :
Masque binaire par trame dans l’espace latent. 1 = conserver l’audio d’origine ; 0 = région à inpainter.
__call__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Nonemask: typing.Optional[torch.Tensor] = Nonemask_start_seconds: typing.Union[float, typing.List[float], NoneType] = Nonemask_end_seconds: typing.Union[float, typing.List[float], NoneType] = Nonenum_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )
Paramètres
- prompt (str ou list[str], facultatif) — Prompt(s) texte.
- duration (float, par défaut 10.0) — Durée de sortie en secondes. Doit correspondre à l'audio de référence.
- audio (torch.Tensor, optionnel) —
Forme d’onde de référence
(batch, channels, samples)àvae.config.sampling_rateHz. Obligatoire pour l’inpainting. - mask (torch.Tensor, optionnel) —
Masque de l’espace latent par image
(batch, 1, L)où 0 = région à inpainter, 1 = conserver. Il faut fournir soitmask, soitmask_start_seconds/mask_end_seconds. - mask_start_seconds (float ou list[float], facultatif) — Temps de début de la région d'inpainting, en secondes.
- mask_end_seconds (float ou list[float], facultatif) —
Temps de fin de la région d'inpainting (doit être associé à
mask_start_seconds). - num_inference_steps (int, facultatif) —
Nombre d’étapes de débruitage. Lorsque la valeur est
None(par défaut), le nombre d’étapes est choisi à partir de la configuration stochastic_sampling du planificateur, conformément à [StableAudio3Pipeline]. - logsnr_min (float, par défaut -6.2) — Valeur minimale de log-SNR pour le calendrier de bruit — correspond au début du calendrier, à forte intensité de bruit.
- logsnr_max (float, par défaut 2.0) — Valeur maximale de log-SNR pour le calendrier de bruit — correspond à l'extrémité à faible bruit du calendrier.
- silence_padding_duration (float, par défaut 0.0) — Marge latente supplémentaire après le contenu cible.
- num_waveforms_per_prompt (int, par défaut 1) — Formes d'onde par invite.
- generator — Générateur aléatoire pour la reproductibilité.
- latents — Bruit de départ pré-généré (
None→ échantillonner un nouveau bruit). - prompt_embeds — Embeddings de texte précalculés.
- encoder_attention_mask — Masque pour les embeddings précalculés.
- return_dict (bool, par défaut True) — Retourne AudioPipelineOutput ou un tuple.
- callback_on_step_end (Callable, facultatif) — Appelé à la fin de chaque étape de débruitage avec (self, step_idx, timestep, callback_kwargs). Doit retourner un dictionnaire contenant les tenseurs (éventuellement modifiés) à utiliser pour le reste de la boucle.
- callback_on_step_end_tensor_inputs (list[str], par défaut [“latents”]) — Les tenseurs transmis à callback_on_step_end. Doit être un sous-ensemble de self._callback_tensor_inputs.
- output_type (str, par défaut
"pt") —"pt"/"np"/"latent".
Générer un audio retouché conditionné par un prompt texte et une référence.
Exemples :
>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3InpaintPipeline
>>> pipe = StableAudio3InpaintPipeline.from_pretrained(
... "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")
>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")
>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
... "A gentle piano melody with soft strings in a concert hall",
... duration=10.0,
... audio=audio,
... mask_start_seconds=4.0,
... mask_end_seconds=6.0,
... generator=generator,
... ).audios
>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)encode_duration
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Intégrez la valeur de durée dans le vecteur de conditionnement global.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
Paramètres
- prompt — Invite de texte ou liste d'invites. Ignoré lorsque
prompt_embedsest fourni. - device — Appareil cible.
- num_waveforms_per_prompt — Nombre de formes d’onde de sortie à générer par invite ; les tenseurs de conditionnement sont dupliqués en conséquence.
- prompt_embeds — Embeddings de texte précalculés
(batch, seq_len, hidden_size). - encoder_attention_mask — masque booléen
(batch, seq_len)pour les embeddings précalculés ;1= jeton réel,0= bourrage.
Encode les prompts de texte en tenseurs de conditionnement pour l'attention croisée.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
Construisez le contexte de l'attention croisée en ajoutant l'embedding de durée en tant que jeton supplémentaire.
SA3 achemine le conditionneur seconds_total à la fois vers l’entrée globale (AdaLN) et vers le contexte d’attention croisée (cross_attention_cond_ids = ["prompt", "seconds_total"]). L’embedding de durée est concaténé après les jetons de texte, et le masque d’attention est étendu avec une entrée valide supplémentaire.
StableAudio3AudioToAudioPipeline
Génère une variation d’un clip audio de référence : l’ensemble de la référence est bruité jusqu’à init_noise_level puis débruité à partir de là, contrairement au conditionnement local additif par image de StableAudio3InpaintPipeline, qui préserve exactement des images spécifiques.
classe diffusers.StableAudio3AudioToAudioPipeline
< source >( vae: AutoencoderSAMEtext_encoder: T5GemmaEncoderModeltokenizer: GemmaTokenizerduration_embedder: StableAudio3DurationEmbeddertransformer: StableAudio3DiTModelscheduler: FlowMatchEulerDiscreteScheduler )
Paramètres
- vae ([AutoencoderSAME]) — Autoencodeur SAME utilisé pour encoder et décoder les latents audio.
- text_encoder ([~transformers.T5GemmaEncoderModel]) —
Encodeur de texte T5Gemma figé (
google/t5gemma-b-b-ul2). - tokenizer ([~transformers.GemmaTokenizerFast]) — Jetoniseur pour l'encodeur de texte.
- duration_embedder ([StableAudio3DurationEmbedder]) —
Mappe
durationen secondes vers un vecteur de conditionnement global pour AdaLN dans chaque bloc DiT. - transformer ([StableAudio3DiTModel]) — Le DiT de prédiction de vitesse rectifiée du flux.
- scheduler ([FlowMatchEulerDiscreteScheduler]) — Planificateur pour la boucle itérative de débruitage. Le point de contrôle SA3 Medium de production (distillé) utilise stochastic_sampling=True pour exactement 8 étapes ping-pong ; le point de contrôle de base non distillé utilise stochastic_sampling=False pour environ 100 étapes déterministes d’Euler.
Pipeline de variation audio-à-audio pour Stable Audio 3.
Partage sa logique de texte vers audio avec [StableAudio3Pipeline] (maintenu synchronisé via # Copied from). Encode l’audio de référence avec l’encodeur SAME figé, le mélange avec du bruit frais selon init_noise_level, puis débruite à partir de là — le signal entier est bruité/débruité globalement, contrairement au conditionnement local additif par frame de [StableAudio3InpaintPipeline].
Extension de la signature d’appel (voir __call__) :
audio (torch.Tensor de forme (batch, channels, samples)) :
Forme d’onde audio de référence à vae.config.sampling_rate Hz.
init_noise_level (float) :
Quantité de bruit à mélanger à la référence avant le débruitage. 1.0 = bruit complet (équivalent à
text-to-audio) ; des valeurs plus faibles conservent davantage la référence.
__call__
< source >( prompt: typing.Union[str, typing.List[str], NoneType] = Noneduration: float = 10.0audio: typing.Optional[torch.Tensor] = Noneinit_noise_level: float = 1.0num_inference_steps: typing.Optional[int] = Nonelogsnr_min: float = -6.2logsnr_max: float = 2.0silence_padding_duration: float = 0.0num_waveforms_per_prompt: int = 1generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonereturn_dict: bool = Truecallback_on_step_end: typing.Optional[typing.Callable[[int, int, dict], dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ['latents']output_type: str = 'pt' )
Paramètres
- prompt (str ou list[str], facultatif) — Prompt(s) texte.
- duration (float, par défaut 10.0) — Durée de sortie en secondes. Doit correspondre à l'audio de référence.
- audio (torch.Tensor, optionnel) —
Forme d’onde de référence
(batch, channels, samples)àvae.config.sampling_rateHz. Obligatoire. - init_noise_level (float, par défaut 1.0) —
Niveau de bruit (dans
(0, 1]) mélangé à la référence avant le débruitage :x_start = (1 - init_noise_level) * reference_latents + init_noise_level * noise.1.0supprime entièrement la référence (équivalent à [StableAudio3Pipeline] ; des valeurs plus faibles conservent progressivement plus de la structure de la référence tout en exécutant le nombre complet d'étapes. - num_inference_steps (int, facultatif) —
Nombre d’étapes de débruitage. Lorsque la valeur est
None(par défaut), le nombre d’étapes est choisi à partir de la configuration stochastic_sampling du planificateur, conformément à [StableAudio3Pipeline]. - logsnr_min (float, par défaut -6.2) — Valeur minimale de log-SNR pour le calendrier de bruit — correspond au début du calendrier, à forte intensité de bruit.
- logsnr_max (float, par défaut 2.0) — Valeur maximale de log-SNR pour le calendrier de bruit — correspond à l'extrémité à faible bruit du calendrier.
- silence_padding_duration (float, par défaut 0.0) — Marge latente supplémentaire après le contenu cible.
- num_waveforms_per_prompt (int, par défaut 1) — Formes d'onde par invite.
- generator — Générateur aléatoire pour la reproductibilité.
- latents — Bruit de départ pré-généré (
None→ échantillonner un nouveau bruit). - prompt_embeds — Embeddings de texte précalculés.
- encoder_attention_mask — Masque pour les embeddings précalculés.
- return_dict (bool, par défaut True) — Retourne AudioPipelineOutput ou un tuple.
- callback_on_step_end (Callable, facultatif) — Appelé à la fin de chaque étape de débruitage avec (self, step_idx, timestep, callback_kwargs). Doit retourner un dictionnaire contenant les tenseurs (éventuellement modifiés) à utiliser pour le reste de la boucle.
- callback_on_step_end_tensor_inputs (list[str], par défaut [“latents”]) — Les tenseurs transmis à callback_on_step_end. Doit être un sous-ensemble de self._callback_tensor_inputs.
- output_type (str, par défaut
"pt") —"pt"/"np"/"latent".
Générer une variation audio conditionnée par un prompt texte et une forme d’onde de référence.
Exemples :
>>> import torch
>>> import soundfile as sf
>>> import torchaudio
>>> from diffusers import StableAudio3AudioToAudioPipeline
>>> pipe = StableAudio3AudioToAudioPipeline.from_pretrained(
... "stabilityai/stable-audio-3-medium", torch_dtype=torch.float16
... )
>>> pipe = pipe.to("cuda")
>>> audio, sr = torchaudio.load("reference.wav")
>>> audio = torchaudio.functional.resample(audio, sr, pipe.vae.config.sampling_rate).unsqueeze(0).to("cuda")
>>> generator = torch.Generator("cuda").manual_seed(0)
>>> audio = pipe(
... "A gentle piano melody with soft strings in a concert hall",
... duration=10.0,
... audio=audio,
... init_noise_level=0.6,
... generator=generator,
... ).audios
>>> sf.write("output.wav", audio[0].T.cpu().float().numpy(), samplerate=pipe.vae.config.sampling_rate)encode_duration
< source >( duration: floatdevice: devicenum_waveforms_per_prompt: intbatch_size: int )
Intégrez la valeur de durée dans le vecteur de conditionnement global.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str], NoneType]device: devicenum_waveforms_per_prompt: intprompt_embeds: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = None )
Paramètres
- prompt — Invite de texte ou liste d'invites. Ignoré lorsque
prompt_embedsest fourni. - device — Appareil cible.
- num_waveforms_per_prompt — Nombre de formes d’onde de sortie à générer par invite ; les tenseurs de conditionnement sont dupliqués en conséquence.
- prompt_embeds — Embeddings de texte précalculés
(batch, seq_len, hidden_size). - encoder_attention_mask — masque booléen
(batch, seq_len)pour les embeddings précalculés ;1= jeton réel,0= bourrage.
Encode les prompts de texte en tenseurs de conditionnement pour l'attention croisée.
prepare_cross_attention
< source >( prompt_embeds: Tensorencoder_attention_mask: Tensorglobal_hidden_states: Tensor )
Construisez le contexte de l'attention croisée en ajoutant l'embedding de durée en tant que jeton supplémentaire.
SA3 achemine le conditionneur seconds_total à la fois vers l’entrée globale (AdaLN) et vers le contexte d’attention croisée (cross_attention_cond_ids = ["prompt", "seconds_total"]). L’embedding de durée est concaténé après les jetons de texte, et le masque d’attention est étendu avec une entrée valide supplémentaire.
StableAudio3DurationEmbedder
classe diffusers.StableAudio3DurationEmbedder
< source >( output_dim: int = 768fourier_dim: int = 256min_val: float = 0.0max_val: float = 384.0min_freq: float = 0.5max_freq: float = 10000.0 )
Paramètres
- output_dim (int, par défaut 768) —
Dimension de l’embedding de sortie. Doit correspondre à
global_cond_dimdu DiT. - fourier_dim (int, par défaut 256) — Dimension interne des caractéristiques de Fourier (doit être paire).
- min_val (float, par défaut 0.0) — Valeur minimale de durée pour le clampage de normalisation.
- max_val (float, par défaut 384.0) —
Valeur maximale de durée pour le clampage de normalisation. Les valeurs supérieures à celle-ci sont limitées. 384 secondes est la limite supérieure de production SA3 Medium pour le conditionneur
seconds_total. - min_freq (float, par défaut 0.5) — Fréquence minimale pour la base de Fourier exponentielle.
- max_freq (float, par défaut 10000.0) — Fréquence maximale pour la base de Fourier exponentielle.
Intègre une valeur de durée (en secondes) dans un vecteur de conditionnement global pour le Stable Audio 3 DiT (utilisé comme entrée AdaLN de global_hidden_states).
Réplique NumberConditioner(fourier_features_type="expo") de l'implémentation de référence SA3.
forward
< source >( seconds: Tensor )