#
# Licenciado sob a Apache License, Versão 2.0 (a "Licença");
# você não pode usar este arquivo, exceto em conformidade com a Licença.
# Você pode obter uma cópia da Licença em
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# A menos que exigido pela lei aplicável ou acordado por escrito, o software
# distribuído sob a Licença é distribuído em uma base "COMO ESTÁ",
# SEM GARANTIAS OU CONDIÇÕES DE QUALQUER TIPO, expressas ou implícitas.
# Consulte a Licença para o idioma específico que rege as permissões e
# limitações sob a Licença. -->

# Echo

[Echo](https://github.com/jd-opensource/JoyAI-Echo) é um modelo de geração de vídeos longos. Ele suporta um primeiro frame limpo opcional, slots de memória de imagem/áudio ordenados e um amostrador estocástico de poucas etapas de Distribution Matching Distillation (DMD). O pipeline gera vídeo e áudio sincronizados.

O Echo é implementado como um [ModularPipeline](/docs/diffusers/main/pt/api/modular_diffusers/pipeline#diffusers.ModularPipeline), de modo que seus blocos de codificação de texto, condicionamento de memória, desruidagem estocástica DMD e decodificação podem ser executados como um fluxo de trabalho completo ou compostos de forma independente.

## Inferência

Carregue diretamente o checkpoint oficial [jdopensource/JoyAI-Echo](https://huggingface.co/jdopensource/JoyAI-Echo). Ele usa o codificador de texto e o tokenizador de [google/gemma-3-12b-it](https://huggingface.co/google/gemma-3-12b-it). O repositório Gemma é restrito, portanto, aceite sua licença e autentique-se no Hugging Face antes de carregar o pipeline.

O modelo lançado usa 241 quadros em seu exemplo de vídeo longo. As coordenadas de RoPE do vídeo permanecem na taxa de treinamento de 24 fps, independentemente da taxa do contêiner de saída.

```py
import torch
import torchaudio
from PIL import Image

from diffusers import ComponentsManager, ModularPipeline
from diffusers.utils import encode_video

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("jdopensource/JoyAI-Echo", components_manager=manager)
pipe.load_components(dtype={"default": torch.bfloat16, "audio_vae": torch.float32})
manager.enable_auto_cpu_offload(device="cuda")
pipe.vae.enable_tiling()

first_frame = Image.open("first_frame.png").convert("RGB")
memory_images = [Image.open(path).convert("RGB") for path in ["memory_0.png", "memory_1.png"]]
memory_audio_with_rates = [torchaudio.load(path) for path in ["memory_0.wav", "memory_1.wav"]]
memory_audio = [waveform for waveform, _ in memory_audio_with_rates]
memory_audio_rates = [sample_rate for _, sample_rate in memory_audio_with_rates]

output = pipe(
    prompt="A cinematic dialogue scene in a quiet cafe.",
    image=first_frame,
    memory_images=memory_images,
    memory_audio_waveforms=memory_audio,
    memory_audio_sample_rates=memory_audio_rates,
    width=1280,
    height=736,
    num_frames=241,
    frame_rate=25.0,
    model_frame_rate=24.0,
    generator=torch.Generator(device="cuda").manual_seed(42),
    output_type="np",
    output=["videos", "audio"],
)

encode_video(
    output["videos"][0],
    fps=25,
    audio=output["audio"][0].float().cpu(),
    audio_sample_rate=pipe.vocoder.config.output_sampling_rate,
    output_path="echo.mp4",
)
```

O agendamento de sigma padrão do DMD é o agendamento de oito etapas publicado. Ele prevê `x0` em cada etapa e re-ruidifica com ruído gaussiano novo no próximo sigma, de modo que um `torch.Generator` com seed controla tanto o ruído inicial quanto todo o re-ruidificação intermediária.

A codificação bruta de áudio em memória requer `torchaudio`. Para paridade de referência, mantenha `audio_vae` em FP32, conforme mostrado acima. Fluxos de trabalho modulares podem fazer cache dos tensores normalizados e descompactados do codificador VAE. Os latentes de vídeo têm forma `(batch, channels, frames, height, width)` e os latentes de áudio têm forma `(batch, channels, time, mel_bins)`. O bloco central `denoise` compacta esses tensores, expande o condicionamento para `num_videos_per_prompt` e descompacta as saídas desruidadas de volta para a mesma forma VAE. Passe os `latents` e `audio_latents` iniciais também nessa forma descompactada. Os decodificadores recebem tensores VAE normalizados e os denormalizam imediatamente antes da decodificação. `output=["latents", "audio_latents"]` retorna tensores VAE normalizados. Com `output_type="latent"` e `output=["videos", "audio"]`, você obtém os tensores VAE denormalizados sem decodificação.

## EchoModularPipeline[[diffusers.EchoModularPipeline]]

#### diffusers.EchoModularPipeline[[diffusers.EchoModularPipeline]]

```python
diffusers.EchoModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/echo/modular_pipeline.py#L27)

Uma ModularPipeline para o checkpoint DMD de vídeo longo do Echo.

## EchoBlocks[[diffusers.EchoBlocks]]

#### diffusers.EchoBlocks[[diffusers.EchoBlocks]]

```python
diffusers.EchoBlocks()
```

[Fonte](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/echo/modular_blocks_echo.py#L220)

Geração de vídeo a partir de referência com Echo, condicionamento limpo do primeiro quadro, slots de memória de imagem/áudio ordenados e desruidagem estocática DMD.

Componentes: text_encoder (`PreTrainedModel`) tokenizer (`PreTrainedTokenizerBase`) conectores (`LTX2TextConnectors`) vae (`AutoencoderKLLTX2Video`) audio_vae (`AutoencoderKLLTX2Audio`) transformer (`LTX2VideoTransformer3DModel`) video_processor (`VideoProcessor`) vocoder (`LTX2Vocoder`)

Inputs: prompt (`str`): O prompt ou prompts para orientar a geração de imagem. max_sequence_length (`int`, *opcional*, padrão 1024): Comprimento máximo da sequência para a codificação do prompt. image (`Image | Tensor`, *opcional*): Opcional, um único primeiro quadro usado como condição de referência limpa. memory_images (`list`, *opcional*): Imagens de referência ordenadas, uma para cada slot de memória do Echo. memory_audio_waveforms (`list`, *opcional*): Formas de onda de memória ordenadas como tensores `(channels, samples)`. Entradas com mais de 9,62 segundos são recortadas para a janela de maior resposta. Use `None` para um slot silencioso. memory_audio_sample_rates (`int | list`, *opcional*): Taxa de amostragem compartilhada por todas as formas de onda de memória, ou uma taxa por slot. height (`int`, *opcional*, padrão 512): A altura em pixels da imagem gerada. width (`int`, *opcional*, padrão 704): A largura em pixels da imagem gerada. model_frame_rate (`float`, *opcional*, padrão 24.0): Taxa de quadros no momento do treinamento usada para as coordenadas RoPE de vídeo do Echo. memory_position_offset (`float`, *opcional*, padrão 500.0): Centro temporal atribuído ao primeiro slot de memória. memory_position_slot_stride (`float`, *opcional*, padrão 50.0): Distância temporal entre os centros de slots de memória consecutivos. num_videos_per_prompt (`int`, *opcional*, padrão 1): Número de vídeos por prompt. num_frames (`int`, *opcional*, padrão 241): Número de quadros de pixels gerados; deve ser `1 + k * vae_temporal_compression_ratio`. frame_rate (`float`, *opcional*, padrão 25.0): Taxa de quadros do vídeo gerado. latents (`Tensor`, *opcional*): Opcional, ruído de vídeo inicial em formato VAE (B, C, F, H, W). audio_latents (`Tensor`, *opcional*): Opcional, ruído de áudio inicial em formato VAE (B, C, L, M). generator (`Generator`, *opcional*): Gerador do Torch para geração determinística. sigmas (`list | tuple`): Agendamento de sigma do DMD, incluindo o zero terminal. attention_kwargs (`dict`, *opcional*): Kwargs adicionais para os processadores de atenção. output_type (`str`, *opcional*, padrão pil): Formato de saída: 'pil', 'np', 'pt'. decode_timestep (`None`, *opcional*, padrão 0.0): Timestep usado para decodificar os latents finais. decode_noise_scale (`None`, *opcional*): Fator de interpolação de ruído aplicado no timestep de decodificação.

Saídas: vídeos (`list`): Os vídeos gerados. áudio (`Tensor`): A forma de onda de áudio gerada.