#
# 根据 Apache 许可证 2.0 版本（“许可证”）授权
# 您只能在遵守许可证的情况下使用本文件。
# 您可以在以下位置获取许可证副本
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 除非适用法律要求或双方书面同意，软件
# 根据许可证分发，本软件按“原样”
# 不附带任何明示或暗示的保证或条件。
# 请参阅许可证中关于权限的具体语言
# 许可证下的限制。-->

# Echo

[Echo](https://github.com/jd-opensource/JoyAI-Echo) 是一个长视频生成模型。它支持可选的干净首帧、有序图像/音频记忆槽，以及随机少步分布匹配蒸馏（DMD）采样器。该流水线生成同步的视频和音频。

Echo 以 [ModularPipeline](/docs/diffusers/main/zh/api/modular_diffusers/pipeline#diffusers.ModularPipeline) 的形式实现，因此其文本编码、记忆条件化、随机 DMD 去噪以及解码模块既可以作为完整的工作流运行，也可以独立组合使用。

## 推理

直接加载官方的 [jdopensource/JoyAI-Echo](https://huggingface.co/jdopensource/JoyAI-Echo) 检查点。它使用了来自 [google/gemma-3-12b-it](https://huggingface.co/google/gemma-3-12b-it) 的文本编码器和分词器。由于 Gemma 仓库是受控的，因此在加载流水线之前，请先接受其许可证并通过 Hugging Face 进行身份验证。

发布的模型在其长视频示例中使用了 241 帧。视频的 RoPE 坐标保持为训练时的 24 fps 速率，与输出容器的速率无关。

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

默认的 DMD sigma 调度是已发布的八步调度。它在每一步都预测 `x0`，并在下一个 sigma 处使用新的高斯噪声进行重新加噪，因此一个带种子的 `torch.Generator` 同时控制初始噪声和所有中间重新加噪过程。

原始音频-内存编码需要 `torchaudio`。为了保持参考一致性，请按照上述所示将 `audio_vae` 保持在 FP32 精度。模块化工作流可以缓存 VAE 编码器归一化且解包后的张量。视频潜变量的形状为 `(batch, channels, frames, height, width)`，音频潜变量的形状为 `(batch, channels, time, mel_bins)`。核心的 `denoise` 块会打包这些张量，为 `num_videos_per_prompt` 扩展条件，并将去噪后的输出解包回相同的 VAE 形式。初始的 `latents` 和 `audio_latents` 也应以该解包形式传入。解码器接收归一化的 VAE 张量，并在解码前立即进行反归一化。`output=["latents", "audio_latents"]` 返回归一化的 VAE 张量。当使用 `output_type="latent"` 和 `output=["videos", "audio"]` 时，你将获得未经解码的反归一化 VAE 张量。

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

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

用于 Echo 长视频 DMD 检查点的 ModularPipeline。

## EchoBlocks[[diffusers.EchoBlocks]]

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

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

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

Echo 参考到视频生成，具备干净的首帧条件、有序图像/音频记忆槽位以及随机 DMD 去噪。

组件：text_encoder (`PreTrainedModel`) tokenizer (`PreTrainedTokenizerBase`) connectors (`LTX2TextConnectors`) vae (`AutoencoderKLLTX2Video`) audio_vae (`AutoencoderKLLTX2Audio`) transformer (`LTX2VideoTransformer3DModel`) video_processor (`VideoProcessor`) vocoder (`LTX2Vocoder`)

输入：prompt (`str`)：用于引导图像生成的提示词或提示词列表。max_sequence_length (`int`，*可选*，默认为 1024)：提示词编码的最大序列长度。image (`Image | Tensor`，*可选*)：可选的单个首帧，用作干净的参考条件。memory_images (`list`，*可选*)：有序的参考图像，每个 Echo 记忆槽对应一张。memory_audio_waveforms (`list`，*可选*)：有序的记忆波形，表示为 `(channels, samples)` 张量。长度超过 9.62 秒的输入将被裁剪至其最高响应窗口。对于静音槽，请使用 `None`。memory_audio_sample_rates (`int | list`，*可选*)：所有记忆波形共用的采样率，或每个槽各自的采样率。height (`int`，*可选*，默认为 512)：生成图像的高度（像素）。width (`int`，*可选*，默认为 704)：生成图像的宽度（像素）。model_frame_rate (`float`，*可选*，默认为 24.0)：用于 Echo 视频 RoPE 坐标的训练时帧率。memory_position_offset (`float`，*可选*，默认为 500.0)：分配给第一个记忆槽的时间中心。memory_position_slot_stride (`float`，*可选*，默认为 50.0)：连续记忆槽中心之间的时间距离。num_videos_per_prompt (`int`，*可选*，默认为 1)：每个提示词生成的视频数量。num_frames (`int`，*可选*，默认为 241)：生成的像素帧数；必须为 `1 + k * vae_temporal_compression_ratio`。frame_rate (`float`，*可选*，默认为 25.0)：生成视频的帧率。latents (`Tensor`，*可选*)：可选的初始视频噪声，采用 VAE 形式 (B, C, F, H, W)。audio_latents (`Tensor`，*可选*)：可选的初始音频噪声，采用 VAE 形式 (B, C, L, M)。generator (`Generator`，*可选*)：用于确定性生成的 Torch 生成器。sigmas (`list | tuple`)：DMD sigma 调度，包括末尾的零。attention_kwargs (`dict`，*可选*)：传递给注意力处理器的额外参数。output_type (`str`，*可选*，默认为 pil)：输出格式：'pil'、'np' 或 'pt'。decode_timestep (`None`，*可选*，默认为 0.0)：用于解码最终潜变量的时间步。decode_noise_scale (`None`，*可选*)：在解码时间步应用的噪声插值因子。

输出：videos (`list`)：生成的视频。audio (`Tensor`)：生成的音频波形。