[feat]: Activate MagiHuman pipeline (registry + examples + SSIM regression)

The activation switch. After this PR merges, MagiHuman is publicly
loadable via:

    from fastvideo import VideoGenerator
    gen = VideoGenerator.from_pretrained('FastVideo/MagiHuman-Diffusers/base')

Files:
- fastvideo/registry.py: 153 lines of register_configs/register_presets
  calls covering all 4 variants x 2 modes (8 total entrypoints).
- examples/inference/basic/basic_magi_human{_,_ti2v,_distill,_distill_ti2v,
  _sr540p,_sr540p_ti2v,_sr1080p,_sr1080p_ti2v}.py: 8 user-facing scripts.
- fastvideo/tests/ssim/test_magi_human_similarity.py: CI-eligible SSIM
  regression test against the umbrella HF repo.
- .agents/memory/codebase-map/models/magi_human.md: codebase-map entry
  (first per-model entry under the models/ subdir; sets the convention).
- fastvideo/pipelines/basic/magi_human/AGENTS.md: provenance section
  finalized with all 8 PR numbers + the will/magi source SHA.

Verification:
- Existing tests on main: should still pass (no shared component changes
  in this PR; the umbrella loader infra landed in PR-B / loader-infra).
- pre-commit run --all-files: clean.
- E2E smoke after activation: any of the 8 examples emits expected mp4
  with hash dcf5f2bf6534c7c0d91e7353e42b23db on the base T2V variant.

Magi-Stack: 8/8

Author: SolitaryThinker

.agents/memory/codebase-map/models/magi_human.md

@@ -0,0 +1,77 @@
+# MagiHuman — Codebase Map Entry
+
+**Family:** daVinci-MagiHuman (joint audio-visual generative model)
+**Reference:** [GAIR-NLP/daVinci-MagiHuman](https://github.com/GAIR-NLP/daVinci-MagiHuman)
+**Architecture:** 15B-param single-stream DiT, 40 layers, hidden=5120,
+head_dim=128, GQA num_query_groups=8. Joint AV denoising in a unified token
+sequence; **no cross-attention**.
+
+## Variant Matrix
+
+| Variant | T2V | TI2V | DiT | Steps | CFG | Resolution |
+|---|---|---|---|---|---|---|
+| `base` | yes | yes | base | 32 | 2 | 480x256 |
+| `distill` | yes | yes | distill (DMD-2) | 8 | 1 (no CFG) | 480x256 |
+| `sr_540p` | yes | yes | base + sr_540p | 32 + 5 | 2 + cfg-trick | 896x512 |
+| `sr_1080p` | yes | yes | base + sr_1080p | 32 + 5 | 2 + cfg-trick | 1920x1056 |
+
+SR-1080p uses block-sparse video→video local-window attention on 32 of 40
+SR DiT layers (`frame_receptive_field=11`), implemented as a 3-block SDPA
+accumulator that mirrors upstream `flex_flash_attn_func`.
+
+## File Locations
+
+| Role | Path |
+|---|---|
+| Pipeline class | `fastvideo/pipelines/basic/magi_human/magi_human_pipeline.py` |
+| Pipeline package AGENTS.md | `fastvideo/pipelines/basic/magi_human/AGENTS.md` |
+| Stages | `fastvideo/pipelines/basic/magi_human/stages/*.py` |
+| DiT | `fastvideo/models/dits/magi_human.py` |
+| Text encoder (T5-Gemma) | `fastvideo/models/encoders/t5gemma.py` |
+| Audio VAE wrapper | `fastvideo/models/vaes/sa_audio.py` (shared with `stable_audio` pipeline) |
+| Conversion script | `scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py` |
+| Examples | `examples/inference/basic/basic_magi_human*.py` (8 files, one per variant × mode) |
+| SSIM regression | `fastvideo/tests/ssim/test_magi_human_similarity.py` |
+| Local parity battery | `tests/local_tests/magi_human/` (14 tests, GPU-gated) |
+| Port journal | `fastvideo/pipelines/basic/magi_human/JOURNAL.md` |
+
+## Canonical HF Repo
+
+[FastVideo/MagiHuman-Diffusers](https://huggingface.co/FastVideo/MagiHuman-Diffusers)
+— umbrella repo with sibling subfolders per variant.
+
+```python
+from fastvideo import VideoGenerator
+gen = VideoGenerator.from_pretrained("FastVideo/MagiHuman-Diffusers/base")
+gen.generate_video(prompt="...", output_path="out.mp4", save_video=True)
+```
+
+Four shared upstream components are lazy-loaded by `MagiHumanPipeline.load_modules`:
+
+| Component | Upstream repo |
+|---|---|
+| Wan 2.2 VAE | `Wan-AI/Wan2.2-TI2V-5B` |
+| T5-Gemma 9B UL2 | `google/t5gemma-9b-9b-ul2` |
+| Stable Audio VAE | `stabilityai/stable-audio-open-1.0` |
+| MagiHuman DiT weights | `GAIR/daVinci-MagiHuman` (gated) |
+
+## Parity Invariants
+
+Three load-bearing invariants. See `fastvideo/pipelines/basic/magi_human/AGENTS.md`
+for the full discussion.
+
+1. **Channel-major video token packing** (`stages/latent_preparation.py`)
+2. **DiT dtype boundary**: residual stream stays fp32 across blocks
+3. **Conversion `_FP32_KEEP_SUFFIXES`** (`scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py`)
+
+## Lessons
+
+- `.agents/lessons/2026-05-07_silent-channel-major-packing-bugs.md`
+- `.agents/lessons/2026-05-07_dit-dtype-boundary-with-flash-attn.md`
+- `.agents/lessons/2026-05-07_conversion-cast-bf16-suffix-allowlist.md`
+
+## Provenance
+
+Decomposed from PR [#1280](https://github.com/hao-ai-lab/FastVideo/pull/1280)
+(`will/magi` @ `4e1603634d27c8e1b5c4cc5d9387f046547f5c49`). See the package
+AGENTS.md for the full PR-stack table.

examples/inference/basic/basic_magi_human.py

@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Minimal user-runnable example for the daVinci-MagiHuman base AV pipeline.
+
+Produces an mp4 with both video (Wan 2.2 TI2V-5B VAE) and audio (Stable
+Audio Open 1.0 VAE, first-class FastVideo port in
+`fastvideo/models/vaes/oobleck.py`) muxed together via PyAV.
+
+Prerequisites (one-off):
+
+  # Accept terms of use on the gated HF repos with your HF_TOKEN:
+  #   - https://huggingface.co/google/t5gemma-9b-9b-ul2
+  #   - https://huggingface.co/stabilityai/stable-audio-open-1.0
+  # All four cross-variant shared components (Wan 2.2 VAE, T5-Gemma
+  # encoder + tokenizer, Stable Audio VAE) are lazy-loaded from their
+  # canonical upstream HF repos on first build, so a single ~25 GB
+  # cache is shared across every MagiHuman variant.
+
+The umbrella HF repo `FastVideo/MagiHuman-Diffusers` holds all four
+variants (base / distill / sr_540p / sr_1080p) under sibling subfolders
+and FastVideo will download just the requested subfolder. Local
+conversion via `scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py`
+is also supported.
+"""
+from fastvideo import VideoGenerator
+
+
+PROMPT = (
+    "A warm afternoon scene: a person sits on a park bench reading a book, "
+    "surrounded by softly swaying trees."
+)
+
+
+def main() -> None:
+    generator = VideoGenerator.from_pretrained(
+        "FastVideo/MagiHuman-Diffusers/base",
+        num_gpus=1,
+    )
+    output_path = "outputs_video/magi_human_basic/output_magi_human.mp4"
+    generator.generate_video(
+        prompt=PROMPT,
+        output_path=output_path,
+        save_video=True,
+        # Defaults pulled from the registered preset (magi_human_base):
+        # height=256, width=448, fps=25, num_inference_steps=32, seed=42.
+        # Override here only if you have a specific QA scenario.
+    )
+    generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_magi_human_distill.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Minimal user-runnable example for the daVinci-MagiHuman DMD-2 distilled
+text-to-AV pipeline.
+
+Same arch as the base model (`basic_magi_human.py`) but with DMD-2 distilled
+weights: 8 denoising steps, no classifier-free guidance. ~4x faster than
+base at the same 256x480 resolution. Mirrors upstream
+`daVinci-MagiHuman/example/distill/run_T2V.sh`.
+
+Prerequisites (one-off):
+
+  # 1) Accept terms on the gated HF repos with your HF_TOKEN:
+  #    - https://huggingface.co/google/t5gemma-9b-9b-ul2
+  #    - https://huggingface.co/stabilityai/stable-audio-open-1.0
+  #    Cross-variant shared components (Wan 2.2 VAE + T5-Gemma + Stable
+  #    Audio VAE) are lazy-loaded from their canonical upstream HF repos
+  #    and shared with the base variant cache.
+  # 2) Convert the distill subfolder of GAIR/daVinci-MagiHuman:
+  python scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py \\
+      --source GAIR/daVinci-MagiHuman \\
+      --subfolder distill \\
+      --output converted_weights/magi_human_distill \\
+      --cast-bf16
+  # `--cast-bf16` is recommended (61 GB fp32 -> 30 GB bf16); the FV pipeline
+  # loads bf16 anyway, and the conversion keeps norms / RoPE bands fp32.
+"""
+from fastvideo import VideoGenerator
+
+
+PROMPT = (
+    "A warm afternoon scene: a person sits on a park bench reading a book, "
+    "surrounded by softly swaying trees."
+)
+
+
+def main() -> None:
+    generator = VideoGenerator.from_pretrained(
+        "FastVideo/MagiHuman-Diffusers/distill",
+        num_gpus=1,
+    )
+    output_path = "outputs_video/magi_human_basic/output_magi_human_distill.mp4"
+    generator.generate_video(
+        prompt=PROMPT,
+        output_path=output_path,
+        save_video=True,
+        # Defaults pulled from the registered preset (magi_human_distill):
+        # height=256, width=480, fps=25, num_inference_steps=8, cfg=1, seed=42.
+    )
+    generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_magi_human_distill_ti2v.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Minimal daVinci-MagiHuman DMD-2 distilled text+image-to-AV example."""
+from fastvideo import VideoGenerator
+from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
+    MagiHumanDistillI2VConfig,
+)
+
+
+PROMPT = (
+    "A cheerful saxophonist performs a short line with expressive facial "
+    "motion, natural head movement, and synchronized audio in a small jazz club."
+)
+IMAGE_PATH = "assets/images/saxophonist.jpg"
+
+
+def main() -> None:
+    generator = VideoGenerator.from_pretrained(
+        "FastVideo/MagiHuman-Diffusers/distill",
+        num_gpus=1,
+        workload_type="i2v",
+        override_pipeline_cls_name="MagiHumanI2VPipeline",
+        pipeline_config=MagiHumanDistillI2VConfig(),
+    )
+    generator.generate_video(
+        prompt=PROMPT,
+        image_path=IMAGE_PATH,
+        output_path="outputs_video/magi_human_distill_ti2v/output_magi_human_distill_ti2v.mp4",
+        save_video=True,
+    )
+    generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_magi_human_sr1080p.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Run daVinci-MagiHuman SR-1080p text-to-AV in FastVideo.
+
+Build the converted repo on large local storage, then symlink it into the
+workspace:
+
+    python scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py \
+        --source GAIR/daVinci-MagiHuman \
+        --subfolder base \
+        --sr-source GAIR/daVinci-MagiHuman \
+        --sr-subfolder 1080p_sr \
+        --output /raid/william5lin_converted_weights/magi_human_sr_1080p \
+        --cast-bf16
+    ln -s /raid/william5lin_converted_weights/magi_human_sr_1080p \
+        converted_weights/magi_human_sr_1080p
+"""
+from fastvideo import VideoGenerator
+from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
+    MagiHumanSR1080pConfig,
+)
+
+
+PROMPT = (
+    "A warm afternoon scene: a person sits on a park bench reading a book, "
+    "surrounded by softly swaying trees."
+)
+
+
+def main() -> None:
+    generator = VideoGenerator.from_pretrained(
+        "FastVideo/MagiHuman-Diffusers/sr_1080p",
+        num_gpus=1,
+        override_pipeline_cls_name="MagiHumanSR1080pPipeline",
+        pipeline_config=MagiHumanSR1080pConfig(),
+    )
+    generator.generate_video(
+        prompt=PROMPT,
+        output_path="outputs_video/magi_human_sr1080p/output_magi_human_sr1080p.mp4",
+        save_video=True,
+    )
+    generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_magi_human_sr1080p_ti2v.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Run daVinci-MagiHuman SR-1080p text+image-to-AV in FastVideo."""
+from fastvideo import VideoGenerator
+from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
+    MagiHumanSR1080pI2VConfig,
+)
+
+
+PROMPT = (
+    "A cheerful saxophonist performs a short line with expressive facial "
+    "motion, natural head movement, and synchronized audio in a small jazz club."
+)
+IMAGE_PATH = "assets/images/saxophonist.jpg"
+
+
+def main() -> None:
+    generator = VideoGenerator.from_pretrained(
+        "FastVideo/MagiHuman-Diffusers/sr_1080p",
+        num_gpus=1,
+        workload_type="i2v",
+        override_pipeline_cls_name="MagiHumanSR1080pI2VPipeline",
+        pipeline_config=MagiHumanSR1080pI2VConfig(),
+    )
+    generator.generate_video(
+        prompt=PROMPT,
+        image_path=IMAGE_PATH,
+        output_path="outputs_video/magi_human_sr1080p_ti2v/output_magi_human_sr1080p_ti2v.mp4",
+        save_video=True,
+    )
+    generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_magi_human_sr540p.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Run daVinci-MagiHuman SR-540p text-to-AV in FastVideo.
+
+The converted repo must contain both ``transformer/`` (base DiT) and
+``sr_transformer/`` (540p SR DiT). Build it with:
+
+    python scripts/checkpoint_conversion/convert_magi_human_to_diffusers.py \
+        --source GAIR/daVinci-MagiHuman \
+        --subfolder base \
+        --sr-source GAIR/daVinci-MagiHuman \
+        --sr-subfolder 540p_sr \
+        --output converted_weights/magi_human_sr_540p
+"""
+from fastvideo import VideoGenerator
+
+
+PROMPT = (
+    "A warm afternoon scene: a person sits on a park bench reading a book, "
+    "surrounded by softly swaying trees."
+)
+
+
+def main() -> None:
+    generator = VideoGenerator.from_pretrained(
+        "FastVideo/MagiHuman-Diffusers/sr_540p",
+        num_gpus=1,
+    )
+    generator.generate_video(
+        prompt=PROMPT,
+        output_path="outputs_video/magi_human_sr540p/output_magi_human_sr540p.mp4",
+        save_video=True,
+    )
+    generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()

examples/inference/basic/basic_magi_human_sr540p_ti2v.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Run daVinci-MagiHuman SR-540p text+image-to-AV in FastVideo."""
+from fastvideo import VideoGenerator
+from fastvideo.pipelines.basic.magi_human.pipeline_configs import (
+    MagiHumanSR540pI2VConfig,
+)
+
+
+PROMPT = (
+    "A cheerful saxophonist performs a short line with expressive facial "
+    "motion, natural head movement, and synchronized audio in a small jazz club."
+)
+IMAGE_PATH = "assets/images/saxophonist.jpg"
+
+
+def main() -> None:
+    generator = VideoGenerator.from_pretrained(
+        "FastVideo/MagiHuman-Diffusers/sr_540p",
+        num_gpus=1,
+        workload_type="i2v",
+        override_pipeline_cls_name="MagiHumanSRI2VPipeline",
+        pipeline_config=MagiHumanSR540pI2VConfig(),
+    )
+    generator.generate_video(
+        prompt=PROMPT,
+        image_path=IMAGE_PATH,
+        output_path="outputs_video/magi_human_sr540p_ti2v/output_magi_human_sr540p_ti2v.mp4",
+        save_video=True,
+    )
+    generator.shutdown()
+
+
+if __name__ == "__main__":
+    main()