# LongCat-AudioDiT

LongCat-AudioDiT es un modelo de difusión de texto a audio de Meituan LongCat. La integración de diffusers expone una interfaz estándar de [DiffusionPipeline](/docs/diffusers/v0.43.0/es/api/pipelines/overview#diffusers.DiffusionPipeline) para la generación de audio condicionado por texto.

Este pipeline se adaptó de la implementación de referencia de LongCat-AudioDiT: https://github.com/meituan-longcat/LongCat-AudioDiT

Este pipeline admite la carga desde un directorio local o un repositorio de Hugging Face Hub en formato diffusers (que contiene las subcarpetas `text_encoder/`, `transformer/`, `vae/`, `tokenizer/` y `scheduler/`).

## Uso

```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)
```

## Consejos

- `audio_duration_s` es la forma más directa de controlar la duración de la salida.
- Use `generator=torch.Generator("cuda").manual_seed(42)` para hacer que la generación sea reproducible.
- La forma de la salida es `(batch, channels, samples)` - use `.audios[0, 0]` para obtener una sola muestra de audio.
- La salida del pipeline es audio mono (1 canal). Si necesitas estéreo, puedes duplicar el 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)
```

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

#### __call__[[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'])
```

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

**Parámetros:**

prompt (`str` o `list[str]`) : Prompt o prompts que guían la generación de audio.

negative_prompt (`str` o `list[str]`, *opcional*) : Prompt(s) negativo(s) para la guía libre de clasificador.

audio_duration_s (`float`, *opcional*) : Duración objetivo del audio en segundos. Se ignora cuando se proporciona `latents`.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pregenerados de forma `(batch_size, duration, latent_dim)`.

num_inference_steps (`int`, por defecto 16) : Número de pasos de desruido.

guidance_scale (`float`, por defecto 4.0) : Escala de guía para la guía libre de clasificador.

generator (`torch.Generator` o `list[torch.Generator]`, *opcional*) : Generador(es) aleatorio(s).

output_type (`str`, por defecto `"np"`) : Formato de salida: `"np"`, `"pt"` o `"latent"`.

return_dict (`bool`, por defecto `True`) : Si se debe devolver `AudioPipelineOutput`.

callback_on_step_end (`Callable`, *opcional*) : Una función que se llama al final de cada paso de desruido con la pipeline, el índice del paso, el timestep y las entradas de tensor especificadas por `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, por defecto `["latents"]`) : Entradas de Tensor pasadas a `callback_on_step_end`.

**Devuelve:** [AudioPipelineOutput](/docs/diffusers/v0.43.0/es/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) o `tuple`

[AudioPipelineOutput](/docs/diffusers/v0.43.0/es/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) si `return_dict` es True, de lo contrario una `tuple`. Al devolver una tupla, el primer elemento es la forma de onda de audio generada.

Función invocada al llamar a la pipeline para la generación.

Ejemplos:
```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)
```

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

**Parámetros:**

pretrained_model_name_or_path (`str` o `os.PathLike`, *opcional*) : Puede ser:  - Una cadena, el *repo id* (por ejemplo `CompVis/ldm-text2im-large-256`) de un pipeline preentrenado alojado en el Hub. - Una ruta a un *directorio* (por ejemplo `./my_pipeline_directory/`) que contenga los pesos del pipeline guardados usando [save_pretrained()](/docs/diffusers/v0.43.0/es/api/pipelines/overview#diffusers.DiffusionPipeline.save_pretrained).

dtype (`torch.dtype` o `dict[str, Union[str, torch.dtype]]`, *opcional*) : Anula el `torch.dtype` predeterminado y carga el modelo con otro dtype. Para cargar submodelos con un dtype diferente, pasa un `dict` (por ejemplo, `{'transformer': torch.bfloat16, 'vae': torch.float16}`). Establece el dtype predeterminado para los componentes no especificados con `default` (por ejemplo, `{'transformer': torch.bfloat16, 'default': torch.float16}`). Si un componente no está especificado y no se establece un valor predeterminado, se utiliza `torch.float32`.

custom_pipeline (`str`, *opcional*) : > [!WARNING] > 🧪 Esta es una función experimental y puede cambiar en el futuro.  Puede ser:  - Una cadena de caracteres, el *repo id* (por ejemplo `hf-internal-testing/diffusers-dummy-pipeline`) de un pipeline personalizado alojado en el Hub. El repositorio debe contener un archivo llamado pipeline.py que defina el pipeline personalizado. - Una cadena de caracteres, el *nombre del archivo* de un pipeline de la comunidad alojado en GitHub bajo [Community](https://github.com/huggingface/diffusers/tree/main/examples/community). Los nombres de archivo válidos deben coincidir con el nombre del archivo y no con el script del pipeline (`clip_guided_stable_diffusion` en lugar de `clip_guided_stable_diffusion.py`). Los pipelines de la comunidad siempre se cargan desde la rama main actual de GitHub. - Una ruta a un directorio (`./my_pipeline_directory/`) que contiene un pipeline personalizado. El directorio debe contener un archivo llamado `pipeline.py` que defina el pipeline personalizado.  Para obtener más información sobre cómo cargar y crear pipelines personalizados, consulte [Carga y adición de pipelines personalizados](https://huggingface.co/docs/diffusers/using-diffusers/custom_pipeline_overview)

force_download (`bool`, *opcional*, valor predeterminado `False`) : Indica si se debe forzar la (re)descarga de los pesos del modelo y los archivos de configuración, reemplazando las versiones en caché si existen.

cache_dir (`Union[str, os.PathLike]`, *opcional*) : Ruta a un directorio donde se almacena en caché la configuración de un modelo preentrenado descargado si no se utiliza la caché estándar.

proxies (`Dict[str, str]`, *opcional*) : Un diccionario de servidores proxy a utilizar por protocolo o punto de acceso, por ejemplo, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Los proxies se utilizan en cada solicitud.

output_loading_info(`bool`, *opcional*, valor predeterminado `False`) : Indica si se debe devolver también un diccionario que contenga las claves faltantes, las claves inesperadas y los mensajes de error.

local_files_only (`bool`, *opcional*, valor predeterminado `False`) : Indica si se deben cargar únicamente los pesos y archivos de configuración del modelo localmente. Si se establece en `True`, el modelo no se descargará desde el Hub.

token (`str` o *bool*, *opcional*) : El token que se usará como autorización HTTP bearer para archivos remotos. Si es `True`, se utiliza el token generado por `diffusers-cli login` (almacenado en `~/.huggingface`).

revision (`str`, *opcional*, valor predeterminado `"main"`) : La versión específica del modelo que se va a utilizar. Puede ser el nombre de una rama, el nombre de una etiqueta, un id de commit o cualquier identificador permitido por Git.

custom_revision (`str`, *opcional*) : La versión específica del modelo a utilizar. Puede ser un nombre de rama, un nombre de etiqueta o un id de commit similar a `revision` al cargar un pipeline personalizado desde el Hub. Por defecto, se utiliza la última versión estable de 🤗 Diffusers.

mirror (`str`, *opcional*) : Origen de espejo para resolver problemas de accesibilidad si estás descargando un modelo en China. No garantizamos la oportunidad ni la seguridad del origen, y debes consultar el sitio de espejo para obtener más información.

device_map (`str`, *opcional*) : Estrategia que dicta cómo deben colocarse los diferentes componentes de un pipeline en los dispositivos disponibles. Actualmente, solo se admite `device_map` "balanced". Consulta [esto](https://huggingface.co/docs/diffusers/main/en/tutorials/inference_with_big_models#device-placement) para obtener más información.

max_memory (`Dict`, *opcional*) : Un diccionario de identificador de dispositivo para la memoria máxima. Si no se establece, se usará por defecto la memoria máxima disponible para cada GPU y la RAM de CPU disponible.

offload_folder (`str` o `os.PathLike`, *opcional*) : La ruta para descargar los pesos si device_map contiene el valor `"disk"`.

offload_state_dict (`bool`, *opcional*) : Si `True`, descarga temporalmente el state dict de la CPU al disco duro para evitar quedarse sin RAM de CPU si el peso del state dict de la CPU + el shard más grande del checkpoint no cabe. El valor predeterminado es `True` cuando hay alguna descarga al disco.

low_cpu_mem_usage (`bool`, *opcional*, por defecto `True` si la versión de torch >= 1.9.0, en caso contrario `False`) : Acelera la carga del modelo cargando solo los pesos preentrenados y no inicializando los pesos. Esto también intenta no usar más de 1x el tamaño del modelo en la memoria de CPU (incluida la memoria pico) mientras se carga el modelo. Solo se admite para PyTorch >= 1.9.0. Si estás usando una versión anterior de PyTorch, establecer este argumento en `True` generará un error.

use_safetensors (`bool`, *opcional*, valor predeterminado `None`) : Si se establece en `None`, se descargan los pesos de safetensors si están disponibles **y** si la biblioteca safetensors está instalada. Si se establece en `True`, el modelo se carga forzosamente desde los pesos de safetensors. Si se establece en `False`, no se cargan los pesos de safetensors.

use_onnx (`bool`, *opcional*, valor predeterminado `None`) : Si se establece en `True`, los pesos de ONNX siempre se descargarán si están presentes. Si se establece en `False`, los pesos de ONNX nunca se descargarán. De forma predeterminada, `use_onnx` toma el valor del atributo de clase `_is_onnx`, que es `False` para los pipelines no-ONNX y `True` para los pipelines ONNX. Los pesos de ONNX incluyen tanto los archivos que terminan en `.onnx` como en `.pb`.

kwargs (resto del diccionario de argumentos de palabra clave, *opcional*) : Se puede usar para sobrescribir las variables de carga y guardado (los componentes de pipeline de la clase de pipeline específica). Los componentes sobrescritos se pasan directamente al método `__init__` de los pipelines. Consulte el ejemplo siguiente para obtener más información.

variant (`str`, *opcional*) : Carga los pesos desde un nombre de archivo de variante especificado, como `"fp16"` o `"ema"`.

disable_mmap ('bool', *opcional*, valor predeterminado 'False') : Si se debe deshabilitar mmap al cargar un modelo de Safetensors. Esta opción puede ofrecer un mejor rendimiento cuando el modelo está en una unidad de red o en un disco duro, que pueden no manejar bien la naturaleza de búsquedas aleatorias de mmap.

Instanciar un pipeline de difusión de PyTorch a partir de pesos de pipeline preentrenados.

El pipeline se configura en modo de evaluación (`model.eval()`) de forma predeterminada.

Si obtienes el siguiente mensaje de error, necesitas ajustar los pesos para tu tarea de destino:

```
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] > Para usar modelos privados o [gated](https://huggingface.co/docs/hub/models-gated#gated-models), inicia sesión
con `hf > auth login`.

Ejemplos:

```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
```