# LongCat-AudioDiT

LongCat-AudioDiT é um modelo de difusão de texto para áudio da Meituan LongCat. A integração com diffusers expõe uma interface padrão [DiffusionPipeline](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline) para geração de áudio condicionada por texto.

Este pipeline foi adaptado da implementação de referência do LongCat-AudioDiT: https://github.com/meituan-longcat/LongCat-AudioDiT

Este pipeline suporta o carregamento a partir de um diretório local ou de um repositório do Hugging Face Hub no formato diffusers (contendo as subpastas `text_encoder/`, `transformer/`, `vae/`, `tokenizer/` e `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)
```

## Dicas

- `audio_duration_s` é a maneira mais direta de controlar a duração da saída.
- Use `generator=torch.Generator("cuda").manual_seed(42)` para tornar a geração reproduzível.
- A forma de saída é `(batch, channels, samples)` - use `.audios[0, 0]` para obter uma única amostra de áudio.
- O pipeline gera áudio mono (1 canal). Se você precisar de estéreo, pode duplicar o 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)
```

[Fonte](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'])
```

[Fonte](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` ou `list[str]`) : Prompt ou prompts que orientam a geração de áudio.

negative_prompt (`str` ou `list[str]`, *opcional*) : Prompt(s) negativo(s) para classifier-free guidance.

audio_duration_s (`float`, *opcional*) : Duração do áudio em segundos. Ignorado quando `latents` é fornecido.

latents (`torch.Tensor`, *opcional*) : Latentes ruidosos pré-gerados com forma `(batch_size, duration, latent_dim)`.

num_inference_steps (`int`, padrão 16) : Número de etapas de desruidamento.

guidance_scale (`float`, padrão 4.0) : Escala de orientação para orientação livre de classificador.

generator (`torch.Generator` ou `list[torch.Generator]`, *opcional*) : Gerador(es) aleatório(s).

output_type (`str`, padrão `"np"`) : Formato de saída: `"np"`, `"pt"` ou `"latent"`.

return_dict (`bool`, padrão `True`) : Se deve retornar `AudioPipelineOutput`.

callback_on_step_end (`Callable`, *opcional*) : Uma função chamada no final de cada etapa de desruidamento com o pipeline, índice da etapa, timestep e entradas de tensor especificadas por `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, padrão `["latents"]`) : Entradas de Tensor passadas para `callback_on_step_end`.

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

[AudioPipelineOutput](/docs/diffusers/v0.43.0/pt/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) se `return_dict` for True, caso contrário, uma `tuple`. Ao retornar uma tupla, o primeiro elemento é a forma de onda de áudio gerada.

Função invocada ao chamar o pipeline para geração.

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

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

**Parâmetros:**

pretrained_model_name_or_path (`str` ou `os.PathLike`, *opcional*) : Pode ser:  - Uma string, o *repo id* (por exemplo `CompVis/ldm-text2im-large-256`) de um pipeline pré-treinado hospedado no Hub. - Um caminho para um *diretório* (por exemplo `./my_pipeline_directory/`) contendo pesos de pipeline salvos usando [save_pretrained()](/docs/diffusers/v0.43.0/pt/api/pipelines/overview#diffusers.DiffusionPipeline.save_pretrained).

dtype (`torch.dtype` ou `dict[str, Union[str, torch.dtype]]`, *opcional*) : Substitui o `torch.dtype` padrão e carrega o modelo com outro dtype. Para carregar submodelos com dtypes diferentes, passe um `dict` (por exemplo, `{'transformer': torch.bfloat16, 'vae': torch.float16}`). Defina o dtype padrão para componentes não especificados com `default` (por exemplo, `{'transformer': torch.bfloat16, 'default': torch.float16}`). Se um componente não for especificado e nenhum padrão for definido, `torch.float32` será usado.

custom_pipeline (`str`, *opcional*) : > [!WARNING] > 🧪 Este é um recurso experimental e pode mudar no futuro.  Pode ser:  - Uma string, o *repo id* (por exemplo `hf-internal-testing/diffusers-dummy-pipeline`) de um pipeline personalizado hospedado no Hub. O repositório deve conter um arquivo chamado pipeline.py que define o pipeline personalizado. - Uma string, o *nome do arquivo* de um pipeline da comunidade hospedado no GitHub sob [Community](https://github.com/huggingface/diffusers/tree/main/examples/community). Os nomes de arquivo válidos devem corresponder ao nome do arquivo e não ao script do pipeline (`clip_guided_stable_diffusion` em vez de `clip_guided_stable_diffusion.py`). Os pipelines da comunidade são sempre carregados da branch main atual do GitHub. - Um caminho para um diretório (`./my_pipeline_directory/`) contendo um pipeline personalizado. O diretório deve conter um arquivo chamado `pipeline.py` que define o pipeline personalizado.  Para mais informações sobre como carregar e criar pipelines personalizados, consulte [Carregando e Adicionando Pipelines Personalizados](https://huggingface.co/docs/diffusers/using-diffusers/custom_pipeline_overview)

force_download (`bool`, *opcional*, padrão `False`) : Se deve forçar o (re-)download dos pesos do modelo e dos arquivos de configuração, sobrescrevendo as versões em cache, caso existam.

cache_dir (`Union[str, os.PathLike]`, *opcional*) : Caminho para um diretório onde a configuração de um modelo pré-treinado baixado é armazenada em cache, caso o cache padrão não seja utilizado.

proxies (`Dict[str, str]`, *opcional*) : Um dicionário de servidores proxy a serem usados por protocolo ou endpoint, por exemplo, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Os proxies são usados em cada solicitação.

output_loading_info(`bool`, *opcional*, padrão `False`) : Indica se deve ou não retornar também um dicionário contendo chaves ausentes, chaves inesperadas e mensagens de erro.

local_files_only (`bool`, *opcional*, padrão `False`) : Se deve carregar apenas os pesos e os arquivos de configuração do modelo localmente ou não. Se definido como `True`, o modelo não será baixado do Hub.

token (`str` ou *bool*, *opcional*) : O token a ser usado como autorização HTTP bearer para arquivos remotos. Se `True`, o token gerado por `diffusers-cli login` (armazenado em `~/.huggingface`) é utilizado.

revision (`str`, *opcional*, padrão `"main"`) : A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag, um id de commit ou qualquer identificador permitido pelo Git.

custom_revision (`str`, *opcional*) : A versão específica do modelo a ser usada. Pode ser o nome de um branch, o nome de uma tag ou um id de commit, semelhante a `revision` ao carregar um pipeline personalizado do Hub. O padrão é a versão estável mais recente do 🤗 Diffusers.

mirror (`str`, *opcional*) : Espelho de origem para resolver problemas de acessibilidade se você estiver baixando um modelo na China. Não garantimos a pontualidade ou a segurança da origem, e você deve consultar o site do espelho para obter mais informações.

device_map (`str`, *opcional*) : Estratégia que determina como os diferentes componentes de um pipeline devem ser alocados nos dispositivos disponíveis. Atualmente, apenas o `device_map` "balanced" é suportado. Consulte [este](https://huggingface.co/docs/diffusers/main/en/tutorials/inference_with_big_models#device-placement) para saber mais.

max_memory (`Dict`, *opcional*) : Um dicionário com o identificador de dispositivo para a memória máxima. Se não for definido, o padrão será a memória máxima disponível para cada GPU e a RAM disponível na CPU.

offload_folder (`str` ou `os.PathLike`, *opcional*) : O caminho para descarregar os pesos se device_map contiver o valor `"disk"`.

offload_state_dict (`bool`, *opcional*) : Se `True`, descarrega temporariamente o state dict da CPU para o disco rígido para evitar a falta de RAM na CPU caso o peso do state dict da CPU + o maior shard do checkpoint não caiba. O padrão é `True` quando há algum offload para o disco.

low_cpu_mem_usage (`bool`, *opcional*, padrão é `True` se a versão do torch >= 1.9.0, caso contrário `False`) : Acelera o carregamento do modelo carregando apenas os pesos pré-treinados e não inicializando os pesos. Isso também tenta não usar mais do que 1x o tamanho do modelo na memória de CPU (incluindo a memória de pico) durante o carregamento do modelo. Suportado apenas para PyTorch >= 1.9.0. Se você estiver usando uma versão mais antiga do PyTorch, definir este argumento como `True` causará um erro.

use_safetensors (`bool`, *opcional*, padrão `None`) : Se definido como `None`, os pesos em safetensors são baixados se estiverem disponíveis **e** se a biblioteca safetensors estiver instalada. Se definido como `True`, o modelo é carregado forçadamente a partir dos pesos em safetensors. Se definido como `False`, os pesos em safetensors não são carregados.

use_onnx (`bool`, *opcional*, padrão `None`) : Se definido como `True`, os pesos ONNX sempre serão baixados, se presentes. Se definido como `False`, os pesos ONNX nunca serão baixados. Por padrão, `use_onnx` assume o valor do atributo de classe `_is_onnx`, que é `False` para pipelines não-ONNX e `True` para pipelines ONNX. Os pesos ONNX incluem tanto arquivos terminados em `.onnx` quanto `.pb`.

kwargs (dicionário restante de argumentos de palavra-chave, *opcional*) : Pode ser usado para sobrescrever variáveis de carregamento e salvamento (os componentes do pipeline da classe de pipeline específica). Os componentes sobrescritos são passados diretamente para o método `__init__` dos pipelines. Veja o exemplo abaixo para mais informações.

variant (`str`, *opcional*) : Carrega os pesos de um nome de arquivo de variante especificado, como `"fp16"` ou `"ema"`.

disable_mmap ('bool', *opcional*, padrão 'False') : Se deve desabilitar o mmap ao carregar um modelo Safetensors. Essa opção pode ter um desempenho melhor quando o modelo está em uma montagem de rede ou em um disco rígido, que podem não lidar bem com a natureza de buscas do mmap.

Instanciar um pipeline de difusão do PyTorch a partir de pesos de pipeline pré-treinados.

O pipeline é definido no modo de avaliação (`model.eval()`) por padrão.

Se você receber a mensagem de erro abaixo, é necessário ajustar os pesos para sua tarefa 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 ou [gated](https://huggingface.co/docs/hub/models-gated#gated-models), faça login
com `hf > auth login`.

Exemplos:

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