MiniMax-H3 character-swap LoRA demo (ref2va, split conditioner)

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+examples/cafe_scene.mp4 filter=lfs diff=lfs merge=lfs -text
+examples/character_anime.png filter=lfs diff=lfs merge=lfs -text
+examples/character_hiker.png filter=lfs diff=lfs merge=lfs -text
+examples/character_sheet_orin.png filter=lfs diff=lfs merge=lfs -text
+examples/workshop_scene.mp4 filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,13 +1,149 @@
 ---
-title: Minimax H3 Character Swap Lora
-emoji: 📈
-colorFrom: purple
-colorTo: purple
+title: MiniMax-H3 Character Swap LoRA
+emoji: 🎭
+colorFrom: red
+colorTo: yellow
 sdk: gradio
 sdk_version: 6.28.0
-python_version: '3.12'
 app_file: app.py
 pinned: false
+short_description: Swap one character in a clip for a reference character
+python_version: "3.12"
+startup_duration_timeout: 1h
+models:
+  - akatz-ai/MiniMax-H3-Character-Swap-LoRA
+  - multimodalart/MiniMax-H3-Pruned
+  - MiniMaxAI/MiniMax-H3
+datasets:
+  - akatz-ai/H3-Character-Swap-v1
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# MiniMax-H3 Character Swap LoRA
+
+A demo of [`akatz-ai/MiniMax-H3-Character-Swap-LoRA`](https://huggingface.co/akatz-ai/MiniMax-H3-Character-Swap-LoRA),
+Akatz Labs' experimental character-replacement adapter for
+[MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3)'s `ref2va` partition. Hand it a scene clip and a character
+reference, name who to replace, and it puts the reference character into the shot — identity, outfit and art style
+carried over — while the background, camera, lighting and everyone else stay where they were. Video and its
+synchronized soundtrack come out of a single denoising pass.
+
+## The request
+
+Two references, **in the order the model reads them**, and a short targeting instruction:
+
+| Slot | Label in the prompt | What it is |
+|---|---|---|
+| reference 1 | `<Picture 1>` | the replacement character — a portrait or a full character sheet |
+| reference 2 | `<Video 1>` | the clip to edit, 5 frames to 15 s |
+
+> Swap the man in the purple shirt in \<Video 1\> with the character in \<Picture 1\>.
+
+That order is the one thing about this request worth being careful with, and it is **not** the order the prompt
+names them in. MiniMax-H3 numbers a reference's label *per modality*, so the first image is `<Picture 1>` and the
+first video is `<Video 1>` whichever way round they are packed — but the packed order still fixes the shared
+audio/video rotary clock, so the same two references swapped round are a different request. The LoRA was trained
+with the character sheet first: `control_path: [character_references, scene_videos]` in
+`configs/trained-run-1000.json` of [`akatz-ai/H3-Character-Swap-v1`](https://huggingface.co/datasets/akatz-ai/H3-Character-Swap-v1).
+`collect()` builds the list that way and nothing else in the app reorders it.
+
+No trigger word was trained. Strength **1.0** is the card's recommendation; **0** is the base `ref2va` model, which
+is the comparison the adapter was judged against, so the slider doubles as an A/B.
+
+## What it is good at, and what it is not
+
+The card is candid, and this demo does not oversell it. It is a **1,000-update experimental** adapter:
+
+* background and scene preservation improved over the base model in the author's local comparisons — qualitative,
+  not a benchmark,
+* motion timing, facial expressions and hard cuts remain unreliable; a hard cut can become a zoom or a gradual
+  reposition,
+* long windows drift in framing and placement. **Short continuous shots of roughly 3–5 s** are the promising range,
+* two-character inference was tested but multi-character replacement was never supervised,
+* the soundtrack is generated, not carried over. Audio preservation in the author's later review was a remux, which
+  does not repair lip-sync drift.
+
+Its 94 training edits targeted **single still frames**, with five-frame static clips standing in for `<Video 1>` —
+which is exactly what the examples below are. Real moving footage goes in the same slot and is what the 40
+preservation clips regularized, but it is the harder case.
+
+## Defaults, and where they come from
+
+`1344x768` at 24 fps, 73 frames (3.04 s), 28 steps, seed 904231 — the `sample` block of the LoRA's own
+`configs/trained-run-1000.json`. The canvas dropdown follows the scene clip's aspect ratio on upload, because a
+character swap is asked to keep the source framing and a portrait clip generated on a landscape canvas is a
+recomposed shot before the model has done anything. "Match the scene clip's length" generates for as long as the
+clip runs whenever that is a length MiniMax-H3 generates (2–14 s); the five-frame example clips are not, so they
+fall through to the slider.
+
+## How it is deployed
+
+MiniMax-H3 is 195.9 GiB in bfloat16 and a ZeroGPU Space is evicted at 150 GB of storage, so `MiniMaxH3Blocks` is
+cut at its `text_encoder` step. This Space is the **denoising half** of `ref2va` — the `transformer_ref` partition
+and the two autoencoders — and the 62 GiB Qwen3-VL conditioner runs in
+[`multimodalart/qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner), which this
+Space calls over the gradio API for every request. `prompt_embeds` + `text_token_tags` is the whole wire format;
+`reference_encoder` stays here, next to the autoencoders it runs. `h3_split_blocks.py` is the subclass that removes
+the step.
+
+The DiT is [`multimodalart/MiniMax-H3-Pruned`](https://huggingface.co/multimodalart/MiniMax-H3-Pruned)'s
+`transformer_ref`: the released partition with its AdaLN input projections folded onto their reachable rank, 37.5
+GiB instead of 61.7. That is the **same checkpoint family the LoRA was trained against** — ai-toolkit trained it on
+Comfy-Org's `minimax_h3_ref2va_pruned_int8_convrot`, an int8 ConvRot quantization of these weights — and everything
+the adapter touches is identical between the pruned and the released partition. The run's
+`network_kwargs.ignore_if_contains = ["adaln_proj"]` kept it off the timestep path, which is the only place the two
+differ.
+
+**GPU time is priced per request, not per Space.** MiniMax-H3 attends over one packed sequence, and on this half the
+references dominate its length: a 2048-short-edge character sheet is thousands of conditioning rows on top of the
+generated ones. `get_duration` evaluates a fitted cost model over the sequence it is about to denoise — the
+conditioner's exact token count plus the references measured from metadata — instead of reserving a flat ceiling for
+everything, because the pool reserves whatever number it is given.
+
+A first-block cache (`h3_fbc.py`, ported from `duckyshell/ComfyUI-MiniMaxH3-FirstBlockCache` with an audio
+exemption) skips blocks 1–49 on steps whose block-0 residual has barely moved. `H3_FBC=0` restores the uncached
+trajectory exactly.
+
+There is no AoTI on this Space, unlike its siblings: a compiled block package binds the base module's weights by
+fully qualified name and would run straight past the PEFT branch the adapter lives in.
+
+## Space variables
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `H3_LORA_SCALE` | `1.0` | Default adapter strength. |
+| `H3_CONDITIONER` | `multimodalart/qwen3vl-conditioner` | The public Space this one asks for embeddings; the client passes no token, so the call runs on the caller's own quota. |
+| `H3_MODEL_REPO` | `multimodalart/MiniMax-H3-Pruned` | The diffusers-layout DiT. |
+| `H3_ATTENTION` | `_native_cudnn` | cuDNN's fused kernel, 10–20% faster than the SDPA default. The two float32 VAEs are pinned to torch SDPA, which cuDNN has no kernel for. |
+| `H3_FBC` / `H3_FBC_THRESHOLD` | `1` / `0.05` | First-block cache and its relative-L1 gate. |
+| `H3_GPU_SIZE` | `xlarge` | ZeroGPU allocation size. `large` does not fit. |
+| `H3_PLACEMENT` | `lazy` | Moves the partition onto the card on the first GPU call and leaves it there. |
+
+## Safety
+
+Every request here carries an image and a video reference — the edit-on-a-real-photo case — so
+[`hfmlsoc/ncii-light-guard-v01`](https://huggingface.co/hfmlsoc/ncii-light-guard-v01) screens the prompt on all of
+them, before the conditioner call and before any GPU is booked. It runs in its own subprocess
+(`ncii_guard.py`): loaded in the main process, its torch activity poisons every later ZeroGPU fork.
+
+## Example assets
+
+All five files in `examples/` are from
+[`akatz-ai/H3-Character-Swap-v1`](https://huggingface.co/datasets/akatz-ai/H3-Character-Swap-v1), the LoRA's own
+training set — Apache-2.0 for Akatz Labs' synthetic contributions. They are the dataset's `CS001`, `CS051` and
+`CS090` edits, with the instructions their own captions carry:
+
+| File | Dataset path |
+|---|---|
+| `cafe_scene.mp4` | `checks/smoke-data/edits/train/scene_videos/CS001.mp4` (shared with `CS051`) |
+| `character_hiker.png` | `.../character_references/CS001.png` |
+| `character_anime.png` | `.../character_references/CS051.png` — a cross-style swap |
+| `workshop_scene.mp4` | `.../scene_videos/CS090.mp4` |
+| `character_sheet_orin.png` | `.../character_references/CS090.png` — a multi-view character sheet |
+
+## License
+
+The adapter is distributed under the
+[MiniMax H3 Community License Agreement](https://huggingface.co/akatz-ai/MiniMax-H3-Character-Swap-LoRA/blob/main/LICENSE),
+**not** Apache-2.0, and that agreement excludes the US, EU, UK and Republic of Korea from its standard territorial
+grant. Read the upstream terms; nothing here extends them. The dataset's own Apache-2.0 covers the example assets
+only and does not replace the model's terms.

app.py

@@ -0,0 +1,785 @@
+"""MiniMax-H3 Character Swap LoRA — replace one character in a shot with a reference character.
+
+`akatz-ai/MiniMax-H3-Character-Swap-LoRA` is a rank-16 ai-toolkit adapter for MiniMax-H3's **`ref2va`** partition.
+A request is two references, in the order the LoRA was trained with — the character sheet as `<Picture 1>` and the
+scene clip as `<Video 1>` — plus a short targeting instruction naming who to replace.
+
+This Space is the denoising half of `ref2va`: the `transformer_ref` partition and the two autoencoders. The Qwen3-VL
+conditioner runs in [`multimodalart/qwen3vl-conditioner`](https://huggingface.co/spaces/multimodalart/qwen3vl-conditioner),
+which this Space calls over the gradio API for every request — MiniMax-H3 is 195.9 GiB in bfloat16 and a ZeroGPU
+Space is evicted at 150 GB of storage, so the two halves cannot live together.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+import traceback
+from functools import cache
+
+# Before anything that could initialize CUDA: `import spaces` patches `torch.cuda` so the DiT load can happen at
+# startup rather than on GPU time.
+import spaces
+import gradio as gr
+import torch
+
+VERSION = "h3-character-swap/1"
+
+# The AdaLN-pruned `ref2va` partition in diffusers layout: 37.5 GiB against the released partition's 61.7 GiB, and
+# the **same** checkpoint family this LoRA was trained against — ai-toolkit trained it on Comfy-Org's
+# `minimax_h3_ref2va_pruned_int8_convrot`, i.e. an int8 ConvRot quantization of these very weights. Everything the
+# LoRA touches (the block stack's attention and feed-forward projections, and the token refiner's) is identical
+# between the pruned and the released partition; only the AdaLN input width differs, and the LoRA excludes
+# `adaln_proj` by construction (`network_kwargs.ignore_if_contains`).
+MODEL_REPO = os.environ.get("H3_MODEL_REPO", "multimodalart/MiniMax-H3-Pruned")
+LORA_REPO = os.environ.get("H3_LORA_REPO", "akatz-ai/MiniMax-H3-Character-Swap-LoRA")
+LORA_FILE = os.environ.get("H3_LORA_FILE", "h3_character_swap_pro4500_1000.safetensors")
+ADAPTER = "character_swap"
+# The model card's own recommendation: "Start with the final checkpoint at strength 1.0."
+DEFAULT_LORA_SCALE = float(os.environ.get("H3_LORA_SCALE", "1.0"))
+
+CONDITIONER_SPACE = os.environ.get("H3_CONDITIONER", "multimodalart/qwen3vl-conditioner")
+# `lazy` moves the whole partition onto the card on the first GPU call and leaves it there. Startup placement is not
+# an option: `spaces`' startup `torch.pack()` writes every startup-resident CUDA tensor to a second copy on disk, and
+# the weights plus their pack do not fit the storage quota next to the VAEs.
+PLACEMENT = os.environ.get("H3_PLACEMENT", "lazy").lower()
+# cuDNN's fused attention, 10-20% faster than the SDPA default on this pool and needs nothing installed.
+# flash-attention 3 is sm90-only and this card is sm120 (the `zero-a10g` flavour name is legacy).
+ATTENTION = os.environ.get("H3_ATTENTION", "_native_cudnn").lower()
+GPU_SIZE = os.environ.get("H3_GPU_SIZE", "xlarge")
+MIN_GPU_DURATION = int(os.environ.get("H3_GPU_DURATION_MIN", "120"))
+MAX_GPU_DURATION = int(os.environ.get("H3_GPU_DURATION_MAX", "1500"))
+
+# Must stay identical to the conditioner's table: the *label* goes over the wire, so a canvas that half does not
+# know is rejected there and surfaces as a failure here.
+CANVASES = {
+    # 16:9
+    "960x544 · 16:9 fast": (544, 960),
+    "1024x576 · 16:9 fast": (576, 1024),
+    "1152x640 · 16:9": (640, 1152),
+    "1280x704 · 16:9": (704, 1280),
+    "1344x768 · 16:9 full": (768, 1344),
+    # 9:16
+    "544x960 · 9:16 fast": (960, 544),
+    "640x1152 · 9:16": (1152, 640),
+    "768x1344 · 9:16 full": (1344, 768),
+    # 1:1
+    "544x544 · 1:1 fast": (544, 544),
+    "768x768 · 1:1 full": (768, 768),
+    "1024x1024 · 1:1 max": (1024, 1024),
+    # 4:3 / 3:4
+    "768x576 · 4:3 fast": (576, 768),
+    "1024x768 · 4:3 full": (768, 1024),
+    "576x768 · 3:4 fast": (768, 576),
+    "768x1024 · 3:4 full": (1024, 768),
+    # 21:9
+    "1152x512 · 21:9 fast": (512, 1152),
+    "1536x672 · 21:9 full": (672, 1536),
+}
+# The LoRA's own training bucket: 1344x768 at 24 fps, which is also the resolution its author sampled at.
+DEFAULT_CANVAS = "1344x768 · 16:9 full"
+# The canvases `pick_canvas` may snap a scene clip to — one per aspect family, at the LoRA's own 768 short edge.
+AUTO_CANVASES = (
+    "1344x768 · 16:9 full",
+    "768x1344 · 9:16 full",
+    "768x768 · 1:1 full",
+    "1024x768 · 4:3 full",
+    "768x1024 · 3:4 full",
+    "1536x672 · 21:9 full",
+)
+
+FPS, FRAMES_PER_CHUNK, LATENTS_PER_CHUNK = 24, 17, 5
+# It is the *snapped* frame count the ceiling has to hold for: 15 s is 360 frames, which rounds up to 362, i.e.
+# 15.083 s, and is refused. 14 is the last whole second that survives the snap.
+MAX_UI_DURATION, MIN_DURATION = 14, 2
+# 73 frames, 3.04 s — the `num_frames` the LoRA's own training run sampled at, and the length of its regularization
+# clips. Short, continuous shots are what its card reports as the promising range.
+DEFAULT_DURATION = 3
+# The scene clip is a reference video. The floor is five frames rather than the two seconds a motion reference wants,
+# because a five-frame static clip is exactly what every character-swap edit in the training set used for `<Video 1>`.
+MIN_REFERENCE_VIDEO, MAX_REFERENCE_VIDEO = 5 / FPS, 15.0
+DEFAULT_STEPS = 28
+
+# Seconds of GPU one request needs, from the packed sequence it is about to denoise: linear in the rows for the
+# matmuls, quadratic for the attention. Fitted on the `t2va` half and checked against live `ref2va` requests.
+STEP_LINEAR, STEP_QUADRATIC, SAFETY = 1.1745e-4, 3.8396e-9, 1.3
+# The lazy `PIPE.to("cuda")` a cold worker pays inside its first GPU call; every request carries it, because nothing
+# here knows whether the worker it lands on is cold.
+PLACEMENT_ALLOWANCE = int(os.environ.get("H3_PLACEMENT_ALLOWANCE", "90"))
+AUDIO_LATENTS_PER_SECOND, AUDIO_CHANNELS = 40, 2
+REFERENCE_IMAGE_SHORT_EDGE, CANVAS_MULTIPLE = 2048, 32
+DECODE_BASE, DECODE_PER_DEFAULT_CANVAS, DEFAULT_CANVAS_PIXELS = 15, 25, 960 * 544 * 124
+
+
+def snap_frames(seconds: float) -> int:
+    """The frame count MiniMax-H3's video VAE can decode: the next `17 * n + 5` at 24 fps."""
+    frames = max(1, round(float(seconds) * FPS))
+    while frames % FRAMES_PER_CHUNK != LATENTS_PER_CHUNK:
+        frames += 1
+    return frames
+
+
+def lower_duration_floor(seconds: float = MIN_DURATION) -> None:
+    """Let the pipeline generate below its 5 s floor. 56 frames (2.33 s) is fine on the released checkpoint."""
+    from diffusers.modular_pipelines.minimax_h3.modular_pipeline import MiniMaxH3ModularPipeline
+
+    MiniMaxH3ModularPipeline.min_duration = property(lambda self: float(seconds))
+
+
+def video_latent_frames(num_frames: int) -> int:
+    """`17 * n + 5` frames become `5 * n + 2` video latents."""
+    return 5 * ((num_frames - LATENTS_PER_CHUNK) // FRAMES_PER_CHUNK) + 2
+
+
+def target_rows(height: int, width: int, num_frames: int) -> int:
+    """The generated rows of the packed sequence: video patched `(1, 2, 2)`, plus two audio rows per latent."""
+    video = video_latent_frames(num_frames) * (height // CANVAS_MULTIPLE) * (width // CANVAS_MULTIPLE)
+    return video + round(num_frames / FPS * AUDIO_LATENTS_PER_SECOND) * AUDIO_CHANNELS
+
+
+def reference_rows(references: list[tuple[str, str]], num_frames: int) -> int:
+    """The rows the two reference blocks add, from metadata alone — no decode."""
+    from PIL import Image
+
+    from diffusers.modular_pipelines.minimax_h3.modular_pipeline import resolve_canvas_size
+
+    rows = 0
+    for kind, path in references:
+        if kind == "image":
+            width, height = Image.open(path).size
+            scale = REFERENCE_IMAGE_SHORT_EDGE / min(width, height)
+            resolved = [
+                max(CANVAS_MULTIPLE, round(edge * scale / CANVAS_MULTIPLE) * CANVAS_MULTIPLE)
+                for edge in (height, width)
+            ]
+            rows += (resolved[0] // CANVAS_MULTIPLE) * (resolved[1] // CANVAS_MULTIPLE)
+            continue
+
+        video_seconds, audio_seconds = probe(path)
+        if kind == "video" and video_seconds is not None:
+            import av
+
+            with av.open(path) as container:
+                stream = container.streams.video[0]
+                source_height, source_width = stream.height, stream.width
+            canvas_height, canvas_width = resolve_canvas_size(source_width, source_height, CANVAS_MULTIPLE)
+            frames = min(round(video_seconds * FPS), num_frames)
+            snapped = max(1, (frames - LATENTS_PER_CHUNK) // FRAMES_PER_CHUNK) * FRAMES_PER_CHUNK + LATENTS_PER_CHUNK
+            rows += (
+                video_latent_frames(snapped)
+                * (canvas_height // CANVAS_MULTIPLE)
+                * (canvas_width // CANVAS_MULTIPLE)
+            )
+        if audio_seconds is not None:
+            seconds = min(audio_seconds, num_frames / FPS)
+            rows += round(seconds * AUDIO_LATENTS_PER_SECOND) * AUDIO_CHANNELS
+    return rows
+
+
+def get_duration(
+    prompt_embeds, text_token_tags, references, height, width, num_frames, steps, seed, lora_scale, *_, **__
+):
+    """Seconds of GPU to reserve for one request. Takes the arguments of the `@spaces.GPU` function it decorates, and
+    tolerates the `gr.Progress` `spaces` injects."""
+    sequence = (
+        int(text_token_tags.shape[0])
+        + reference_rows(references, num_frames)
+        + target_rows(height, width, num_frames)
+    )
+    denoise = int(steps) * (STEP_LINEAR * sequence + STEP_QUADRATIC * sequence**2) * SAFETY
+    # The two reference encoders ahead of the loop, and the two decoders plus the mux after it. Both scale with what
+    # they are handed rather than with the step count.
+    encode = 5 + reference_rows(references, num_frames) * 1e-3
+    decode = DECODE_BASE + DECODE_PER_DEFAULT_CANVAS * (height * width * num_frames) / DEFAULT_CANVAS_PIXELS
+    total = PLACEMENT_ALLOWANCE + encode + denoise + decode + 10
+    duration = max(MIN_GPU_DURATION, min(MAX_GPU_DURATION, int(total)))
+    print(f"[{VERSION}] S={sequence} -> reserving {duration}s ({denoise:.0f}s of denoise at {steps} steps)", flush=True)
+    return duration
+
+
+PIPE = None
+MANAGER = None
+LOAD_ERROR: str | None = None
+LORA_STATUS: str = ""
+
+
+# ── LoRA loading (runtime PEFT adapter) ──────────────────────────────────────
+#
+# The adapter targets the checkpoint's own module names (`diffusion_model.blocks.N.attn.qkv_proj`, `mlp.fc1`/`fc2`,
+# `attn.out_proj`, and the same four under `token_refiner.blocks.N` — 208 modules, 416 tensors). diffusers serves
+# the converted port, so every name — and, for two of them, the row layout of `lora_B` — has to be pushed through
+# the same transforms `scripts/convert_minimax_h3_to_diffusers.py` applied to the base weights:
+#
+#   * `blocks.` -> `transformer_blocks.`, `token_refiner.blocks.` -> `token_refiner.refiner_blocks.`,
+#     `attn.out_proj` -> `attn.to_out.0`, `mlp.fc2` -> `ff.net.2` (pure renames),
+#   * `mlp.fc1` -> `ff.net.0.proj` with its two fused halves swapped, because diffusers' SwiGLU reads
+#     `[value; gate]` where the checkpoint stores `[gate; value]`,
+#   * `attn.qkv_proj` -> `to_q` / `to_k` / `to_v`: split `lora_B`'s 21504 rows into **contiguous** thirds of 7168
+#     (`num_attention_heads * attention_head_dim`).
+#
+# That last split is where MiniMax-H3 LoRAs diverge. diffusers' own `_convert_non_diffusers_minimax_h3_lora_to_
+# diffusers` documents two fused-QKV layouts: DiffSynth-Studio exports (identifiable by the peft `.default.` infix)
+# are *per-head interleaved* and must be de-interleaved before the split, whereas ai-toolkit exports under the
+# `diffusion_model.` prefix are already `[q_all; k_all; v_all]` and must **not** be. This file's keys are
+# `diffusion_model.…lora_A.weight` with `ai-toolkit 0.13.21` in its metadata, so it is the second kind: contiguous
+# thirds, no reorder. De-interleaving it anyway would scatter each head's q/k/v across all three projections and
+# turn the adapter into structured noise on all 52 attention blocks.
+#
+# Row transforms only ever touch `lora_B`, so the three projections share one `lora_A`: the rows of `B @ A` are just
+# the rows of `B`, which makes the split exact rather than an approximation.
+#
+# There is no AdaLN branch to reconcile: the run's `network_kwargs.ignore_if_contains = ["adaln_proj"]` kept the
+# adapter off the timestep path entirely, which is also why the pruned partition takes it verbatim.
+
+
+def _lora_target_name(source_name: str) -> str:
+    """Map an original-checkpoint module path to the diffusers one (no `.lora_A/B.*` suffix)."""
+    if source_name.startswith("token_refiner.blocks."):
+        return source_name.replace("token_refiner.blocks.", "token_refiner.refiner_blocks.", 1)
+    if source_name.startswith("blocks."):
+        return source_name.replace("blocks.", "transformer_blocks.", 1)
+    return source_name
+
+
+def _lora_modules(name: str, a_weight, b_weight, inner_dim: int):
+    """Yield `(diffusers_module_path, lora_A, lora_B)` for one original module path."""
+    target = _lora_target_name(name)
+
+    if target.endswith(".attn.qkv_proj"):
+        prefix = target.removesuffix("qkv_proj")
+        for kind, part in zip(("q", "k", "v"), b_weight.split(inner_dim, dim=0)):
+            yield f"{prefix}to_{kind}", a_weight, part.contiguous()
+    elif target.endswith(".mlp.fc1"):
+        # SwiGLU gate/value swap: the checkpoint stores [gate, value]; diffusers stores [value, gate].
+        gate, value = b_weight.chunk(2, dim=0)
+        yield target.replace(".mlp.fc1", ".ff.net.0.proj"), a_weight, torch.cat([value, gate]).contiguous()
+    elif target.endswith(".mlp.fc2"):
+        yield target.replace(".mlp.fc2", ".ff.net.2"), a_weight, b_weight
+    elif target.endswith(".attn.out_proj"):
+        yield target.replace(".attn.out_proj", ".attn.to_out.0"), a_weight, b_weight
+    else:
+        yield target, a_weight, b_weight
+
+
+def build_lora_state_dict(transformer) -> tuple[dict, int, int]:
+    """Download the LoRA and remap it into a PEFT-format state dict for the diffusers transformer.
+
+    Every target is validated against the transformer's own parameter shapes, and an unresolved one is fatal: a
+    silently dropped target means the name mapping is wrong and the Space would serve a half-applied adapter that
+    still *looks* like it worked.
+    """
+    from huggingface_hub import hf_hub_download
+    from safetensors.torch import load_file
+
+    raw = load_file(hf_hub_download(LORA_REPO, LORA_FILE))
+
+    prefix, suffix_a, suffix_b = "diffusion_model.", ".lora_A.weight", ".lora_B.weight"
+    unexpected = [k for k in raw if not (k.startswith(prefix) and k.endswith((suffix_a, suffix_b)))]
+    if unexpected:
+        raise ValueError(f"{LORA_FILE} holds {len(unexpected)} unexpected tensors, e.g. {unexpected[:5]}")
+    bases = sorted({k[len(prefix) : -len(suffix_a)] for k in raw if k.endswith(suffix_a)})
+    if not bases:
+        raise ValueError(f"No `{prefix}*{suffix_a}` / `{suffix_b}` pairs found in {LORA_FILE}")
+
+    ranks = set()
+    for name in bases:
+        if f"{prefix}{name}{suffix_b}" not in raw:
+            raise ValueError(f"LoRA is missing the lora_B twin of {prefix}{name}{suffix_a}")
+        ranks.add(raw[f"{prefix}{name}{suffix_a}"].shape[0])
+    if len(ranks) != 1:
+        raise ValueError(f"LoRA mixes ranks {sorted(ranks)}; this loader assumes a single rank")
+    rank = ranks.pop()
+
+    inner_dim = transformer.config.num_attention_heads * transformer.config.attention_head_dim
+    base_shapes = {key: tuple(value.shape) for key, value in transformer.state_dict().items()}
+
+    state_dict: dict[str, torch.Tensor] = {}
+    missed: list[str] = []
+    for name in bases:
+        a_weight = raw[f"{prefix}{name}{suffix_a}"]
+        b_weight = raw[f"{prefix}{name}{suffix_b}"]
+        for module, a_part, b_part in _lora_modules(name, a_weight, b_weight, inner_dim):
+            base = base_shapes.get(f"{module}.weight")
+            if base is None:
+                missed.append(module)
+                continue
+            # `W` is [out, in]; the adapter must be `lora_B` [out, r] @ `lora_A` [r, in].
+            if (b_part.shape[0], a_part.shape[1]) != base:
+                raise ValueError(
+                    f"LoRA delta for `{module}` would be {(b_part.shape[0], a_part.shape[1])}, "
+                    f"base weight is {base}"
+                )
+            state_dict[f"{module}.lora_A.weight"] = a_part
+            state_dict[f"{module}.lora_B.weight"] = b_part
+    if missed:
+        raise ValueError(
+            f"{len(missed)} LoRA targets matched no transformer weight, e.g. {missed[:5]}. "
+            "The LoRA and the diffusers transformer disagree on module naming."
+        )
+
+    return state_dict, rank, len(bases)
+
+
+def load_and_apply_lora(transformer) -> str:
+    """Attach the LoRA as a PEFT adapter so its strength stays a per-request knob."""
+    state_dict, rank, targets = build_lora_state_dict(transformer)
+    # `prefix=None` because the keys are already the transformer's own module paths, and no `network_alphas` because
+    # the file carries no `.alpha` tensors — PEFT then sets alpha == rank, which is also what the run trained with
+    # (`linear: 16`, `linear_alpha: 16`), so the adapter's intrinsic scale is 1.0 and the slider *is* the strength.
+    transformer.load_lora_adapter(state_dict, prefix=None, adapter_name=ADAPTER)
+    transformer.set_adapters([ADAPTER], [DEFAULT_LORA_SCALE])
+    return (
+        f"LoRA attached · {targets} checkpoint targets -> {len(state_dict) // 2} diffusers modules, "
+        f"rank {rank}, alpha == rank · default strength {DEFAULT_LORA_SCALE:g} · {LORA_FILE}"
+    )
+
+
+def check_prompt(prompt: str) -> None:
+    """The NCII guard. Every request here carries an image and a video reference — the edit-on-a-real-photo case — so
+    it runs on all of them, before the conditioner call and the denoise booking, and a refused prompt costs no GPU
+    time on either half. The classifier lives in `ncii_guard`'s spawned subprocess; in the main process it kills
+    every GPU worker."""
+    import ncii_guard
+
+    flag = ncii_guard.classify(prompt)
+    if flag["label"] == "ncii":
+        print(f"[guard] prompt refused (ncii {flag['score']:.2f}): {prompt!r}", flush=True)
+        raise gr.Error("This prompt was flagged by a content filter and wasn't run.")
+
+
+def load_models() -> str | None:
+    """Load the denoising half at startup, but *not* onto the card.
+
+    `MiniMaxH3Ref2VAGeneratorBlocks` declares `transformer_ref`, `vae`, `audio_vae`, the two schedulers and
+    `video_processor`, so `load_components` fetches exactly those subfolders — `text_encoder/` and the `transformer/`
+    partition are never touched. Both autoencoders carry `_keep_in_fp32_modules` over every module and stay float32:
+    a bfloat16 audio VAE decodes the soundtrack roughly 20 dB too quiet.
+    """
+    global PIPE, MANAGER, LOAD_ERROR, LORA_STATUS
+
+    if PIPE is not None or LOAD_ERROR is not None:
+        return LOAD_ERROR
+
+    started = time.time()
+    try:
+        from diffusers import ComponentsManager
+
+        from h3_split_blocks import MiniMaxH3Ref2VAGeneratorBlocks
+
+        lower_duration_floor()
+        manager = ComponentsManager()
+        blocks = MiniMaxH3Ref2VAGeneratorBlocks()
+        print(f"[{VERSION}] loading {[c.name for c in blocks.expected_components]} from {MODEL_REPO} ...", flush=True)
+        pipe = blocks.init_pipeline(MODEL_REPO, components_manager=manager, collection="h3")
+        # The pruned DiT is served as remote code (`transformer_ref/modeling_minimax_h3_pruned.py`, reached through
+        # the `AutoModel` type hint in `modular_model_index.json`). `load_components` forwards `trust_remote_code`
+        # only to components that live in the pipeline's own repo, so the two VAEs and the schedulers — which
+        # `modular_model_index.json` still points at `MiniMaxAI/MiniMax-H3` — never see it.
+        pipe.load_components(dtype=torch.bfloat16, trust_remote_code=True)
+
+        # Both VAEs first, and explicitly. `set_attention_backend` also sets the registry's *global* backend, which
+        # every processor that was not stamped falls through to, and the float32 audio VAE has no cuDNN kernel:
+        # `RuntimeError: No available kernel. Aborting execution.` in its causal encoder attention.
+        pipe.vae.set_attention_backend("native")
+        pipe.audio_vae.set_attention_backend("native")
+        pipe.transformer_ref.set_attention_backend(ATTENTION)
+
+        # Before any GPU placement, so the adapter's parameters travel with the transformer. No AoTI on this Space
+        # for the same reason: a compiled block package binds the *base* module's weights by fully qualified name
+        # and would run straight past the PEFT branch.
+        LORA_STATUS = load_and_apply_lora(pipe.transformer_ref)
+        print(f"[{VERSION}] {LORA_STATUS}", flush=True)
+
+        # Installed per request rather than here — a cached residual only means something within the schedule it was
+        # measured on, so the state cannot outlive one generation.
+        import h3_fbc
+
+        print(f"[h3-fbc] {h3_fbc.status()}", flush=True)
+
+        if PLACEMENT == "offload":
+            manager.enable_auto_cpu_offload(device="cuda")
+            _arm_decode_hooks(pipe)
+
+        PIPE, MANAGER = pipe, manager
+        print(f"[{VERSION}] ready in {time.time() - started:.0f}s", flush=True)
+    except Exception as error:
+        traceback.print_exc()
+        LOAD_ERROR = (
+            f"**Loading `{MODEL_REPO}` + `{LORA_REPO}` failed** after {time.time() - started:.0f}s: "
+            f"`{type(error).__name__}: {error}`"
+        )
+    return LOAD_ERROR
+
+
+def _arm_decode_hooks(pipe):
+    """Make the offload hooks fire for the two VAEs.
+
+    `enable_auto_cpu_offload` wraps `forward`, and the reference-encoder and decode blocks call `vae.encode/decode(...)`
+    directly, so the hook never runs and the VAE is still on the host when the latents arrive on the card.
+    """
+    for name in ("vae", "audio_vae"):
+        module = getattr(pipe, name)
+        for method in ("encode", "decode"):
+            inner = getattr(module, method)
+
+            def armed(*args, _module=module, _inner=inner, **kwargs):
+                hook = getattr(_module, "_hf_hook", None)
+                if hook is not None:
+                    hook.pre_forward(_module)
+                return _inner(*args, **kwargs)
+
+            setattr(module, method, armed)
+
+
+@cache
+def conditioner():
+    """The other half, over the gradio API. `gradio_client` attaches the caller's own ZeroGPU token per call, so the
+    conditioner's booking is billed to whoever asked for the video."""
+    from gradio_client import Client
+
+    return Client(CONDITIONER_SPACE)
+
+
+def probe(path: str) -> tuple[float | None, float | None]:
+    """`(video seconds, audio seconds)` of a media file, either being `None` when the stream is absent."""
+    import av
+
+    def seconds(stream, container):
+        if stream.duration is not None and stream.time_base is not None:
+            return float(stream.duration * stream.time_base)
+        return None if container.duration is None else container.duration / av.time_base
+
+    with av.open(path) as container:
+        video = seconds(container.streams.video[0], container) if container.streams.video else None
+        audio = seconds(container.streams.audio[0], container) if container.streams.audio else None
+    return video, audio
+
+
+def collect(character_path: str, scene_path: str) -> list[tuple[str, str]]:
+    """The `(kind, path)` references of a request, **in the order the model reads them**.
+
+    The character sheet first, the scene clip second. That order is not cosmetic and it is not the order the prompt
+    names them in: it numbers the labels of MiniMax-H3's prompt presentation and it advances the shared audio/video
+    rotary clock, so the same two references swapped round are a different request. It is the order the LoRA was
+    trained with — `control_path: [character_references, scene_videos]` in `configs/trained-run-1000.json` of
+    `akatz-ai/H3-Character-Swap-v1` — which is why the captions read `<Video 1>` before `<Picture 1>` while the
+    references go the other way: the labels are numbered per modality, not by position.
+    """
+    return [("image", character_path), ("video", scene_path)]
+
+
+def build_references(references: list[tuple[str, str]]):
+    """The `(kind, path)` references of a request as decoded reference dataclasses, in packed order. `from_file`
+    brings the rates along: a video its own frame rate and soundtrack."""
+    from diffusers.modular_pipelines.minimax_h3 import (
+        MiniMaxH3ImageReference,
+        MiniMaxH3VideoReference,
+    )
+
+    classes = {"image": MiniMaxH3ImageReference, "video": MiniMaxH3VideoReference}
+    return [classes[kind].from_file(path) for kind, path in references]
+
+
+def pick_canvas(scene_path: str | None) -> str:
+    """The generated canvas whose aspect ratio is closest to the scene clip's, at the LoRA's own 768 short edge.
+
+    A character swap is asked to keep the source framing, so a portrait clip generated on a landscape canvas is a
+    recomposed shot before the model has done anything. Wired to the clip's `change`, so the dropdown shows what a
+    request will actually use and stays overridable.
+    """
+    if not scene_path:
+        return gr.update()
+    try:
+        import av
+
+        with av.open(scene_path) as container:
+            stream = container.streams.video[0]
+            ratio = stream.width / stream.height
+    except Exception:
+        return gr.update()
+    best = min(AUTO_CANVASES, key=lambda label: abs(CANVASES[label][1] / CANVASES[label][0] - ratio))
+    return gr.update(value=best)
+
+
+def check(prompt: str, character_path: str | None, scene_path: str | None) -> None:
+    """The request's own rules, before anything is uploaded or a card is allocated."""
+    if not prompt or not prompt.strip():
+        raise gr.Error("Name who to replace — MiniMax-H3 always takes a prompt.")
+    if not scene_path:
+        raise gr.Error("Add the scene clip to edit; it is the request's `<Video 1>`.")
+    if not character_path:
+        raise gr.Error("Add the character reference to swap in; it is the request's `<Picture 1>`.")
+    video_seconds, _ = probe(scene_path)
+    if video_seconds is None:
+        raise gr.Error("That scene clip has no video stream.")
+    if not MIN_REFERENCE_VIDEO <= video_seconds <= MAX_REFERENCE_VIDEO:
+        raise gr.Error(
+            f"The scene clip is {video_seconds:.2f} s. Use one between {MIN_REFERENCE_VIDEO:.2f} and "
+            f"{MAX_REFERENCE_VIDEO:g} seconds."
+        )
+
+
+def encode_remote(prompt, references, canvas, num_frames):
+    """`/encode_ref2va` on the conditioner Space: a safetensors file holding `prompt_embeds` + `text_token_tags`,
+    with the resolved `height` / `width` / `num_frames` in its metadata, plus the plan.
+
+    `canvas` is the label. `media` and `kinds` are parallel and ordered, and the references go over because `ref2va`'s
+    presentation puts a vision block in front of the prompt for every image and every merged video frame pair.
+    """
+    from gradio_client import handle_file
+    from safetensors import safe_open
+
+    path, plan = conditioner().predict(
+        prompt=prompt,
+        media=[handle_file(path) for _, path in references],
+        kinds=",".join(kind for kind, _ in references),
+        canvas=canvas,
+        num_frames=num_frames,
+        rewrite_prompt=False,
+        api_name="/encode_ref2va",
+    )
+    with safe_open(path, framework="pt") as handle:
+        return handle.get_tensor("prompt_embeds"), handle.get_tensor("text_token_tags"), handle.metadata(), plan
+
+
+@spaces.GPU(duration=get_duration, size=GPU_SIZE)
+def _generate(prompt_embeds, text_token_tags, references, height, width, num_frames, steps, seed, lora_scale):
+    """The only thing on GPU time: the two reference encoders, the packed-sequence denoise loop and the decoders.
+
+    References cross as paths and are decoded here; only the three generated outputs come back. A `@spaces.GPU`
+    argument crosses a process boundary by pickling, a 5 s 1344x768 reference video is 370 MB of expanded frames, and
+    the full `PipelineState` still holds the packed latents and the rotary grid on the card.
+    """
+    import h3_fbc
+
+    if PLACEMENT == "lazy":
+        PIPE.to("cuda")
+
+    # Per request, inside the worker: the adapter's scale is a python attribute on its PEFT layers, so setting it on
+    # this fork's copy leaves every concurrent request with its own strength.
+    PIPE.transformer_ref.set_adapters([ADAPTER], [float(lora_scale)])
+
+    with h3_fbc.enabled(PIPE.transformer_ref, steps=int(steps)):
+        state = PIPE(
+            prompt_embeds=prompt_embeds.to("cuda"),
+            text_token_tags=text_token_tags,
+            references=build_references(references),
+            height=height,
+            width=width,
+            num_frames=num_frames,
+            num_inference_steps=int(steps),
+            generator=torch.Generator("cpu").manual_seed(int(seed)),
+        )
+    return state.get("videos")[0], state.get("audio")[0].cpu(), state.get("sampling_rate")
+
+
+def generate(
+    # The first three are the columns `gr.Examples` varies, and they lead the signature for that reason: an example
+    # row is applied to `inputs` positionally. Every other parameter carries the same default as its UI component,
+    # so clicking an example and pressing Generate behave identically.
+    prompt: str,
+    scene_video: str | None = None,
+    character_image: str | None = None,
+    canvas: str = DEFAULT_CANVAS,
+    match_length: bool = True,
+    duration: float = DEFAULT_DURATION,
+    steps: int = DEFAULT_STEPS,
+    seed: int = 904231,
+    lora_scale: float = DEFAULT_LORA_SCALE,
+    progress=gr.Progress(track_tqdm=True),
+):
+    """Replace one character in a clip with the character in a reference image, keeping the rest of the shot.
+
+    Args:
+        prompt: who to replace and with what, naming the references as `<Video 1>` and `<Picture 1>`, e.g.
+            "Swap the man in the purple shirt in <Video 1> with the character in <Picture 1>."
+        scene_video: path to the clip to edit — the request's `<Video 1>`, 5 frames to 15 seconds.
+        character_image: path to the replacement character's portrait or character sheet — `<Picture 1>`.
+        canvas: the generated canvas, as one of this Space's labels.
+        match_length: generate for as long as the scene clip runs, when that length is one MiniMax-H3 generates.
+        duration: seconds to generate when `match_length` is off, or the clip is too short to set it.
+        steps: denoising steps. The LoRA's own training run sampled at 28.
+        seed: RNG seed.
+        lora_scale: character-swap adapter strength. 1.0 is the card's recommendation; 0 is the base model.
+
+    Returns:
+        Path to the generated MP4, video and its jointly generated soundtrack.
+    """
+    if LOAD_ERROR:
+        raise gr.Error(LOAD_ERROR)
+    if PIPE is None:
+        raise gr.Error("The denoiser is still loading.")
+
+    from diffusers.utils import encode_video
+
+    check(prompt, character_image, scene_video)
+    check_prompt(prompt)
+    references = collect(character_image, scene_video)
+
+    scene_seconds, _ = probe(scene_video)
+    requested_seconds = float(duration)
+    if match_length and scene_seconds is not None and MIN_DURATION <= scene_seconds <= MAX_UI_DURATION:
+        requested_seconds = scene_seconds
+    num_frames = snap_frames(requested_seconds)
+
+    progress(0.0, desc="Reading the prompt and the two references ...")
+    conditioned = time.time()
+    try:
+        prompt_embeds, text_token_tags, metadata, plan = encode_remote(prompt, references, canvas, num_frames)
+    except gr.Error:
+        raise
+    except Exception as error:
+        # gradio only puts the exception *type* on the wire, so the useful half of a conditioner-side failure is in
+        # that Space's logs.
+        traceback.print_exc()
+        raise gr.Error(
+            f"The conditioner ({CONDITIONER_SPACE}) failed with `{type(error).__name__}: {error}`. "
+            "Its logs carry the full traceback."
+        ) from error
+    condition_seconds = time.time() - conditioned
+    height, width, num_frames = (int(metadata[key]) for key in ("height", "width", "num_frames"))
+
+    progress(0.1, desc=f"Swapping over {num_frames / FPS:.1f} s at {width}x{height} ...")
+    started = time.time()
+    frames, audio, sampling_rate = _generate(
+        prompt_embeds, text_token_tags, references, height, width, num_frames, steps, seed, lora_scale
+    )
+    generate_seconds = time.time() - started
+
+    directory = os.path.join(tempfile.gettempdir(), "h3-outputs")
+    os.makedirs(directory, exist_ok=True)
+    path = os.path.join(directory, f"h3-character-swap-{int(time.time() * 1000)}.mp4")
+    encode_video(frames, fps=FPS, output_path=path, audio=audio, audio_sample_rate=sampling_rate)
+
+    print(
+        f"[{VERSION}] `{width}x{height}`, {num_frames} frames ({num_frames / FPS:.3f} s), {int(steps)} steps, "
+        f"strength {float(lora_scale):g} · conditioner {condition_seconds:.0f}s "
+        f"({plan['num_text_tokens']} tokens) · denoise + decode {generate_seconds:.0f}s "
+        f"({generate_seconds / max(1, int(steps)):.1f} s/step) · seed {int(seed)}",
+        flush=True,
+    )
+    return path
+
+
+import ncii_guard
+
+ncii_guard.start()
+load_models()
+
+INTRO = """# MiniMax-H3 Character Swap LoRA
+
+<div align="center">
+  <a href="https://huggingface.co/akatz-ai/MiniMax-H3-Character-Swap-LoRA" target="_blank" rel="noopener"><strong>[ LoRA ]</strong></a> &nbsp;
+  <a href="https://huggingface.co/datasets/akatz-ai/H3-Character-Swap-v1" target="_blank" rel="noopener"><strong>[ dataset ]</strong></a> &nbsp;
+  <a href="https://huggingface.co/MiniMaxAI/MiniMax-H3" target="_blank" rel="noopener"><strong>[ base model ]</strong></a>
+</div>
+
+Give it a **scene clip** and a **character reference**, then name who to replace. Akatz Labs' experimental
+character-swap adapter for MiniMax-H3 `ref2va` puts the reference character into the shot — identity, outfit and
+art style carried over — while the background, the camera and everyone else stay where they were. Video and its
+soundtrack come out of one denoising pass.
+
+Refer to the two references the way the LoRA was trained to read them: the clip is **`<Video 1>`** and the
+character is **`<Picture 1>`**.
+"""
+
+NOTES = """It is an experimental 1,000-update adapter and its own card is candid about the limits: motion timing,
+facial expressions and hard cuts are unreliable, long windows drift in framing, and close-up expressions may not
+match the source performance. Short continuous shots of about 3–5 seconds are the promising range.
+
+Its training targets were **single still frames** with five-frame static scene clips, which is what the examples
+below are — a still scene, handed over as the short clip `<Video 1>` wants. Real moving footage works the same way
+and is what the 40 preservation clips in the dataset regularized, but it is the harder case.
+
+Strength 1.0 is the author's recommendation; 0 is the base `ref2va` model, which is the comparison the adapter was
+judged against.
+"""
+
+CSS = """
+.main.fillable { max-width: 1250px !important; }
+.dark .gradio-container { color: var(--body-text-color); }
+"""
+
+with gr.Blocks(title="MiniMax-H3 Character Swap LoRA", theme=gr.themes.Citrus(), css=CSS) as demo:
+    gr.Markdown(INTRO)
+
+    with gr.Row():
+        with gr.Column():
+            prompt = gr.Textbox(
+                label="Prompt — name the person to replace",
+                lines=3,
+                value="Swap the man in the purple shirt in <Video 1> with the character in <Picture 1>.",
+                placeholder="Swap the woman on the left in <Video 1> with the character in <Picture 1>.",
+            )
+            with gr.Row():
+                scene = gr.Video(label="Scene clip · <Video 1>", height=260)
+                character = gr.Image(label="Character reference · <Picture 1>", type="filepath", height=260)
+            run = gr.Button("Swap the character", variant="primary", size="lg")
+            with gr.Accordion("Advanced options", open=False):
+                lora_scale = gr.Slider(
+                    label="Character-swap LoRA strength",
+                    minimum=0.0,
+                    maximum=1.5,
+                    step=0.05,
+                    value=DEFAULT_LORA_SCALE,
+                )
+                canvas = gr.Dropdown(
+                    label="Canvas (follows the scene clip's aspect ratio)",
+                    choices=list(CANVASES),
+                    value=DEFAULT_CANVAS,
+                )
+                match_length = gr.Checkbox(label="Match the scene clip's length", value=True)
+                duration = gr.Slider(
+                    label="Duration (s) — used when the clip is shorter than the model generates",
+                    minimum=MIN_DURATION,
+                    maximum=MAX_UI_DURATION,
+                    step=1,
+                    value=DEFAULT_DURATION,
+                )
+                steps = gr.Slider(label="Steps", minimum=10, maximum=40, step=1, value=DEFAULT_STEPS)
+                seed = gr.Number(label="Seed", value=904231, precision=0)
+
+        with gr.Column():
+            result = gr.Video(label="Swapped clip + soundtrack")
+            gr.Markdown(NOTES)
+
+    scene.change(pick_canvas, scene, canvas, show_progress="hidden", api_name=False)
+
+    request = [prompt, scene, character, canvas, match_length, duration, steps, seed, lora_scale]
+
+    gr.Examples(
+        # The dataset's own edits, with the instructions its captions carry: a photoreal swap, a cross-style swap
+        # onto an illustrated character, and a multi-view character sheet.
+        examples=[
+            [
+                "Swap the man in the purple shirt in <Video 1> with the character in <Picture 1>.",
+                "examples/cafe_scene.mp4",
+                "examples/character_hiker.png",
+            ],
+            [
+                "Swap the man in the purple shirt in <Video 1> with the character in <Picture 1>. Keep the "
+                "replacement character's identity, outfit and art style from <Picture 1>. Preserve the source "
+                "video's camera, background, lighting, objects and all other people.",
+                "examples/cafe_scene.mp4",
+                "examples/character_anime.png",
+            ],
+            [
+                "Swap the person in <Video 1> with the character in <Picture 1>. Do not show the reference sheet "
+                "or its background.",
+                "examples/workshop_scene.mp4",
+                "examples/character_sheet_orin.png",
+            ],
+        ],
+        inputs=[prompt, scene, character],
+        outputs=result,
+        fn=generate,
+        cache_examples=True,
+        cache_mode="lazy",
+    )
+
+    run.click(generate, request, result, api_name="generate")
+
+
+if __name__ == "__main__":
+    demo.launch(show_error=True, max_threads=1000)

examples/cafe_scene.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3d1dbc1b503df47708aa2b1a49d2987078e1edb2954d0f28ee30650823ce0488
+size 923206

examples/workshop_scene.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fa1b341d2bb03a786b95457a1705d6fda46e7ebaa0baf205bf8a36c70662ee4a
+size 766362

h3_fbc.py

@@ -0,0 +1,357 @@
+"""First-block cache for MiniMax-H3: skip the trunk on steps whose block-0 residual barely moved.
+
+Block 0 and the final AdaLN head run at the true timestep on **every** step; only blocks 1..49 are skipped, and only
+while the residual they would have been handed looks like the one from the last step that actually ran. The decision
+signal is the relative L1 between this step's block-0 residual (`block0_out - block0_in`) and the residual of the last
+*computed* step, over the whole packed sequence. On a skip the trunk's contribution is replayed as a cached residual,
+`(final_trunk_out - block0_out)` of that computed step.
+
+Ported from `duckyshell/ComfyUI-MiniMaxH3-FirstBlockCache` (`nodes.py` @ 725973c) — same signal, same protected window
+(10%-95% of the schedule, converted through the video shift of 12.0) and the same cap of two consecutive skips, which
+is their "H3 Safe" preset at threshold 0.08.
+
+**The audio exemption is not theirs.** duckyshell has no audio term anywhere: the decision is ~98% video by row count
+and every audio row rides the stale trunk residual, which is what costs the soundtrack its energy. Audio runs its own
+schedule (shift 3 against video's 12, diverging by up to 11x in rate across 20 steps), so on a skip the audio rows of
+the trunk output are instead a 2-point **linear** extrapolation of the last two actually-computed audio features, in
+the audio sigma coordinate — `xmarre/ComfyUI-Spectrum-MiniMax-H3`'s `audio_blend_weight=0.0` path, applied where
+Spectrum applies it (the post-trunk hidden feature, ahead of the head that still runs at the true timestep) and fixed
+to the right coordinate. Following ComfyUI PR #15390, no carried audio tensor is ever mutated: every write is a fresh
+tensor out of `index_copy`.
+
+It earns its place. Running this Space's own request at threshold 0.08 with `H3_FBC_AUDIO_EXEMPT=0` — the duckyshell
+mechanism verbatim, same 13 skipped forwards, same video to within 0.2 dB — costs the soundtrack **16.7% of its RMS**
+(0.0483 against an uncached 0.0580), while the exemption holds it at 1.04x. That is the same direction the offline
+study measured on a near-silent clip, three times the size on one with real audio energy.
+
+**A threshold does not travel across step counts.** The signature shrinks as the schedule is subdivided, so the same
+number gates far more loosely at more steps. Measured on this Space — 960x544, 124 frames, one image reference,
+seed 42, AoTI blocks, at its **default 28 steps** (27 forwards) — against the same request with `H3_FBC=0`:
+
+| threshold | skipped | denoise loop | end to end | audio RMS vs uncached |
+|---|---|---|---|---|
+| 0.03 | 0 / 27 | 1.02x | 1.06x | 1.000 (bitwise-identical audio) |
+| 0.05 | 9 / 27 | 1.46x | 1.36x | 0.956 |
+| 0.08 | 13 / 27 | 2.19x | 1.82x | 1.040 |
+
+The offline study calibrated 0.08 over a 20-step schedule, where it skipped 7 of 19 forwards. At 28 steps that same
+0.08 skips 13 of 27 — nearly half — and the sampled video visibly re-rolls its background detail. **0.05 is the
+default** because it reproduces the skip fraction that study validated (33% here against 37% there); 0.08 is the
+aggressive setting. Below the signature floor — 0.03 skipped nothing at all here — a threshold buys nothing and still
+pays for the signature, so lower is not safer, it is just slower.
+
+A cached request is not the uncached one: the trajectory moves, so the video is a different sample of the same prompt
+(same shot, same subject, same quality — different signage and background detail). `H3_FBC=0` restores today's output
+exactly, and is worth reaching for when a request has to reproduce a specific earlier result.
+
+This composes with `h3_aoti`: that module patches each of the 50 blocks' own `forward` and they stay a real
+`ModuleList`, so skipping the trunk simply does not call blocks 1..49 that step. `LazyAOTIModel` rebinds its constants
+whenever the weights dict it is handed changes identity, and the first forward of a request never skips, so every
+block has bound its own weights before any step is cached.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import types
+
+ENABLED = os.environ.get("H3_FBC", "1") == "1"
+# Relative-L1 gate on the block-0 residual, calibrated at this Space's default 28 steps — see the table above.
+THRESHOLD = float(os.environ.get("H3_FBC_THRESHOLD", "0.05"))
+# duckyshell's cap. Without it the gate compares against an ever-older computed step and drifts away unbounded.
+MAX_CONSECUTIVE_HITS = int(os.environ.get("H3_FBC_MAX_CONSECUTIVE", "2"))
+# The protected head and tail of the schedule, as fractions, converted to sigma through the video shift below.
+START_PERCENT = float(os.environ.get("H3_FBC_START_PERCENT", "0.10"))
+END_PERCENT = float(os.environ.get("H3_FBC_END_PERCENT", "0.95"))
+# `MiniMaxH3SetTimestepsStep` builds the video schedule at shift 12.0 and the audio one at 3.0.
+VIDEO_SHIFT = float(os.environ.get("H3_FBC_VIDEO_SHIFT", "12.0"))
+AUDIO_EXEMPT = os.environ.get("H3_FBC_AUDIO_EXEMPT", "1") == "1"
+
+# Every keyword `MiniMaxH3LoopDenoiser` passes. It filters the packed-sequence layout through
+# `inspect.signature(transformer.forward).parameters`, so a replacement forward that drops a name silently stops
+# receiving it; `install` refuses rather than let that happen quietly.
+FORWARD_PARAMETERS = (
+    "hidden_states",
+    "audio_hidden_states",
+    "encoder_hidden_states",
+    "timestep",
+    "timestep_indices",
+    "token_tags",
+    "position_ids",
+    "video_indices",
+    "audio_indices",
+    "text_indices",
+    "attention_kwargs",
+    "return_dict",
+)
+
+
+def status() -> str:
+    return (
+        f"first-block cache **on** · threshold `{THRESHOLD}` · audio exemption "
+        f"{'on' if AUDIO_EXEMPT else 'off'}"
+        if ENABLED
+        else "first-block cache **off** (`H3_FBC=1` to skip the trunk on steady steps)"
+    )
+
+
+def _shifted_sigma(u: float, shift: float) -> float:
+    return shift * u / (1.0 + (shift - 1.0) * u)
+
+
+def _rel_l1(current, previous) -> float:
+    numerator = (current.float() - previous.float()).abs().mean()
+    denominator = previous.float().abs().mean().clamp(min=1e-8)
+    return float((numerator / denominator).item())
+
+
+class _State:
+    def __init__(self, threshold: float, steps: int, audio_exempt: bool):
+        self.threshold = threshold
+        self.steps = steps
+        self.audio_exempt = audio_exempt
+        # duckyshell reads the window as sigma bounds: a flow model's sigma at `u = 1 - percent`, shifted.
+        self.start_sigma = _shifted_sigma(1.0 - START_PERCENT, VIDEO_SHIFT)
+        self.end_sigma = _shifted_sigma(1.0 - END_PERCENT, VIDEO_SHIFT)
+        self.original = None
+        self.failed = False
+        self.consecutive_hits = 0
+        self.prev_first_residual = None
+        self.tail_residual = None
+        self.audio_history = []  # [(sigma_audio, audio rows of the trunk output)], newest last, at most two
+        self.computed = 0
+        self.skipped = 0
+
+
+def _cached_forward(
+    self,
+    state,
+    hidden_states,
+    audio_hidden_states,
+    encoder_hidden_states,
+    timestep,
+    timestep_indices,
+    token_tags,
+    position_ids,
+    video_indices,
+    audio_indices,
+    text_indices,
+    return_dict,
+):
+    """`MiniMaxH3Transformer3DModel.forward` with the block loop split at block 0.
+
+    Everything outside the loop is that method verbatim, at the `diffusers` commit `requirements.txt` pins; keep the
+    two in step when the pin moves.
+    """
+    import torch
+
+    from diffusers.models.transformers.transformer_minimax_h3 import (
+        MINIMAX_H3_MODALITY_NUM,
+        MiniMaxH3TransformerOutput,
+    )
+
+    sequence_length = position_ids.shape[0]
+    rotary_emb = self.rope(position_ids)
+
+    video_embeds = self.proj_in(hidden_states.to(self.proj_in.weight.dtype))
+    audio_embeds = self.audio_proj_in(audio_hidden_states.to(self.audio_proj_in.weight.dtype))
+    text_embeds = self.context_embedder(encoder_hidden_states.to(self.context_embedder.weight.dtype))
+    text_embeds = self.token_refiner(text_embeds)
+
+    packed = text_embeds.new_zeros((text_embeds.shape[0], sequence_length, text_embeds.shape[-1]))
+    packed = packed.index_copy(1, text_indices, text_embeds)
+    packed = packed.index_copy(1, video_indices, video_embeds.to(text_embeds.dtype))
+    packed = packed.index_copy(1, audio_indices, audio_embeds.to(text_embeds.dtype))
+
+    temb = self.time_proj(timestep)
+    temb = self.time_embedder(temb.to(self.time_embedder.linear_1.weight.dtype))
+    adaln_indices = timestep_indices * MINIMAX_H3_MODALITY_NUM + token_tags.clamp(min=0)
+
+    attention_mask = None
+    is_pad = token_tags < 0
+    if bool(is_pad.any()):
+        attention_mask = is_pad[None, :] == is_pad[:, None]
+
+    blocks = self.transformer_blocks
+    block0_out = blocks[0](packed, temb, adaln_indices, rotary_emb, attention_mask)
+    first_residual = block0_out - packed
+
+    # The generated rows trail their modality's index list, so the last row of each carries that stream's live noise
+    # level. The scheduler exposes `timesteps = 1 - sigmas[:-1]`.
+    sigma_video = 1.0 - float(timestep[timestep_indices[video_indices[-1]]].item())
+    sigma_audio = 1.0 - float(timestep[timestep_indices[audio_indices[-1]]].item())
+
+    use_cache = False
+    if (
+        state.prev_first_residual is not None
+        and state.tail_residual is not None
+        and state.prev_first_residual.shape == first_residual.shape
+        and state.consecutive_hits < MAX_CONSECUTIVE_HITS
+        and state.end_sigma <= sigma_video <= state.start_sigma
+    ):
+        use_cache = _rel_l1(first_residual, state.prev_first_residual) <= state.threshold
+
+    if use_cache:
+        state.consecutive_hits += 1
+        state.skipped += 1
+        trunk_out = block0_out + state.tail_residual
+        if state.audio_exempt and state.audio_history:
+            sigma_prev, feature_prev = state.audio_history[-1]
+            if len(state.audio_history) == 2 and abs(sigma_prev - state.audio_history[-2][0]) > 1e-8:
+                sigma_prev2, feature_prev2 = state.audio_history[-2]
+                ratio = (sigma_audio - sigma_prev) / (sigma_prev - sigma_prev2)
+                audio_feature = feature_prev + (feature_prev - feature_prev2) * ratio
+            else:
+                audio_feature = feature_prev
+            trunk_out = trunk_out.index_copy(1, audio_indices, audio_feature.to(trunk_out.dtype))
+    else:
+        state.consecutive_hits = 0
+        state.computed += 1
+        trunk_out = block0_out
+        for block in blocks[1:]:
+            trunk_out = block(trunk_out, temb, adaln_indices, rotary_emb, attention_mask)
+        state.tail_residual = (trunk_out - block0_out).detach()
+        state.prev_first_residual = first_residual.detach()
+        if state.audio_exempt:
+            state.audio_history.append((sigma_audio, trunk_out.index_select(1, audio_indices).detach().float()))
+            state.audio_history = state.audio_history[-2:]
+
+    out = self.norm_out(trunk_out, temb, timestep_indices).to(self.proj_out.weight.dtype)
+    video_output = self.proj_out(out).index_select(1, video_indices)
+    audio_output = self.audio_proj_out(out).index_select(1, audio_indices)
+
+    if not return_dict:
+        return (video_output, audio_output)
+    return MiniMaxH3TransformerOutput(sample=video_output, audio_sample=audio_output)
+
+
+def _forward(
+    self,
+    hidden_states,
+    audio_hidden_states,
+    encoder_hidden_states,
+    timestep,
+    timestep_indices,
+    token_tags,
+    position_ids,
+    video_indices,
+    audio_indices,
+    text_indices,
+    attention_kwargs=None,
+    return_dict: bool = True,
+):
+    """The installed forward. Anything it cannot serve — a LoRA scale, an unexpected layout, a bug — is handed to the
+    original forward instead, for this call and every later one, so a cached request can degrade to an uncached one but
+    never to a failed one."""
+    state = self._h3_fbc
+    original = dict(
+        hidden_states=hidden_states,
+        audio_hidden_states=audio_hidden_states,
+        encoder_hidden_states=encoder_hidden_states,
+        timestep=timestep,
+        timestep_indices=timestep_indices,
+        token_tags=token_tags,
+        position_ids=position_ids,
+        video_indices=video_indices,
+        audio_indices=audio_indices,
+        text_indices=text_indices,
+        attention_kwargs=attention_kwargs,
+        return_dict=return_dict,
+    )
+    # `apply_lora_scale` decorates the real forward and this one is not it, so a request that actually scales a LoRA
+    # goes down the original path rather than silently losing its scale.
+    if state.failed or (attention_kwargs or {}).get("scale") is not None:
+        return state.original(**original)
+    try:
+        return _cached_forward(
+            self,
+            state,
+            hidden_states,
+            audio_hidden_states,
+            encoder_hidden_states,
+            timestep,
+            timestep_indices,
+            token_tags,
+            position_ids,
+            video_indices,
+            audio_indices,
+            text_indices,
+            return_dict,
+        )
+    except Exception as error:
+        state.failed = True
+        print(f"[h3-fbc] disabled for this request ({type(error).__name__}: {error}); running uncached", flush=True)
+        return state.original(**original)
+
+
+def install(transformer, steps: int = 0, threshold: float = THRESHOLD, audio_exempt: bool = AUDIO_EXEMPT) -> bool:
+    """Bind the caching forward onto `transformer`. Returns whether it went on.
+
+    `accelerate`'s `add_hook_to_module` — what `ComponentsManager.enable_auto_cpu_offload` installs — moves the real
+    forward to `_old_forward` and puts its own onload wrapper in `forward`. Replacing `forward` there would step over
+    the wrapper and run the block stack against weights still on the host, so the replacement goes into `_old_forward`
+    whenever the hook is present.
+    """
+    import inspect
+
+    if getattr(transformer, "_h3_fbc", None) is not None:
+        return True
+
+    hooked = hasattr(transformer, "_hf_hook") and hasattr(transformer, "_old_forward")
+    current = transformer._old_forward if hooked else transformer.forward
+    missing = [name for name in FORWARD_PARAMETERS if name not in inspect.signature(current).parameters]
+    if missing:
+        print(f"[h3-fbc] this transformer's forward has no {missing}; running uncached", flush=True)
+        return False
+    if not hasattr(transformer, "transformer_blocks") or len(transformer.transformer_blocks) < 2:
+        print("[h3-fbc] no block stack to skip; running uncached", flush=True)
+        return False
+
+    state = _State(threshold, steps, audio_exempt)
+    state.original = current
+    transformer._h3_fbc = state
+    bound = types.MethodType(_forward, transformer)
+    if hooked:
+        transformer._old_forward = bound
+    else:
+        transformer.forward = bound
+    return True
+
+
+def uninstall(transformer) -> None:
+    state = getattr(transformer, "_h3_fbc", None)
+    if state is None:
+        return
+    if hasattr(transformer, "_hf_hook") and hasattr(transformer, "_old_forward"):
+        transformer._old_forward = state.original
+    else:
+        transformer.__dict__.pop("forward", None)
+    del transformer._h3_fbc
+    total = state.computed + state.skipped
+    if total:
+        print(
+            f"[h3-fbc] {state.skipped}/{total} forwards served from cache "
+            f"(threshold {state.threshold}, audio exemption {'on' if state.audio_exempt else 'off'})",
+            flush=True,
+        )
+
+
+@contextlib.contextmanager
+def enabled(transformer, steps: int = 0):
+    """Cache the trunk for the duration of one request. The state is per-request by construction — a residual only ever
+    means something within the schedule it was measured on — and nothing in here can raise into the request."""
+    installed = False
+    if ENABLED:
+        try:
+            installed = install(transformer, steps=steps)
+        except Exception as error:
+            print(f"[h3-fbc] install failed ({type(error).__name__}: {error}); running uncached", flush=True)
+    try:
+        yield installed
+    finally:
+        if installed:
+            try:
+                uninstall(transformer)
+            except Exception as error:
+                print(f"[h3-fbc] uninstall failed ({type(error).__name__}: {error})", flush=True)

h3_split_blocks.py

@@ -0,0 +1,147 @@
+"""The halves of a **split** MiniMax-H3 deployment, for both of its checkpoint partitions.
+
+MiniMax-H3 is 195.9 GiB in bfloat16 and a ZeroGPU Space is evicted at 150 GB of storage, so `MiniMaxH3Blocks` is cut
+at its `text_encoder` step: the 62.14 GiB Qwen3-VL runs in the conditioner Space, everything else in a generator
+Space, and `prompt_embeds` + `text_token_tags` is the whole wire format between them.
+
+`resize` / `setup` run on **both** sides: they own no pretrained component, and each half needs the canvas and the
+prepared keyframes or normalized references. Both conditioner halves also return the resolved `height` / `width` /
+`num_frames`, which the generating half pins rather than re-deriving.
+
+Two things the blocks leave to the caller: a keyframe reaches them EXIF-transposed and in RGB, and the `t2va` / `fl2va`
+frame count is aligned to `17 * n + 5` before the call, since that arithmetic lives on the denoising side of the cut.
+"""
+
+from diffusers.modular_pipelines.minimax_h3.before_encoder import MiniMaxH3Ref2VASetupStep
+from diffusers.modular_pipelines.minimax_h3.decoders import MiniMaxH3AfterDenoiseStep
+from diffusers.modular_pipelines.minimax_h3.encoders import (
+    MiniMaxH3Ref2VAReferenceEncoderStep,
+    MiniMaxH3Ref2VATextEncoderStep,
+    MiniMaxH3TextEncoderStep,
+)
+from diffusers.modular_pipelines.minimax_h3.modular_blocks_minimax_h3 import (
+    MiniMaxH3AutoKeyframeVaeEncoderStep,
+    MiniMaxH3AutoResizeStep,
+    MiniMaxH3CoreDenoiseStep,
+    MiniMaxH3DecodeStep,
+    MiniMaxH3Ref2VACoreDenoiseStep,
+    _generation_outputs,
+)
+from diffusers.modular_pipelines.modular_pipeline import SequentialPipelineBlocks
+from diffusers.modular_pipelines.modular_pipeline_utils import OutputParam
+
+
+def _wire_outputs(num_frames: bool = True) -> list[OutputParam]:
+    """The wire format of the split. `num_frames` is declared by the `ref2va` half alone, whose setup resolves one."""
+    return [
+        OutputParam.template("prompt_embeds"),
+        OutputParam("text_token_tags", description="The per-row modality tag of every row of `prompt_embeds`."),
+        OutputParam("height", type_hint=int, description="Resolved height of the generated video in pixels."),
+        OutputParam("width", type_hint=int, description="Resolved width of the generated video in pixels."),
+        *(
+            [OutputParam("num_frames", type_hint=int, description="Resolved number of frames, of the form 17 * n + 5.")]
+            if num_frames
+            else []
+        ),
+    ]
+
+
+class MiniMaxH3ConditionerBlocks(SequentialPipelineBlocks):
+    """The conditioner half of a split MiniMax-H3: the keyframes on the canvas plus the Qwen3-VL read at layer 50."""
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3AutoResizeStep, MiniMaxH3TextEncoderStep]
+    block_names = ["resize", "text_encoder"]
+
+    @property
+    def description(self):
+        return (
+            "The conditioner half of a split MiniMax-H3 deployment: puts the keyframes onto the target canvas and "
+            "encodes MiniMax-H3's presentation of the request into the `prompt_embeds` / `text_token_tags` pair the "
+            "denoising half consumes. The frame count is the caller's to align."
+        )
+
+    @property
+    def outputs(self):
+        return _wire_outputs(num_frames=False)
+
+
+class MiniMaxH3GeneratorBlocks(SequentialPipelineBlocks):
+    """The denoising half of a split MiniMax-H3: `MiniMaxH3Blocks` with its `text_encoder` step removed."""
+
+    model_name = "minimax-h3"
+    block_classes = [
+        MiniMaxH3AutoResizeStep,
+        MiniMaxH3AutoKeyframeVaeEncoderStep,
+        MiniMaxH3CoreDenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
+        MiniMaxH3DecodeStep,
+    ]
+    block_names = ["resize", "vae_encoder", "denoise", "after_denoise", "decode"]
+
+    @property
+    def description(self):
+        return (
+            "The denoising half of a split MiniMax-H3 deployment: the `t2va` / `fl2va` branch of `MiniMaxH3Blocks` "
+            "without its text-encoder step, so `prompt_embeds` and `text_token_tags` come in as inputs and the "
+            "62.14 GiB Qwen3-VL conditioner is never loaded here."
+        )
+
+    @property
+    def outputs(self):
+        return _generation_outputs()
+
+
+class MiniMaxH3Ref2VAConditionerBlocks(SequentialPipelineBlocks):
+    """The conditioner half of a split `ref2va`: the resolved plan plus the Qwen3-VL read at its 50th layer.
+
+    Component for component this is `MiniMaxH3ConditionerBlocks`, so one conditioner Space serves both partitions.
+    What differs is the presentation: `ref2va` prepends a label per reference and a vision block per image and per
+    merged video frame pair, so the references themselves have to reach this half.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [MiniMaxH3Ref2VASetupStep, MiniMaxH3Ref2VATextEncoderStep]
+    block_names = ["setup", "text_encoder"]
+
+    @property
+    def description(self):
+        return (
+            "The conditioner half of a split MiniMax-H3 `ref2va` deployment: resolves the request plan (canvas, frame "
+            "count, references normalized onto MiniMax-H3's own rates and resolutions) and encodes MiniMax-H3's "
+            "presentation of it into the `prompt_embeds` / `text_token_tags` pair the denoising half consumes."
+        )
+
+    @property
+    def outputs(self):
+        return _wire_outputs()
+
+
+class MiniMaxH3Ref2VAGeneratorBlocks(SequentialPipelineBlocks):
+    """The denoising half of a split `ref2va`: the `ref2va` branch with its `text_encoder` step removed.
+
+    `reference_encoder` stays here, next to the two autoencoders it runs: its output shapes are where every reference
+    block's geometry in the packed layout comes from.
+    """
+
+    model_name = "minimax-h3"
+    block_classes = [
+        MiniMaxH3Ref2VASetupStep,
+        MiniMaxH3Ref2VAReferenceEncoderStep,
+        MiniMaxH3Ref2VACoreDenoiseStep,
+        MiniMaxH3AfterDenoiseStep,
+        MiniMaxH3DecodeStep,
+    ]
+    block_names = ["setup", "reference_encoder", "denoise", "after_denoise", "decode"]
+
+    @property
+    def description(self):
+        return (
+            "The denoising half of a split MiniMax-H3 `ref2va` deployment: the `ref2va` branch of `MiniMaxH3Blocks` "
+            "without its text-encoder step, so `prompt_embeds` and `text_token_tags` come in as inputs and the "
+            "62.14 GiB Qwen3-VL conditioner is never loaded here. The transformer is the `transformer_ref` partition."
+        )
+
+    @property
+    def outputs(self):
+        return _generation_outputs()

ncii_guard.py

@@ -0,0 +1,90 @@
+"""The NCII prompt guard, in its own process.
+
+[`hfmlsoc/ncii-light-guard-v01`](https://huggingface.co/hfmlsoc/ncii-light-guard-v01) is a 270M CPU text
+classifier scoring the NCII risk of an edit prompt. It cannot live in the main process: with it loaded there,
+every subsequent `@spaces.GPU` worker dies at `worker_init` with `RuntimeError: No CUDA GPUs are available` —
+the fork inherits whatever CUDA driver state the classifier's torch activity left behind, and a factory reboot
+does not clear it. It cannot be a `multiprocessing.spawn` child either: spawn re-imports the parent's main
+module, and on a Space that main module is `app.py` — the child would re-run the whole startup, `start()`
+included. So the classifier runs this file as a plain subprocess — a fresh interpreter that never sees `spaces`
+— and answers over stdin/stdout, one JSON object per line.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import select
+import subprocess
+import sys
+import threading
+
+GUARD_REPO = "hfmlsoc/ncii-light-guard-v01"
+
+_lock = threading.Lock()
+_process: subprocess.Popen | None = None
+
+
+def _read(timeout: float) -> dict:
+    readable, _, _ = select.select([_process.stdout], [], [], timeout)
+    if not readable:
+        raise TimeoutError(f"the guard did not answer within {timeout}s")
+    line = _process.stdout.readline()
+    if not line:
+        raise EOFError("the guard process died")
+    return json.loads(line)
+
+
+def _spawn() -> None:
+    global _process
+    _process = subprocess.Popen(
+        [sys.executable, os.path.abspath(__file__)],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+    # Generous: a cold cache downloads the checkpoint first.
+    assert _read(300.0) == {"status": "ready"}
+
+
+def start() -> None:
+    """Launch the worker and block until its model is up. Called once at startup; `classify` revives it if it dies."""
+    with _lock:
+        _spawn()
+
+
+def classify(prompt: str, timeout: float = 60.0) -> dict:
+    """`{'label': 'safe' | 'ncii', 'score': ...}` for one prompt, replacing a dead or wedged worker once."""
+    with _lock:
+        for attempt in (0, 1):
+            try:
+                if _process is None or _process.poll() is not None:
+                    _spawn()
+                _process.stdin.write(json.dumps({"prompt": prompt}) + "\n")
+                _process.stdin.flush()
+                return _read(timeout)
+            except Exception:
+                if attempt:
+                    raise
+                if _process is not None and _process.poll() is None:
+                    _process.kill()
+
+
+def _serve() -> None:
+    """The child: plain torch on CPU. The protocol keeps the real stdout to itself — everything else
+    (download progress, warnings) is pushed over to stderr so it cannot corrupt a reply."""
+    protocol = os.fdopen(os.dup(1), "w", buffering=1)
+    os.dup2(2, 1)
+
+    from transformers import pipeline
+
+    classifier = pipeline("text-classification", model=GUARD_REPO, device="cpu")
+    protocol.write(json.dumps({"status": "ready"}) + "\n")
+    for line in sys.stdin:
+        result = classifier(json.loads(line)["prompt"], truncation=True)[0]
+        protocol.write(json.dumps({"label": result["label"], "score": float(result["score"])}) + "\n")
+
+
+if __name__ == "__main__":
+    _serve()

packages.txt

@@ -0,0 +1 @@
+ffmpeg

requirements.txt

@@ -0,0 +1,33 @@
+# `diffusers` is installed from the canonical MiniMax-H3 pull request,
+# https://github.com/huggingface/diffusers/pull/14371 ("Minimax h3 follow up (review & refactor)"), pinned to a
+# **commit** rather than to its `minimax-h3-refactor` branch: the PR is a WIP and its head moves, and this Space's
+# `h3_split_blocks.py` subclasses its block classes. Re-pin — and re-check `h3_split_blocks.py` against the block
+# names of the new head — whenever the PR updates. (diffusers `main` has already renamed several of them.) It is
+# also the commit `multimodalart/qwen3vl-conditioner` serves, and the two halves have to agree on the wire format.
+#
+#   665f578278365ea4a3318cb8c9b66ce6c01204b9 = refs/pull/14371/head at the time of this deploy
+--extra-index-url https://download.pytorch.org/whl/cu130
+diffusers @ git+https://github.com/huggingface/diffusers.git@665f578278365ea4a3318cb8c9b66ce6c01204b9
+torch==2.11.0
+torchvision==0.26.0
+# A scene clip's soundtrack that is not already at the audio VAE's 32 kHz is resampled with `torchaudio`. Real
+# camera and phone footage is 44.1/48 kHz, so this is hit by most uploads that are not silent.
+torchaudio==2.11.0
+# The Qwen3-VL processor decides the vision patch count, so a different minor changes the conditioning.
+transformers==5.8.0
+accelerate==1.14.0
+# diffusers pins <2.
+huggingface-hub==1.24.0
+# The character-swap LoRA is attached as a runtime PEFT adapter (`load_lora_adapter` + `set_adapters`), not folded
+# into the base weights, so its strength stays a per-request slider. Without `peft`, `load_lora_adapter` raises
+# ModuleNotFoundError at startup and the Space would quietly serve the base `ref2va` model.
+peft
+# `gradio` and `spaces` are deliberately absent: the Space runtime installs both itself (gradio from `sdk_version`
+# in README.md, `spaces` at whichever version it currently ships), so pinning either here is a resolver conflict
+# rather than a version choice.
+# PyAV decodes the scene clip and muxes the generated soundtrack onto the frames (`encode_video`).
+av
+pillow
+numpy
+requests
+safetensors>=0.8.0