Buckets:

hf-doc-build
/

doc

Files

xet

hf-doc-build/doc / diffusers /main /ja /api /pipelines /echo.md

mishig

8 days ago

preview code

download

raw

10 kB

#
# Apache License, Version 2.0（「ライセンス」）の下でライセンスされています。
# このファイルは、ライセンスに準拠した場合にのみ使用できます。
# ライセンスのコピーは以下から入手できます
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 適用される法律で要求される場合、または書面による合意がある場合を除き、ソフトウェア
# ライセンスに基づき配布される本ソフトウェアは、「現状のまま」
# 明示的または黙示的を問わず、いかなる種類の保証や条件も付随しません。
# 権限を管理する特定の言語については、ライセンスを参照してください。
# ライセンスの下での制限。-->

# エコー

[Echo](https://github.com/jd-opensource/JoyAI-Echo)は、長尺動画生成モデルです。任意のクリーンな先頭フレーム、順序付けられた画像/音声メモリスロット、および確率的な少数ステップのDistribution Matching Distillation (DMD) サンプラーをサポートしています。このパイプラインは、同期された動画と音声を生成します。

Echo は [ModularPipeline](/docs/diffusers/main/ja/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 シグマスケジュールは、リリースされた 8 ステップのスケジュールです。各ステップで `x0` を予測し、次のシグマで新しいガウスノイズを用いて再ノイズ化するため、シード付きの `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`)
Inputs: prompt (`str`): 画像生成をガイドするためのプロンプト、またはプロンプトのリスト。 max_sequence_length (`int`, *任意*, デフォルト値 1024): プロンプトエンコードの最大シーケンス長。 image (`Image | Tensor`, *任意*): クリーンな参照条件として使用される、任意の単一の最初のフレーム。 memory_images (`list`, *任意*): Echo メモリスロットごとに1枚の、順序付けられた参照画像。 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 シグマスケジュール。 attention_kwargs (`dict`, *任意*): アテンションプロセッサー用の追加の kwargs。 output_type (`str`, *任意*, デフォルト値 pil): 出力形式: 'pil', 'np', 'pt'。 decode_timestep (`None`, *任意*, デフォルト値 0.0): 最終的な潜在変数をデコードするために使用されるタイムステップ。 decode_noise_scale (`None`, *任意*): デコードタイムステップで適用されるノイズ補間係数。
出力: videos (`list`): 生成された動画。 audio (`Tensor`): 生成された音声波形。

Xet Storage Details

Size:: 10 kB
Xet hash:: 072e7e2ec93c49d1647f03b37e7f57b064d984e9184726efd239fe294d4446f7

Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.

	#
	# Apache License, Version 2.0（「ライセンス」）の下でライセンスされています。
	# このファイルは、ライセンスに準拠した場合にのみ使用できます。
	# ライセンスのコピーは以下から入手できます
	#
	# http://www.apache.org/licenses/LICENSE-2.0
	#
	# 適用される法律で要求される場合、または書面による合意がある場合を除き、ソフトウェア
	# ライセンスに基づき配布される本ソフトウェアは、「現状のまま」
	# 明示的または黙示的を問わず、いかなる種類の保証や条件も付随しません。
	# 権限を管理する特定の言語については、ライセンスを参照してください。
	# ライセンスの下での制限。-->

	# エコー

	[Echo](https://github.com/jd-opensource/JoyAI-Echo)は、長尺動画生成モデルです。任意のクリーンな先頭フレーム、順序付けられた画像/音声メモリスロット、および確率的な少数ステップのDistribution Matching Distillation (DMD) サンプラーをサポートしています。このパイプラインは、同期された動画と音声を生成します。

	Echo は [ModularPipeline](/docs/diffusers/main/ja/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 シグマスケジュールは、リリースされた 8 ステップのスケジュールです。各ステップで `x0` を予測し、次のシグマで新しいガウスノイズを用いて再ノイズ化するため、シード付きの `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`)

	Inputs: prompt (`str`): 画像生成をガイドするためのプロンプト、またはプロンプトのリスト。 max_sequence_length (`int`, 任意, デフォルト値 1024): プロンプトエンコードの最大シーケンス長。 image (`Image \| Tensor`, 任意): クリーンな参照条件として使用される、任意の単一の最初のフレーム。 memory_images (`list`, 任意): Echo メモリスロットごとに1枚の、順序付けられた参照画像。 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 シグマスケジュール。 attention_kwargs (`dict`, 任意): アテンションプロセッサー用の追加の kwargs。 output_type (`str`, 任意, デフォルト値 pil): 出力形式: 'pil', 'np', 'pt'。 decode_timestep (`None`, 任意, デフォルト値 0.0): 最終的な潜在変数をデコードするために使用されるタイムステップ。 decode_noise_scale (`None`, 任意): デコードタイムステップで適用されるノイズ補間係数。

	出力: videos (`list`): 生成された動画。 audio (`Tensor`): 生成された音声波形。