[new-model] Add Wan2.2-Animate-14B character animation/replacement inference

[SuhaanCoding]

Purpose

Add Wan2.2-Animate-14B inference: character animation driven by a reference image plus a driving video (skeleton + face crops), with an animation mode (character on the reference image's background) and a replacement mode (character composited into the driving video's scene).

The implementation follows FastVideo's component, pipeline-stage, preset, registry, and checkpoint-loading abstractions. It loads the official Diffusers-layout checkpoint (Wan-AI/Wan2.2-Animate-14B-Diffusers) directly — no weights conversion or upload is needed — and does not change the routing or behavior of existing pipelines. Driving inputs are the files the official preprocessing produces (wan/modules/animate/preprocess in the Wan2.2 repo); this PR does not re-implement that preprocessing, matching the choice the diffusers integration made.

Follow-up to #1683 (S2V); related community interest in #1126 (distilling this model).

Changes

• Add WanAnimateTransformer3DModel as a subclass of the existing Wan transformer: the tower is unchanged Wan-I2V; the port adds a pose patch embedding (applied to every latent frame except the reference slot), a LIA-style motion encoder + face encoder, and 8 per-frame face cross-attention blocks (one after every 5th transformer block).
• Reproduce the StyleGAN2 runtime weight scaling in the motion encoder (checkpoint stores unit-scale weights; the layer divides by sqrt(fan_in) at forward), and pin motion_synthesis_weight to fp32 via the loader's per-parameter dtype hook (an orthonormal basis is re-derived from it every forward).
• Add five Animate pipeline stages: +1 latent frame for the reference slot, 20-channel conditional-latent assembly (4-channel folded I2V mask + VAE-encoded reference/target frames, mode-branched for animation vs replacement), pose-video VAE encoding, face video as raw pixels, and decode that drops the reference slot.
• Add arch/pipeline configs transcribed from the official checkpoint manifest, the wan_animate_14b preset (77 frames, 30 fps, 20 steps, guidance 1.0 — the official runtime defaults), and registry resolution.
• Carry five new request inputs through the API (pose_video_path, face_video_path, background_video_path, mask_video_path, animate_mode), with schema-parity inventory and parser-test updates.
• Add a repack script for the replace-mode relighting LoRA (ships only in the non-diffusers repo, in PEFT key format the loader cannot read; the script renames keys and writes per-layer alpha values so the strength matches).
• Add a runnable example and support-matrix entries.
• Add 36 tests: config transcription and guard asserts, the StyleGAN2 scaling contract, per-frame face-attention confinement, pose reference-slot isolation, adapter wiring order, meta-device buffer survival, plus two weight-gated tests (strict checkpoint↔model tensor mapping in both directions; raw no-autocast bf16 forward).

Test Plan

# Unit + weight-gated tests
export WAN_ANIMATE_MODEL_PATH=/path/to/Wan2.2-Animate-14B-Diffusers
pytest fastvideo/tests/transformers/test_wan_animate.py -v

# End-to-end (driving inputs produced by the official preprocessing)
python examples/inference/basic/basic_wan_animate.py

Numerical parity against diffusers was checked with a standalone two-phase harness (each phase loads one implementation in fp32 from the same checkpoint, identical fixed-seed inputs, forward hooks at every stage); happy to attach the script or fold it into tests/local_tests/ if wanted.

Test Results

All runs on a DGX Spark (GB10) against the official checkpoint.

Test output

fastvideo/tests/transformers/test_wan_animate.py
================= 36 passed, 14 warnings in 172.69s (0:02:52) ==================

fp32 parity vs diffusers (same checkpoint, identical inputs, per-stage probes):
- input assembly (patchify + pose add): bitwise identical
- condition embeddings (timestep/text/CLIP): <= 4.8e-07 max abs
- block 0 self-attention:  max_rel 5.4e-07
- block 0 cross-attention: max_rel 5.2e-07
- after all 40 blocks:     max_rel 8.4e-07
- face adapters:           max_rel <= 8.9e-07
- final output:            max_rel 1.7e-06

End to end: official example clip -> official preprocessing (skeleton video +
face crops) -> 77 frames @ 832x464, 20 steps, guidance 1.0 -> saved video.

source video:
https://github.com/user-attachments/assets/339706fa-0e4c-477a-85fe-c154b565510e

source ref:

source face:
https://github.com/user-attachments/assets/d9cfa32d-1133-4206-ba9a-6c983e6eaac1

source pose:
https://github.com/user-attachments/assets/e172b655-d5f3-4219-b02d-c437bfd6c82c

output:
https://github.com/user-attachments/assets/023960c3-f864-49c1-aeb2-da61bf098c91

Note: shares a few files with #1683 (S2V) so whichever merges second needs a small rebase.

[mergify]

Merge Protections

🔴 1 of 1 protections blocking · waiting on 👀 reviews and 🤖 CI

	Protection	Waiting on
🔴	PR merge requirements	👀 reviews and 🤖 CI

🔴 PR merge requirements

Waiting for

• #approved-reviews-by>=1
• check-success=fastcheck-passed
• check-success=full-suite-passed

This rule is failing.

• #approved-reviews-by>=1
• check-success=fastcheck-passed
• check-success=full-suite-passed
• check-success~=pre-commit
• title~=(?i)^\[(feat|feature|bugfix|fix|refactor|perf|ci|doc|docs|misc|chore|kernel|new.?model|skill|skills|infra)\]