Document the combined workflow shipped in this repo

README.md

@@ -84,25 +84,42 @@ video, audio, rate = out["videos"][0], out["audio"][0], out["sampling_rate"]
 
 ### Keyframes and references in the same generation
 
-The model itself supports it — MiniMax-H3 denoises one packed sequence, and keyframe conditioning rows and reference
-conditioning rows can both sit in it. ComfyUI exposes this natively: chain its `MiniMaxH3ReferenceToVideo` into
-`MiniMaxH3AddGuide` and one sampler run carries both.
-
-`diffusers` does **not** expose it. Its auto-blocks dispatch either/or — `select_block` checks `references` first and
-returns the `ref2va` branch — so a request carrying both is accepted and the **keyframes are silently dropped**. There
-is no error and no warning; you get a reference-only generation.
-
-Combining them therefore needs one extra piece on top of `diffusers`: a layout step that packs
-`[text | keyframe conditions | reference blocks | targets]` into one sequence, with the keyframe anchors shifted by
-the references' total time span (the references push the target timeline out). Porting
-[ComfyUI's `PackedLayout`](https://github.com/comfyanonymous/ComfyUI/blob/master/comfy/ldm/minimax/model.py) is the
-straightforward way to get it, and the denoising loop needs no change at all, since the conditioning rows are simply
-the leading rows of the sequence.
-
-Measured on this checkpoint with such a layout in place: a combined request (first frame + last frame + an image
-reference) agrees with the real `ref2va` partition at video-latent cosine **0.972** — closer than any reference-only
-request reaches, because keyframes anchoring both ends leave the delta less to carry. Adding an audio reference on top
-moves the video only 0.965 while rewriting the soundtrack to 0.403, i.e. each conditioning does its own job.
+`workflow="combined"` — this repo ships the blocks for it:
+
+```python
+pipe = ModularPipeline.from_pretrained(REPO, workflow="combined", trust_remote_code=True)
+pipe.load_components(dtype=torch.bfloat16, trust_remote_code=True)
+
+out = pipe(
+    prompt="She lifts the teacup and takes a slow sip, then smiles; warm kitchen light",
+    references=[MiniMaxH3ImageReference.from_file("subject.png")],   # who / what
+    image=Image.open("first.png"), last_image=Image.open("last.png"),  # where it starts and ends
+    height=544, width=960, num_frames=124, num_inference_steps=20,
+    generator=torch.Generator("cpu").manual_seed(42),
+)
+```
+
+MiniMax-H3 denoises **one packed sequence**, and that sequence can hold keyframe conditioning rows and reference
+conditioning rows at the same time. `diffusers`' shipped blocks cannot express it: their conditional steps dispatch
+either/or — `select_block` checks `references` first — so a request carrying both is accepted and the **keyframes are
+silently dropped**, with no error and no warning.
+
+`MiniMaxH3CombinedBlocks` (in `combined_blocks.py`) is the stock blockset with three of its conditional steps replaced
+by ones that know a fourth shape. It reserves `[text | keyframe conditions | reference blocks | target audio | target
+video]`, and because the references push the target timeline out, the keyframe anchors ride on the timeline their
+spans leave behind. The `t2va`, `fl2va` and `ref2va` workflows are untouched and take exactly the same path as before;
+the denoising loop needed no change at all, since the conditioning rows are simply the leading rows of the sequence.
+
+Two things keep it honest: the layout reproduces **both** shipped `diffusers` builders bit for bit in their degenerate
+cases — no keyframes gives the `ref2va` layout, no references gives the `fl2va` one, `position_ids` compared in
+float64 — and the stock prepare-latents step asserts that the conditioning rows encoded equal the rows the layout
+reserved, so a wrong layout raises instead of quietly degrading.
+
+Measured on this checkpoint — with this layout, driven through the same underlying steps, before it was packaged as
+the blockset above: a combined request (first frame + last frame + an image reference) agrees with the real
+`ref2va` partition at video-latent cosine **0.972**, closer than any reference-only request reaches, because keyframes
+anchoring both ends leave the delta less to carry. Adding an audio reference on top moves the video only 0.965 while
+rewriting the soundtrack to 0.403 — each conditioning doing its own job.
 
 ### Few-step generation — keep the turbo LoRA live
 
@@ -167,4 +184,5 @@ approach established by [Kijai](https://huggingface.co/Kijai/MiniMax-H3-experime
 [MiniMaxAI](https://huggingface.co/MiniMaxAI/MiniMax-H3). Related community work on the same question:
 [lihaoyun6](https://huggingface.co/lihaoyun6/MiniMax-H3-Ref-Patch) (exact-diff-only patch),
 [smhfacct](https://huggingface.co/smhfacct/Minimax-H3-fl2va-ref2va-hybrid-models) (AdaLN block swap),
-[PulpCut](https://huggingface.co/PulpCut/MiniMax-H3-Ref2VA-Turbo-INT8-ConvRot) (turbo merged into Ref2VA).
+[PulpCut](https://huggingface.co/PulpCut/MiniMax-H3-Ref2VA-Turbo-INT8-ConvRot) (turbo merged into Ref2VA). The
+packed-sequence order a combined request uses follows ComfyUI's implementation of this model.