[feat] Add MiniMax H3 MLX spatial fast mode

[SuhaanCoding]

Summary

• Wire spatial fast mode (--fast-spatial) into the MiniMax H3 MLX runtime: denoise and decode on the smallest 32px-aligned canvas covering target / scale (a 480x832 request runs on a 256x416 canvas), center-crop to target / scale, then resample the decoded frames up to the requested size in pixel space.
• Follow the runtime's established split (same shape as temporal --fast from [feat] Add MiniMax H3 MLX T2VA inference #1770): the planner is H3-native — FastSpatialPlan / plan_fast_spatial colocated with FastTemporalPlan, delegating grid rules to _model_canvas_size so no size the full-resolution path accepts is rejected — while execution reuses the shared frame_upsample pixel-space resampler. The upsample never runs on latents.
• Compose with --fast: RIFE runs first at the reduced size (optical flow on fewer pixels), then one unsharp pass at full resolution using the stronger of the two requested amounts — same rationale as the Wan runtime's post pass.
• Audio is untouched: spatial mode changes resolution, not duration.
• CLI flags mirror the Wan entrypoint: --fast-spatial, --fast-spatial-scale, --fast-spatial-upsample-mode, --fast-spatial-sharpen. Docs updated where they claimed spatial fast mode was not wired.

Performance

Not measured yet — developed without local FastH3 weights. Expected shape: 2x scale cuts spatial tokens ~4x (30x52 -> 16x26 latent grid at 480p) with attention-dominated denoise. Pending numbers, plus two quality questions, are why this opens as a draft:

• whether H3 holds composition below its 480p training resolution;
• VSA tile-64 behavior on the smaller grid (prepare_vsa_geometry receives the reduced layout; the reference fallback should cover unsupported shapes).

Validation

• pytest fastvideo/tests/mlx/ — 235 passed, 2 skipped. Includes 8 new CPU contracts in test_mlx_minimax_h3_fast_spatial.py: planner geometry (240 -> 256 canvas round-up at 480p, 384x640 at 720p), non-reducing-scale rejection, kernel/sharpen validation, OpenCV preflight, and crop -> upsample restoring the exact target size.
• pre-commit run --files <changed paths> clean (yapf, ruff, mypy, codespell, pymarkdown).
• Not run: end-to-end generation with real FastH3 weights (480x832 and 720p spot checks, --fast --fast-spatial composition, VSA interaction). Will attach results before marking ready for review.

Note: docs/cookbook/minimax-h3.md and cookbook-recipes.json still say VSA is not wired on MLX — stale since #1776 merged; left untouched here to keep this PR scoped.

[mergify]

Merge Protections

🔴 1 of 1 protections blocking · waiting on 🤖 CI

	Protection	Waiting on
🔴	PR merge requirements	🤖 CI

🔴 PR merge requirements

Waiting for

• check-success=full-suite-passed
• check-success~=pre-commit

This rule is failing.

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

[aryan5v]

Reviewed feeecfd4f applied unchanged onto 8f9d76a80 (merged #1776 + #1788; local integration a1bda8f3c). It applies cleanly and the three real CLI paths complete. Requesting changes for the CI registration and generation-level regression coverage noted inline, not for a demonstrated crash in the implementation.

Local validation

M4 Max, 36 GB unified memory, MLX 0.31.2, Preview-v0.2 dense INT6 checkpoint, seed 2026, four steps, 832x480 output, 124 frames, tiled FP32 VAE. Same cached prompt in every run: (S1) A presenter says <d>[English] Fast H3 is amazing.</d>. VSA off; the merged affine dequant+GEMM path engaged in all three runs.

Flags	Denoise canvas / source frames	DiT forwards	Video decode	RIFE	CLI wall	Denoise MLX peak
--fast-spatial	416x256 / 124	77.57 s	20.07 s	—	104.63 s	16.83 GiB
--fast	832x480 / 73	179.16 s	60.71 s	4.75 s	252.08 s	17.86 GiB
--fast --fast-spatial	416x256 / 73	46.22 s	12.96 s	1.39 s	67.63 s	16.68 GiB

Spatial upsampling took 0.33 s / 0.27 s. CLI wall includes process startup and muxing, but not uncached text encoding. These are single samples with different denoising workloads, not quality-preserving kernel speedup measurements. No competing MLX generation was running. System swap changed by approximately +0.48 / +2.43 / -0.15 GiB respectively; this is not a zero-swap benchmark.

All MP4s fully decode: H.264, 832x480, 124 frames at 24 fps (5.167 s), with stereo AAC at 32 kHz. All three generated 165,334 audio samples per channel before muxing; muxed audio is 5.152 s.

Visual inspection of six frames per clip: spatial-only produced a blurry interface-like scene with colored blobs; temporal-only produced a clearer workbench/hands scene; stacked produced a presenter, with visible softness and ghosted edges around the face and moving hands. These are different samples, not a parity pass. This one prompt/seed does not establish a prompt-encoder bug or general quality preservation. Please document the quality trade-off in the spatial CLI/guide and retain the opt-in status.

• 120 targeted H3, VSA, affine dequant+GEMM, and frame-resampling tests passed.
• 12 reviewer-local probes passed: actual generate() orchestration with heavyweight phases mocked, reduced-layout tile-64/256 geometry, and real reference VSA attention on both reduced layouts (one head, not a full DiT).
• Pre-commit passed on all eight changed files; the integration checkout is clean. No PR code was modified or pushed.

The orchestration probes verify the reduced denoise/decode canvas, 73/124 source-frame choices, full-duration audio, RIFE-before-upsample ordering, and one final sharpening pass. Please preserve these contracts in the committed tests.

Not run: no-fast full-resolution baseline, 720p generation, full-model VSA generation with spatial mode, uncached encoder, or listening/transcription-based audio-quality assessment.

[SolitaryThinker]

Re-reviewed 17f3a91e2 after the follow-up. The previous blockers are resolved: the new suite is registered in both MLX CI lanes, and committed generation-level contracts cover spatial-only, temporal-only, stacked RIFE-before-upsample ordering, full-duration audio, one final sharpen pass, and reduced VSA layouts.

Validation: 39 focused MLX CPU tests passed; repository pre-commit passed on all changed paths (including mypy and workflow lint); Buildkite fastcheck passed at this head. The documented opt-in quality trade-off matches the real-weight spot checks. No remaining findings.

[aryan5v]

Local Mac M4 Max check on 17f3a91e2 (INT6, 832×480×124, 4 steps, seed 2026, tiled VAE).

Geometry is as documented: --fast-spatial denoises 416×256×124 (center-crop from the 256-tall canvas), stacked --fast --fast-spatial is 416×256×73 then RIFE. Tests I ran locally (test_mlx_minimax_h3_fast_spatial + fast-mode) passed.

Run	Denoise	VAE	Generate
Native 480p (same machine, earlier INT6 e2e, prompt cached)	351 s	107 s	458 s
--fast-spatial only	79 s (~4.4×)	20 s	~100 s cached / 184 s first run with text encode
--fast + --fast-spatial	50 s (~7.1×)	12 s	65 s

Composition held at the reduced canvas (alpine, one dancer, coral jacket / cobalt pants / cream headphones). Dance is a bit weak — more standing than a two-step — which matches the expected quality trade-off of generating below 480p.

One non-blocking quality issue: random white flashes / halo around the character (headphones, jacket edge, feet). Looks like 2× Lanczos + unsharp ringing (sharpen=0.4, stacked uses max(0.4, 0.6)=0.6), not a mux crash. Worth a follow-up to try fast_spatial_sharpen=0 or a milder stacked sharpen, but I would not block on it.

LGTM