# LongCat-AudioDiT

LongCat-AudioDiT est un modèle de diffusion texte-vers-audio de Meituan LongCat. L'intégration diffusers expose une interface standard [DiffusionPipeline](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline) pour la génération d'audio conditionnée par le texte.

Ce pipeline a été adapté de l'implémentation de référence LongCat-AudioDiT : https://github.com/meituan-longcat/LongCat-AudioDiT

Ce pipeline prend en charge le chargement depuis un répertoire local ou un dépôt du Hugging Face Hub au format diffusers (contenant les sous-dossiers `text_encoder/`, `transformer/`, `vae/`, `tokenizer/` et `scheduler/`).

## Utilisation

```py
import soundfile as sf
import torch
from diffusers import LongCatAudioDiTPipeline

pipeline = LongCatAudioDiTPipeline.from_pretrained(
    "ruixiangma/LongCat-AudioDiT-1B-Diffusers",
    dtype=torch.float16,
)
pipeline = pipeline.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A calm ocean wave ambience with soft wind in the background."
audio = pipeline(
    prompt,
    audio_duration_s=5.0,
    num_inference_steps=16,
    guidance_scale=4.0,
    generator=torch.Generator("cuda").manual_seed(42),
).audios[0, 0]

sf.write("longcat.wav", audio, pipeline.sample_rate)
```

## Astuces

- `audio_duration_s` est la méthode la plus directe pour contrôler la durée de la sortie.
- Utilisez `generator=torch.Generator("cuda").manual_seed(42)` pour rendre la génération reproductible.
- La forme de la sortie est `(batch, channels, samples)` - utilisez `.audios[0, 0]` pour obtenir un échantillon audio unique.
- Le pipeline sort un audio mono (1 canal). Si vous avez besoin du stéréo, vous pouvez dupliquer le canal : `audio.unsqueeze(0).repeat(1, 2, 1)`.

## LongCatAudioDiTPipeline[[diffusers.LongCatAudioDiTPipeline]]

#### diffusers.LongCatAudioDiTPipeline[[diffusers.LongCatAudioDiTPipeline]]

```python
diffusers.LongCatAudioDiTPipeline(vae: LongCatAudioDiTVae, text_encoder: UMT5EncoderModel, tokenizer: PreTrainedTokenizerBase, transformer: LongCatAudioDiTTransformer, scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = None)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/longcat_audio_dit/pipeline_longcat_audio_dit.py#L99)

#### __appel__[[diffusers.LongCatAudioDiTPipeline.__call__]]

```python
__call__(prompt: str | list[str], negative_prompt: str | list[str] | None = None, audio_duration_s: float | None = None, latents: typing.Optional[torch.Tensor] = None, num_inference_steps: int = 16, guidance_scale: float = 4.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'np', return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/longcat_audio_dit/pipeline_longcat_audio_dit.py#L219)

**Paramètres :**

prompt (`str` ou `list[str]`) : Prompt ou prompts qui guident la génération audio.

negative_prompt (`str` ou `list[str]`, *facultatif*) : Prompt(s) négatif(s) pour le guidage sans classifieur.

audio_duration_s (`float`, *facultatif*) : Durée cible de l'audio en secondes. Ignoré lorsque `latents` est fourni.

latents (`torch.Tensor`, *facultatif*) : Latents bruités pré-générés de forme `(batch_size, duration, latent_dim)`.

num_inference_steps (`int`, par défaut 16) : Nombre d'étapes de débruitage.

guidance_scale (`float`, par défaut 4.0) : Échelle de guidage pour le guidage sans classifieur.

generator (`torch.Generator` ou `list[torch.Generator]`, *facultatif*) : Générateur(s) aléatoire(s).

output_type (`str`, par défaut `"np"`) : Format de sortie : `"np"`, `"pt"` ou `"latent"`.

return_dict (`bool`, par défaut `True`) : Indique s'il faut retourner `AudioPipelineOutput`.

callback_on_step_end (`Callable`, *facultatif*) : une fonction appelée à la fin de chaque étape de débruitage avec le pipeline, l'indice d'étape, le timestep et les entrées tensorielles spécifiées par `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, par défaut `["latents"]`) : Entrées Tensor passées à `callback_on_step_end`.

**Retourne :** [AudioPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) ou `tuple`

[AudioPipelineOutput](/docs/diffusers/v0.43.0/fr/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) si `return_dict` est True, sinon un `tuple`. En cas de retour d'un tuple, le premier élément est la forme d'onde audio générée.

Fonction appelée lors de l'appel du pipeline pour la génération.

Exemples :
```py
>>> import soundfile as sf
>>> import torch
>>> from diffusers import LongCatAudioDiTPipeline

>>> pipe = LongCatAudioDiTPipeline.from_pretrained("ruixiangma/LongCat-AudioDiT-1B-Diffusers")
>>> pipe.to("cuda")

>>> prompt = "A calm ocean wave ambience with soft wind in the background."
>>> audio = pipe(
...     prompt,
...     audio_duration_s=5.0,
...     num_inference_steps=20,
...     guidance_scale=4.0,
...     generator=torch.Generator("cuda").manual_seed(42),
... ).audios[0, 0]
>>> sf.write("output.wav", audio, pipe.sample_rate)
```

#### from_pretrained[[diffusers.LongCatAudioDiTPipeline.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, **kwargs)
```

[Source](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L638)

**Paramètres :**

pretrained_model_name_or_path (`str` ou `os.PathLike`, *facultatif*) : Peut être : - Une chaîne de caractères, l'*identifiant du dépôt* (par exemple `CompVis/ldm-text2im-large-256`) d'un pipeline pré-entraîné hébergé sur le Hub. - Un chemin vers un *dossier* (par exemple `./my_pipeline_directory/`) contenant les poids du pipeline enregistrés à l'aide de [save_pretrained()](/docs/diffusers/v0.43.0/fr/api/pipelines/overview#diffusers.DiffusionPipeline.save_pretrained).

dtype (`torch.dtype` ou `dict[str, Union[str, torch.dtype]]`, *facultatif*) : Remplace le `torch.dtype` par défaut et charge le modèle avec un autre dtype. Pour charger des sous-modèles avec des dtypes différents, passez un `dict` (par exemple `{'transformer': torch.bfloat16, 'vae': torch.float16}`). Définissez le dtype par défaut pour les composants non spécifiés avec `default` (par exemple `{'transformer': torch.bfloat16, 'default': torch.float16}`). Si un composant n'est pas spécifié et qu'aucun défaut n'est défini, `torch.float32` est utilisé.

custom_pipeline (`str`, *facultatif*) : > [!WARNING] > 🧪 Il s'agit d'une fonctionnalité expérimentale qui peut évoluer à l'avenir.  Peut être :  - Une chaîne de caractères, l'*identifiant du dépôt* (par exemple `hf-internal-testing/diffusers-dummy-pipeline`) d'un pipeline personnalisé hébergé sur le Hub. Le dépôt doit contenir un fichier nommé pipeline.py qui définit le pipeline personnalisé. - Une chaîne de caractères, le *nom du fichier* d'un pipeline communautaire hébergé sur GitHub sous [Community](https://github.com/huggingface/diffusers/tree/main/examples/community). Les noms de fichiers valides doivent correspondre au nom du fichier et non au script du pipeline (`clip_guided_stable_diffusion` au lieu de `clip_guided_stable_diffusion.py`). Les pipelines communautaires sont toujours chargés depuis la branche main actuelle de GitHub. - Un chemin vers un répertoire (`./my_pipeline_directory/`) contenant un pipeline personnalisé. Le répertoire doit contenir un fichier nommé `pipeline.py` qui définit le pipeline personnalisé.  Pour plus d'informations sur la manière de charger et de créer des pipelines personnalisés, veuillez consulter [Charger et ajouter des pipelines personnalisés](https://huggingface.co/docs/diffusers/using-diffusers/custom_pipeline_overview)

force_download (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut forcer le (re)téléchargement des poids du modèle et des fichiers de configuration, en ignorant les versions mises en cache si elles existent.

cache_dir (`Union[str, os.PathLike]`, *facultatif*) : Chemin vers un répertoire où la configuration d'un modèle pré-entraîné téléchargé est mise en cache si le cache standard n'est pas utilisé.

proxies (`Dict[str, str]`, *facultatif*) : Un dictionnaire de serveurs proxy à utiliser par protocole ou point de terminaison, par exemple, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Les proxys sont utilisés pour chaque requête.

output_loading_info(`bool`, *facultatif*, valeur par défaut `False`) : Indique s'il faut également retourner un dictionnaire contenant les clés manquantes, les clés inattendues et les messages d'erreur.

local_files_only (`bool`, *facultatif*, par défaut `False`) : Indique s'il faut charger uniquement les poids et les fichiers de configuration du modèle locaux. Si défini sur `True`, le modèle ne sera pas téléchargé depuis le Hub.

token (`str` ou *bool*, *facultatif*) : Le jeton à utiliser comme autorisation bearer HTTP pour les fichiers distants. Si `True`, le jeton généré par `diffusers-cli login` (stocké dans `~/.huggingface`) est utilisé.

revision (`str`, *facultatif*, par défaut `"main"`) : La version spécifique du modèle à utiliser. Il peut s'agir d'un nom de branche, d'un nom de tag, d'un identifiant de commit ou de tout identifiant autorisé par Git.

custom_revision (`str`, *facultatif*) : La version spécifique du modèle à utiliser. Il peut s'agir d'un nom de branche, d'un nom de tag ou d'un identifiant de commit, similaire à `revision` lors du chargement d'un pipeline personnalisé depuis le Hub. Par défaut, la dernière version stable de 🤗 Diffusers est utilisée.

mirror (`str`, *facultatif*) : Source miroir pour résoudre les problèmes d’accessibilité lors du téléchargement d’un modèle en Chine. Nous ne garantissons ni la réactivité ni la sécurité de la source ; veuillez consulter le site miroir pour plus d’informations.

device_map (`str`, *facultatif*) : Stratégie qui définit comment les différents composants d'un pipeline doivent être répartis sur les appareils disponibles. Actuellement, seul `device_map` "balanced" est pris en charge. Consultez [ce lien](https://huggingface.co/docs/diffusers/main/en/tutorials/inference_with_big_models#device-placement) pour en savoir plus.

max_memory (`Dict`, *facultatif*) : Un identifiant de dictionnaire de périphérique pour la mémoire maximale. Par défaut, la valeur est la mémoire maximale disponible pour chaque GPU et la RAM CPU disponible si non définie.

offload_folder (`str` ou `os.PathLike`, *facultatif*) : Le chemin pour décharger les poids si device_map contient la valeur `"disk"`.

offload_state_dict (`bool`, *facultatif*) : Si `True`, décharge temporairement le dictionnaire d'état CPU sur le disque dur pour éviter d'épuiser la RAM CPU si le poids du dictionnaire d'état CPU + le plus grand fragment du point de contrôle ne tient pas. La valeur par défaut est `True` lorsqu'il y a une décharge sur disque.

low_cpu_mem_usage (`bool`, *facultatif*, par défaut `True` si la version de torch est >= 1.9.0, sinon `False`) : Accélère le chargement du modèle en ne chargeant que les poids préentraînés et sans initialiser les poids. Cela tente également de ne pas utiliser plus de 1 fois la taille du modèle en mémoire CPU (y compris la mémoire de pointe) lors du chargement du modèle. Pris en charge uniquement pour PyTorch >= 1.9.0. Si vous utilisez une version plus ancienne de PyTorch, définir cet argument sur `True` déclenchera une erreur.

use_safetensors (`bool`, *facultatif*, valeur par défaut `None`) : Si défini sur `None`, les poids safetensors sont téléchargés s'ils sont disponibles **et** si la bibliothèque safetensors est installée. Si défini sur `True`, le modèle est chargé de force à partir des poids safetensors. Si défini sur `False`, les poids safetensors ne sont pas chargés.

use_onnx (`bool`, *facultatif*, valeur par défaut `None`) : Si défini sur `True`, les poids ONNX seront toujours téléchargés s’ils sont présents. Si défini sur `False`, les poids ONNX ne seront jamais téléchargés. Par défaut, `use_onnx` prend la valeur de l’attribut de classe `_is_onnx`, qui est `False` pour les pipelines non-ONNX et `True` pour les pipelines ONNX. Les poids ONNX incluent à la fois les fichiers se terminant par `.onnx` et `.pb`.

kwargs (reste du dictionnaire des arguments par mot-clé, *facultatif*) : peut être utilisé pour écraser les variables de chargement et de sauvegarde (les composants du pipeline de la classe de pipeline spécifique). Les composants écrasés sont transmis directement à la méthode `__init__` des pipelines. Voir l’exemple ci-dessous pour plus d’informations.

variant (`str`, *facultatif*) : Charge les poids depuis un nom de fichier de variante spécifié, tel que `"fp16"` ou `"ema"`.

disable_mmap ('bool', *facultatif*, valeur par défaut 'False') : Indique s'il faut désactiver mmap lors du chargement d'un modèle Safetensors. Cette option peut offrir de meilleures performances lorsque le modèle est situé sur un montage réseau ou un disque dur, qui peuvent ne pas gérer correctement les accès aléatoires (seek) de mmap.

Instanciez un pipeline de diffusion PyTorch à partir de poids de pipeline pré-entraînés.

Le pipeline est défini en mode évaluation (`model.eval()`) par défaut.

Si vous obtenez le message d’erreur ci-dessous, vous devez affiner les poids pour votre tâche en aval :

```
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
```

> [!TIP] > Pour utiliser des modèles privés ou [gated](https://huggingface.co/docs/hub/models-gated#gated-models), connectez-vous
avec `hf > auth login`.

Exemples :

```py
>>> from diffusers import DiffusionPipeline

>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")

>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")

>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler

>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = scheduler
```