Diffusers documentation
Echo
Echo
Echo 是一个长视频生成模型。它支持可选的干净首帧、有序图像/音频记忆槽，以及随机少步 Distribution Matching Distillation (DMD) 采样器。 该流水线生成同步的视频和音频。
Echo 以 ModularPipeline 的形式实现，因此其文本编码、记忆条件化、随机 DMD 去噪以及解码模块既可以作为完整的工作流运行，也可以独立组合使用。
推理
直接加载官方的 jdopensource/JoyAI-Echo 检查点。 它使用了来自 google/gemma-3-12b-it 的文本编码器和分词器。 Gemma 仓库是受控的，因此在加载流水线之前，请先接受其许可证并通过 Hugging Face 进行身份验证。
发布的模型在其长视频示例中使用了 241 帧。视频的 RoPE 坐标保持为训练时的 24 fps 速率，与输出容器的速率无关。
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 处使用新的 Gaussian 噪声进行重新加噪，因此一个带种子的 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
class diffusers.EchoModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
用于 Echo 长视频 DMD 检查点的 ModularPipeline。
EchoBlocks
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)：
生成的音频波形。