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

# Wan-Animate-2

Alibaba Wan Team による [Wan-Animate-2](https://github.com/Wan-Video/Wan2.2) は、駆動動画の動きを用いて、参照キャラクター画像にアニメーションを付与します。駆動動画は固定長のセグメントに分割して処理されます。各セグメントでは、参照抽出パスを実行して駆動セグメントの K/V をすべての transformer レイヤーでキャッシュし、そのキャッシュに対してデノイズを行います。また、次のセグメントが前のセグメントのデコードされた末尾フレームに条件付けされるため、ループ内でデコードが実行されます。

2つのプリセットが利用可能です。ベースのチェックポイントはclassifier-free guidance付きでサンプリングを行い、蒸留されたチェックポイントはguidanceなしで少数ステップでサンプリングします（そのguiderは`guidance_scale=1.0`に固定されています）。

```python
import torch
from diffusers import ModularPipeline
from diffusers.utils import export_to_video, load_image, load_video

pipe = ModularPipeline.from_pretrained("Wan-AI/Wan2.2-Animate-2-14B-Diffusers")
pipe.load_components(dtype=torch.bfloat16)

# The transformer weights and the per-segment reference KV cache do not co-reside on one 80 GB
# card at the default resolution, so stream the transformer's blocks. Compiling the blocks is
# required as the in-context attention runs on the flex backend
pipe.transformer.enable_group_offload(
    onload_device=torch.device("cuda"),
    offload_device=torch.device("cpu"),
    offload_type="block_level",
    use_stream=True,
)
pipe.text_encoder.to("cuda")  # or "mps", "xpu", "cpu"
pipe.image_encoder.to("cuda")
pipe.vae.to("cuda")
pipe.transformer.compile_repeated_blocks(fullgraph=False)

# The first demo from the official repository: https://github.com/Wan-Video/Wan-Animate-2
demo = "https://raw.githubusercontent.com/Wan-Video/Wan-Animate-2/main/examples/demo1"
image = load_image(f"{demo}/reference.png")
driving_video, driving_video_fps = load_video(f"{demo}/template.mp4", return_fps=True)
prompt = "人物外观描述：一只银灰色虎斑纹的小猫，拥有圆润的脸庞、竖立的耳朵和巨大的圆形眼睛。它身穿一套深蓝色的制服套装，包括一件带有金色纽扣的西装外套和一条百褶裙。外套里面搭配着白色衬衫，领口处系着一个红色的蝴蝶结，袖口露出白色的衬衫边缘。背景描述：背景为纯白色，光线均匀明亮，无其他杂物或装饰。"

videos = pipe(
    image=image,
    driving_video=driving_video,
    driving_video_fps=driving_video_fps,
    prompt=prompt,
    output="videos",
)
export_to_video(videos[0], "output.mp4", fps=24)
```

蒸留済みチェックポイントでは、`Wan-AI/Wan2.2-Animate-2-14B-Distilled-Diffusers` も同じ方法で読み込みます。その他の変更はありません。各プリセットには独自のサンプリングのデフォルト値が設定されています（ベースチェックポイントは40ステップ、蒸留済みチェックポイントは10ステップ）。また、`guidance_scale` 引数はどこにも存在しません。ガイダンスはパイプラインの guider コンポーネントが管理しており、ベースプリセットでは classifier-free guidance が 3.0 で有効、蒸留済みプリセットでは無効になっています。

`height` と `width`（デフォルト値はそれぞれ 800 と 640）は、生成される動画の目標*領域*を設定します。実際のフレームサイズは参照画像のアスペクト比を維持し、駆動フレームはレターボックス方式でそのサイズに調整されます。すでに目標のレターボックスサイズに一致している入力については、前処理がそのままスキップされるため、前処理をパイプラインの外側で完全に実行することも可能です。

## WanAnimate2ModularPipeline[[diffusers.WanAnimate2ModularPipeline]]

#### diffusers.WanAnimate2ModularPipeline[[diffusers.WanAnimate2ModularPipeline]]

```python
diffusers.WanAnimate2ModularPipeline(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/wan_animate_2/modular_pipeline.py#L23)

Wan-Animate-2 のキャラクターアニメーション用の ModularPipeline。

## WanAnimate2DistilledModularPipeline[[diffusers.WanAnimate2DistilledModularPipeline]]

#### diffusers.WanAnimate2DistilledModularPipeline[[diffusers.WanAnimate2DistilledModularPipeline]]

```python
diffusers.WanAnimate2DistilledModularPipeline(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/wan_animate_2/modular_pipeline.py#L62)

ModularPipelineは、classifier-free guidanceなしで少数ステップでサンプリングを行う蒸留済みWan-Animate-2モデル用のパイプラインです。

## WanAnimate2Blocks[[diffusers.WanAnimate2Blocks]]

#### diffusers.WanAnimate2Blocks[[diffusers.WanAnimate2Blocks]]

```python
diffusers.WanAnimate2Blocks()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/wan_animate_2/modular_blocks_wan_animate_2.py#L252)

Wan-Animate-2 のキャラクターアニメーション用のモジュール化されたパイプラインブロック: 参照キャラクター画像と駆動動画を入力することで、駆動モーションに従ってキャラクターが動く動画を生成します。

コンポーネント: text_encoder (`UMT5EncoderModel`) tokenizer (`AutoTokenizer`) image_processor (`WanAnimate2VideoProcessor`) image_encoder (`CLIPVisionModel`) video_processor (`WanAnimate2VideoProcessor`) vae (`AutoencoderKLWan`) transformer (`WanAnimate2Transformer3DModel`) scheduler (`SchedulerMixin`) guider (`ClassifierFreeGuidance`)

Inputs: prompt (`str`): 画像生成をガイドするためのプロンプトまたはプロンプトのリスト。 negative_prompt (`str`, *任意*): 画像生成をガイドしないためのプロンプトまたはプロンプトのリスト。 prompt_ref (`str`, *任意*, デフォルトは 人物动作的参考视频): ドライブ動画のコンテキストに対する参照プロンプト。 max_sequence_length (`int`, *任意*, デフォルトは 512): プロンプトエンコーディングの最大シーケンス長。 image (`Image | list`): アニメーションさせるキャラクターを含む参照画像。 height (`int`, *任意*, デフォルトは 800): `width` と合わせて、生成される動画の目標 *面積* を指定します。アスペクト比は `image` から取得されます。解決されたフレームの高さで上書きされます。 width (`int`, *任意*, デフォルトは 640): `height` を参照してください。解決されたフレームの幅で上書きされます。 driving_video (`list`): `VideoProcessor.preprocess_video` が受け入れる任意の形式で、モーションを提供するドライブ動画。 driving_video_fps (`float`, *任意*): `driving_video` が撮影されたフレームレート — `load_video(..., return_fps=True)` がこれを報告します。設定されている場合、ドライブフレームは `fps` にリサンプリングされます。`None` の場合は、そのまま使用されます。 fps (`int`, *任意*, デフォルトは 24): モデルが生成するフレームレート。 segment_frame_length (`int`, *任意*, デフォルトは 81): 各推論セグメントのフレーム数。 prev_segment_conditioning_frames (`int`, *任意*, デフォルトは 1): 前のセグメントから引き継ぐ条件付けフレームの数。 generator (`Generator`, *任意*): 決定論的な生成のための Torch ジェネレーター。 num_inference_steps (`int`, *任意*, デフォルトは 40): 減噪ステップの数。 **denoiser_input_fields (`None`, *任意*): デノイザー用の条件付きモデル入力: 例: prompt_embeds, negative_prompt_embeds など。 output_type (`str`, *任意*, デフォルトは np): デコードされた動画の出力タイプ。

出力: 動画 (`list`): 生成された動画。

## WanAnimate2DistilledBlocks[[diffusers.WanAnimate2DistilledBlocks]]

#### diffusers.WanAnimate2DistilledBlocks[[diffusers.WanAnimate2DistilledBlocks]]

```python
diffusers.WanAnimate2DistilledBlocks()
```

[ソース](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/wan_animate_2/modular_blocks_wan_animate_2_distilled.py#L254)

蒸留された Wan-Animate-2 キャラクターアニメーション用のモジュール化されたパイプラインブロック。Classifier-free guidance なしで、少数のステップでのサンプリングを実現します。

コンポーネント: text_encoder (`UMT5EncoderModel`) tokenizer (`AutoTokenizer`) image_processor (`WanAnimate2VideoProcessor`) image_encoder (`CLIPVisionModel`) video_processor (`WanAnimate2VideoProcessor`) vae (`AutoencoderKLWan`) transformer (`WanAnimate2Transformer3DModel`) scheduler (`SchedulerMixin`) guider (`ClassifierFreeGuidance`)

Inputs: prompt (`str`): 画像生成をガイドするためのプロンプトまたはプロンプトのリスト。 negative_prompt (`str`, *任意*): 画像生成をガイドしないためのプロンプトまたはプロンプトのリスト。 prompt_ref (`str`, *任意*, デフォルトは 人物动作的参考视频): ドライブ動画のコンテキストに対する参照プロンプト。 max_sequence_length (`int`, *任意*, デフォルトは 512): プロンプトエンコーディングの最大シーケンス長。 image (`Image | list`): アニメーションさせるキャラクターを含む参照画像。 height (`int`, *任意*, デフォルトは 800): `width` と合わせて、生成される動画の目標*面積*。アスペクト比は`image`から取得されます。解決されたフレームの高さで上書きされます。 width (`int`, *任意*, デフォルトは 640): `height`を参照してください。解決されたフレームの幅で上書きされます。 driving_video (`list`): `VideoProcessor.preprocess_video`が受け入れる任意の形式で、モーションを提供するドライブ動画。 driving_video_fps (`float`, *任意*): `driving_video`が撮影されたフレームレート — `load_video(..., return_fps=True)`がこれを報告します。設定されている場合、ドライブフレームはそこから`fps`にリサンプリングされます。`None`の場合、そのまま使用されます。 fps (`int`, *任意*, デフォルトは 24): モデルが生成するフレームレート。 segment_frame_length (`int`, *任意*, デフォルトは 81): 各推論セグメントのフレーム数。 prev_segment_conditioning_frames (`int`, *任意*, デフォルトは 1): 前のセグメントから引き継がれる条件付けフレームの数。 generator (`Generator`, *任意*): 決定論的な生成のための Torch ジェネレーター。 num_inference_steps (`int`, *任意*, デフォルトは 10): 減噪ステップの数。 **denoiser_input_fields (`None`, *任意*): デノイザー用の条件付きモデル入力: 例: prompt_embeds, negative_prompt_embeds など。 output_type (`str`, *任意*, デフォルトは np): デコードされた動画の出力タイプ。

出力: 動画 (`list`): 生成された動画。