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 좌표는 학습 시 사용된 24fps의 비율을 유지합니다.
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 스케줄은 공개된 8단계 스케줄입니다. 모든 단계에서 x0를 예측하고 다음 sigma에서 새로운 가우시안 노이즈로 재노이즈링을 수행하므로, 시드가 설정된 torch.Generator가 초기 노이즈와 모든 중간 재노이즈링을 제어합니다.
Raw 오디오-메모리 인코딩에는 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
< 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):
종단부 0을 포함한 DMD 시그마 스케줄입니다.
attention_kwargs (dict, 선택 사항):
어텐션 프로세서에 전달할 추가 kwargs입니다.
output_type (str, 선택 사항, 기본값 pil):
출력 형식: ‘pil’, ‘np’, ‘pt’.
decode_timestep (None, 선택 사항, 기본값 0.0):
최종 latents를 디코딩하는 데 사용되는 타임스텝입니다.
decode_noise_scale (None, 선택 사항):
디코딩 타임스텝에서 적용되는 노이즈 보간 계수입니다.
Outputs:
videos (list):
생성된 비디오.
audio (Tensor):
생성된 오디오 웨이브폼.