# Stable Audio 3 Stable Audio 3 (SA3) est un modèle de texte vers audio de [Stability AI](https://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](/docs/diffusers/v0.43.0/fr/api/pipelines/stable_audio_3#diffusers.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](/docs/diffusers/v0.43.0/fr/api/models/autoencoder_same#diffusers.AutoencoderSAME). Les deux points de contrôle utilisent [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/fr/api/schedulers/flow_match_euler_discrete#diffusers.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 valeur appropriée si vous ne le définissez pas. Ne le passez que pour l’écraser. Base de code originale : [Stability-AI/stable-audio-3](https://github.com/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` : ```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` est un dépôt **restreint**. Exécutez `hf auth login` avec un compte ayant accès avant de convertir, 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`](https://pypi.org/project/soundfile/) avec `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) ``` Le pipeline est également enregistré avec [AutoPipelineForText2Audio](/docs/diffusers/v0.43.0/fr/api/pipelines/auto_pipeline#diffusers.AutoPipelineForText2Audio), qui résout automatiquement le point de contrôle vers `StableAudio3Pipeline` : ```py from diffusers import AutoPipelineForText2Audio pipe = AutoPipelineForText2Audio.from_pretrained("/tmp/sa3-diffusers-euler", torch_dtype=torch.float32) ``` > [!NOTE] > Les exemples utilisent un chemin local car `stabilityai/stable-audio-3-medium` et `stable-audio-3-medium-base` ne 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.float32` sur CPU ou MPS (Apple Silicon) — `torch.float16` sur 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. Laissez `guidance_scale=1.0` (la valeur par défaut) et ne passez pas de `negative_prompt` pour 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éfaut `0.0`) ajoute une marge de silence à la fin de la séquence latente. Laissez cette valeur à `0.0` sauf 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 plus silencieux. * Définissez `num_waveforms_per_prompt > 1` pour générer plusieurs clips par invite. ## StableAudio3Pipeline[[diffusers.StableAudio3Pipeline]] #### diffusers.StableAudio3Pipeline[[diffusers.StableAudio3Pipeline]] ```python diffusers.StableAudio3Pipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L157) **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*]) : Tokenizer pour l'encodeur de texte. duration_embedder ([*StableAudio3DurationEmbedder*]) : Convertit `duration` en secondes en un vecteur de conditionnement global pour AdaLN dans chaque bloc DiT. transformer ([*StableAudio3DiTModel*]) : Le DiT de prédiction de vitesse rectifiée. 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. #### __appel__[[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') ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L398) **Paramètres :** prompt (*str* ou *list[str]*, *facultatif*) : Prompt(s) de texte. Passez `prompt_embeds` à la place pour ignorer la tokenisation et l’encodage. duration (*float*, valeur par défaut 10.0) : Durée de sortie demandée, en secondes. num_inference_steps (*int*, *optionnel*) : Nombre d'étapes de débruitage. Lorsque `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é). Passez une valeur explicite pour outrepasser ce comportement. logsnr_min (*float*, valeur par défaut : -6.2) : Valeur minimale de log-SNR pour le plan de bruit — correspond au début du plan, à forte intensité de bruit. logsnr_max (*float*, valeur par défaut 2.0) : Valeur maximale du log-SNR pour le plan de bruit — correspond à l'extrémité à faible bruit du plan. silence_padding_duration (*float*, valeur par défaut 0.0) : Nombre de 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 pour correspondre à *duration*. La valeur par défaut est 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*, valeur par défaut 1.0) : Échelle du guidage sans classifieur. `1.0` désactive le guidage (valeur par défaut, et seule valeur pertinente pour le point de contrôle distillé SA3 Medium, dont le CFG est intégré aux poids). Les valeurs `> 1.0` sont significatives pour le point de contrôle non distillé `stable-audio-3-medium-base` ; 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 lorsque `guidance_scale > 1.0` et que ni ce paramètre ni *negative_prompt_embeds* n'est fourni. Ignoré lorsque `guidance_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 passés à *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 retourner 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 : ```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) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L289) **Paramètres :** duration : Durée en secondes, appliquée à chaque échantillon du lot. device : Appareil cible. num_waveforms_per_prompt : Facteur de tuilage. batch_size : Nombre de prompts. **Retourne :** tenseur `(batch * num_waveforms_per_prompt, output_dim)`. Intégrez la valeur de durée dans le vecteur de conditionnement 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) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L223) **Paramètres :** prompt : Invite de texte ou liste d'invites. Ignoré lorsque `prompt_embeds` est 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. **Retourne :** `(prompt_embeds, encoder_attention_mask)` tous deux tuilés en `batch * num_waveforms_per_prompt`. Encode les prompts de texte en tenseurs de conditionnement pour l'attention croisée. #### prepare_cross_attention[[diffusers.StableAudio3Pipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3.py#L313) **Retourne :** `(context, context_mask)` de formes `(batch, T_text + 1, dim)` et `(batch, T_text + 1)`. 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 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[[diffusers.StableAudio3InpaintPipeline]] #### diffusers.StableAudio3InpaintPipeline[[diffusers.StableAudio3InpaintPipeline]] ```python diffusers.StableAudio3InpaintPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L158) **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*]) : Tokenizer pour l'encodeur de texte. duration_embedder ([*StableAudio3DurationEmbedder*]) : Convertit `duration` en secondes en un vecteur de conditionnement global pour AdaLN dans chaque bloc DiT. transformer ([*StableAudio3DiTModel*]) : Le DiT de prédiction de vitesse rectifiée. 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 transformer (`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. #### __appel__[[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') ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L455) **Paramètres :** prompt (*str* ou *list[str]*, *facultatif*) : Prompt(s) de texte. duration (*float*, valeur par défaut 10.0) : Durée de sortie en secondes. Doit correspondre à l'audio de référence. audio (*torch.Tensor*, *facultatif*) : Forme d'onde de référence `(batch, channels, samples)` à `vae.config.sampling_rate` Hz. Obligatoire pour l'inpainting. mask (*torch.Tensor*, *facultatif*) : Masque de l’espace latent par image `(batch, 1, L)` où 0 = région à inpainter, 1 = conserver. Il faut fournir soit `mask`, soit `mask_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*) : Heure(s) de fin de la région d'inpainting (doit être appariée avec `mask_start_seconds`). num_inference_steps (*int*, *optionnel*) : Nombre d'étapes de débruitage. Lorsque `None` (par défaut), le nombre d'étapes est choisi à partir de la configuration *stochastic_sampling* du planificateur, conformément à [*StableAudio3Pipeline*]. logsnr_min (*float*, valeur par défaut : -6.2) : Valeur minimale de log-SNR pour le plan de bruit — correspond au début du plan, à forte intensité de bruit. logsnr_max (*float*, valeur par défaut 2.0) : Valeur maximale du log-SNR pour le plan de bruit — correspond à l'extrémité à faible bruit du plan. silence_padding_duration (*float*, valeur par défaut 0.0) : Marge latente supplémentaire après le contenu cible. num_waveforms_per_prompt (*int*, par défaut 1) : Nombre de formes d'onde par invite. generator : RNG 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*) : Retourner *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 passés à *callback_on_step_end*. Doit être un sous-ensemble de *self._callback_tensor_inputs*. output_type (*str*, par défaut `"pt"`) : `"pt"` / `"np"` / `"latent"`. **Retourne :** [*~pipelines.AudioPipelineOutput*] avec `.audios`. Générer un audio retouché conditionné par un prompt texte et une référence. Exemples : ```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) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L290) **Paramètres :** duration : Durée en secondes, appliquée à chaque échantillon du lot. device : Appareil cible. num_waveforms_per_prompt : Facteur de tuilage. batch_size : Nombre de prompts. **Retourne :** tenseur `(batch * num_waveforms_per_prompt, output_dim)`. Intégrez la valeur de durée dans le vecteur de conditionnement 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) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L223) **Paramètres :** prompt : Invite de texte ou liste d'invites. Ignoré lorsque `prompt_embeds` est 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. **Retourne :** `(prompt_embeds, encoder_attention_mask)` tous deux tuilés en `batch * num_waveforms_per_prompt`. Encode les prompts de texte en tenseurs de conditionnement pour l'attention croisée. #### prepare_cross_attention[[diffusers.StableAudio3InpaintPipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_inpaint.py#L315) **Retourne :** `(context, context_mask)` de formes `(batch, T_text + 1, dim)` et `(batch, T_text + 1)`. 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 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[[diffusers.StableAudio3AudioToAudioPipeline]] Génère une variation d'un clip audio de référence : l'intégralité de la référence est bruitée jusqu'à `init_noise_level` puis débruitée à partir de là, contrairement au conditionnement local additif par image de [StableAudio3InpaintPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/stable_audio_3#diffusers.StableAudio3InpaintPipeline), qui préserve exactement des images spécifiques. #### diffusers.StableAudio3AudioToAudioPipeline[[diffusers.StableAudio3AudioToAudioPipeline]] ```python diffusers.StableAudio3AudioToAudioPipeline(vae: AutoencoderSAME, text_encoder: T5GemmaEncoderModel, tokenizer: GemmaTokenizer, duration_embedder: StableAudio3DurationEmbedder, transformer: StableAudio3DiTModel, scheduler: FlowMatchEulerDiscreteScheduler) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L154) **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*]) : Tokenizer pour l'encodeur de texte. duration_embedder ([*StableAudio3DurationEmbedder*]) : Convertit `duration` en secondes en un vecteur de conditionnement global pour AdaLN dans chaque bloc DiT. transformer ([*StableAudio3DiTModel*]) : Le DiT de prédiction de vitesse rectifiée. 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. #### __appel__[[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') ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L424) **Paramètres :** prompt (*str* ou *list[str]*, *facultatif*) : Prompt(s) de texte. duration (*float*, valeur par défaut 10.0) : Durée de sortie en secondes. Doit correspondre à l'audio de référence. audio (*torch.Tensor*, *facultatif*) : Forme d’onde de référence `(batch, channels, samples)` à `vae.config.sampling_rate` Hz. 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.0` supprime 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*, *optionnel*) : Nombre d'étapes de débruitage. Lorsque `None` (par défaut), le nombre d'étapes est choisi à partir de la configuration *stochastic_sampling* du planificateur, conformément à [*StableAudio3Pipeline*]. logsnr_min (*float*, valeur par défaut : -6.2) : Valeur minimale de log-SNR pour le plan de bruit — correspond au début du plan, à forte intensité de bruit. logsnr_max (*float*, valeur par défaut 2.0) : Valeur maximale du log-SNR pour le plan de bruit — correspond à l'extrémité à faible bruit du plan. silence_padding_duration (*float*, valeur par défaut 0.0) : Marge latente supplémentaire après le contenu cible. num_waveforms_per_prompt (*int*, par défaut 1) : Nombre de formes d'onde par invite. generator : RNG 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*) : Retourner *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 passés à *callback_on_step_end*. Doit être un sous-ensemble de *self._callback_tensor_inputs*. output_type (*str*, par défaut `"pt"`) : `"pt"` / `"np"` / `"latent"`. **Retourne :** [*~pipelines.AudioPipelineOutput*] avec `.audios`. Générer une variation audio conditionnée par un prompt texte et une forme d’onde de référence. Exemples : ```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) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L287) **Paramètres :** duration : Durée en secondes, appliquée à chaque échantillon du lot. device : Appareil cible. num_waveforms_per_prompt : Facteur de tuilage. batch_size : Nombre de prompts. **Retourne :** tenseur `(batch * num_waveforms_per_prompt, output_dim)`. Intégrez la valeur de durée dans le vecteur de conditionnement 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) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L220) **Paramètres :** prompt : Invite de texte ou liste d'invites. Ignoré lorsque `prompt_embeds` est 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. **Retourne :** `(prompt_embeds, encoder_attention_mask)` tous deux tuilés en `batch * num_waveforms_per_prompt`. Encode les prompts de texte en tenseurs de conditionnement pour l'attention croisée. #### prepare_cross_attention[[diffusers.StableAudio3AudioToAudioPipeline.prepare_cross_attention]] ```python prepare_cross_attention(prompt_embeds: Tensor, encoder_attention_mask: Tensor, global_hidden_states: Tensor) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/stable_audio_3/pipeline_stable_audio_3_audio2audio.py#L312) **Retourne :** `(context, context_mask)` de formes `(batch, T_text + 1, dim)` et `(batch, T_text + 1)`. 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 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[[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) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L43) **Paramètres :** output_dim (*int*, par défaut 768) : Dimension de l'embedding de sortie. Doit correspondre à `global_cond_dim` du DiT. fourier_dim (*int*, par défaut 256) : Dimension interne des caractéristiques de Fourier (doit être paire). min_val (*float*, valeur par défaut 0.0) : Valeur minimale de durée pour le clampage de la normalisation. max_val (*float*, valeur par défaut 384.0) : Valeur maximale de durée pour le clampage de normalisation. Les valeurs supérieures à ce seuil sont limitées. 384 secondes est la borne 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*, valeur 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[[diffusers.StableAudio3DurationEmbedder.forward]] ```python forward(seconds: Tensor) ``` [Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_stable_audio_3.py#L90) **Paramètres :** seconds (`torch.Tensor` de forme `(batch,)`) : Durées en secondes. **Retourne :** `torch.Tensor` de forme `(batch, output_dim)` — embeddings de durée.