Add FastH3 Preview v1 Dense-DataFree MLX to Apple Silicon video gen

[atomanticagent]

Context

FastVideo shipped packed MLX DiT checkpoints for FastH3 Preview v1 Dense / Data-Free on 2026-09-01. These skip scripts/checkpoint_conversion/convert_minimax_h3_mlx.py. Hugging Face cards say they "avoid the local conversion step."

This is not the VSA-DataFree CUDA checkpoint tracked in #5351. That watch stays CUDA/VSA. This issue is the Dense MLX packed path that now runs on Apple Silicon.

Default for a 128 GB MacBook Pro: INT6 (~15.41 GiB DiT). INT8 and INT4 are optional. Upstream validated on an M4 Max with 36 GB; 128 GB has headroom.

Caveats to keep explicit in catalog copy and disclosures:

• Dense / Data-Free Preview v1 only. No --vsa.
• The Apple Silicon install guide still documents the old convert path. HF cards are the no-convert recipe.
• Two downloads: shared H3 components (tokenizer, Qwen3-VL, VAEs) plus the MLX DiT pack.

Decision

Extend the existing fastvideo BYOV runtime (do not add a new runtime, and do not reuse minimax_h3 / PipeNetwork or minimax_h3_cuda). Add FastH3 Dense-DataFree MLX as catalog entries in the MLX video bucket, same shape as FastMetal in migration 314.

Recommended default row: INT6. Also ship INT8 and INT4. Text-to-video-with-audio (T2VA). Opt-in --fast / --fast-spatial later if the UI already has a speed/quality toggle; do not block first ship on that.

Install stays user-triggered (INSTALL_FASTVIDEO). No cold-bootstrap downloads. Cache-only once weights are on disk.

Weights

• Components: FastVideo/FastVideo-FastH3-4-step-Preview-v1-Dense-DataFree (pin revision f624f08c6c279ab43534c003e556fc5b295b6558 unless a newer card says otherwise)
• INT6 DiT (default): FastVideo/FastVideo-FastH3-4-step-Preview-v1-Dense-DataFree-MLX-INT6
• INT8: FastVideo/FastVideo-FastH3-4-step-Preview-v1-Dense-DataFree-MLX-INT8
• INT4: FastVideo/FastVideo-FastH3-4-step-Preview-v1-Dense-DataFree-MLX-INT4

Upstream run (INT6):

python examples/inference/basic/mlx_fasth3.py \
  --model-root ./FastH3-Preview-v1-Dense-DataFree \
  --mlx-checkpoint ./FastH3-MLX-INT6 \
  --prompt '(S1) A presenter says <d>[English] Fast H3 runs on Apple silicon.</d>' \
  --height 480 --width 832 --num-frames 124 --steps 4 --seed 2026 \
  --output-path ./outputs/fasth3_int6.mp4

Implementation seams

Follow the FastMetal pattern (scripts/migrations/314-fastvideo-mlx-models.js, runtime: 'fastvideo'):

• scripts/generate_fastvideo.py — teach it FastH3: call mlx_fasth3.py with --model-root + --mlx-checkpoint (two local dirs), 4-step schedule, 480×832 / 124 frames defaults. Keep FastMetal on mlx_wan_prompt_to_video.py / mlx_wan22_generate.py.
• server/services/videoGen/renderArgs.js — argv for the new model ids.
• server/services/videoGen/runtimes.js — keep using fastvideo; FastH3 is another model on that runtime, not a new BYOV id.
• data.reference/media-models.json + a new migration (next id after the current last) seeding MLX-bucket rows (fasth3_dense_datafree_mlx_int6 etc.).
• server/lib/mediaModels.js, server/lib/videoDisclosure.js, server/lib/huggingfaceModel.js — license, T2VA disclosure, HF auto-detect for the two-repo layout.
• scripts/setup-image-video.sh — only if the FastVideo install block needs another extra; otherwise leave install as-is.

Do not invoke convert_minimax_h3_mlx.py in PortOS. Do not add these rows to the CUDA bucket. Do not claim VSA or FL2VA/Ref2VA.

Acceptance

• Video Gen on Apple Silicon lists FastH3 Dense-DataFree MLX (INT6 default; INT8/INT4 available).
• Install/download is explicit; first render does not convert DiT locally.
• A 4-step T2VA render writes a muxed mp4 via the existing FastVideo venv.
• FastMetal rows and MiniMax H3 runtimes are unchanged.
• Catalog copy states Dense-only / no VSA, MiniMax H3 Community License, and the two-download layout.
• Tests: migration idempotency + argv builder for the new ids (same style as 314).

References

• Track Apple Silicon support for FastH3 VSA preview #5351 (VSA CUDA watch — different checkpoint; do not reopen for this)
• FastVideo repo: https://github.com/hao-ai-lab/FastVideo
• MPS guide (partly stale on convert): https://haoailab.com/FastVideo/getting_started/installation/mps/

[atomantic]

Working this now. Two upstream facts changed the plan, so recording the calls made rather than parking the issue.

1. The three FastVideo/*-MLX-INT{6,8,4} repos ship no weights. Each holds five small files (README.md, LICENSE, .gitattributes, conversion_manifest.json, mlx_h3_dit.json); mlx_h3_dit.safetensors returns HTTP 404 on resolve/main for all three, and the tree listing agrees (5 siblings, usedStorage: 0). The repos were created 2026-09-01 and the LFS blob was never pushed. Shipping catalog rows against them would put three guaranteed-404 download buttons in Video Gen, so they are not shipped in this PR.

2. One complete Dense/Data-Free MLX checkpoint does exist: MrMofer/FastVideo-FastH3-4-step-Preview-v1-Dense-DataFree-MLX-INT4 (rev 4c8c3e54da8cd667b5db10f6074b4cb9b7559f15, 89.27 GB). Its conversion_manifest.json names the same source (FastVideo/...-Dense-DataFree @ f624f08c), the same converter commit cf6a00b9, MLX 0.32.2, 1464 tensors, vsa_capable: false. Unlike the FastVideo packs it is self-contained — it carries vae/, audio_vae/, text_encoder/, tokenizer/, processor/, scheduler/ alongside mlx_h3_dit.safetensors (11.53 GB), so --model-root and --mlx-checkpoint are the same snapshot and there is no two-download layout to build. MrMofer is already a shipped repacker in this catalog (ltx25_mlx_q8, and the ltx25 runtime is their fork).

Decisions

• Ship one row now: fasth3_dense_datafree_mlx_int4 on the existing fastvideo runtime, MLX bucket, T2VA, 4-step, 832x480, 124 frames.
• Because the snapshot is self-contained, the mlxCheckpoint/second-repo seam described in the issue is not built — it would be an abstraction with no caller. It goes in with the INT6/INT8 rows if and when the FastVideo packs get their weights.
• INT6 cannot be the default row because INT6 does not exist as a downloadable artifact. A follow-up watch issue tracks INT6/INT8 (and the official INT4) for when upstream pushes the blobs.
• The pinned FastVideo checkout PortOS installs (a159b63c) has examples/inference/basic/mlx_fasth3.py, and its --help accepts exactly --model-root --mlx-checkpoint --prompt --output-path --height --width --num-frames --seed --steps. No --fps, --guidance, --negative-prompt or --image-path; output is fixed at 24 fps H.264 + 32 kHz stereo AAC. The helper is taught that argv shape rather than reusing the FastMetal one.

No test render on this machine. It has 48 GB of free disk against an 89.27 GB snapshot, and 48 GB of unified memory against a 66.73 GB bf16 Qwen3-VL text encoder. Verification in this PR is the argv-builder and migration tests plus a --help check of the real pinned entry script; the render itself is unverified and the PR says so.