MiniMax H3 Preview Override

# MiniMax H3 Preview Override

Live, kjnodes-style sampling previews for MiniMax H3 in ComfyUI — with true RGB colors.

MiniMax H3 is an omni-modal model (video / audio / text / image). Like most video

models it has no tiny autoencoder bundled, so ComfyUI's built-in sampler preview

can only show a rough Latent2RGB projection — which, for a 24-channel video latent,

looks like colored noise.

This single node attaches an OUTER_SAMPLE wrapper to the H3 model and, **on every

sampling step**, decodes the current x0 video latent into real RGB frames and

streams them into a DOM widget right on the node — with sigma / delta graphs,

per-step timing and a click-to-scrub history.

It ships with a trained Tiny AutoEncoder decoder taeh3_decoder.safetensors,

24-channel, ~9.9M params) that distills the big H3 video VAE's decoder — the H3

equivalent of taeltx for LTX or taesd for SD.

---

## Features

- 🔴 True-RGB per-step previews — real decoded frames, not Latent2RGB noise

- ▶️ Animated previews — sample multiple frames per step, play back as

animated WebP (or H.264 MP4 when NVENC is available)

- 📊 σ / Δ graph — hover to scrub steps, click to lock and inspect any step

- ⏱️ Step timing — per-step ms and rolling average + ETA in the widget header

- 🪶 Cheap — the TAE is ~40 MB and decodes in milliseconds; negligible VRAM

- 🛡️ VRAM-safe — only tiny autoencoders (TAEHV/TAESD) are ever used per step;

a full video VAE is ignored (it would OOM during sampling)

- 🖼️ Full resolution — previews stream at sampler resolution (capped by

max_resolution), unlike the default 512 px first-frame preview

- 🧹 Clean logs — the expected "missing encoder keys" warning for decoder-only

TAE files is suppressed

## Requirements

- ComfyUI (current 2025+ version with the new frontend and comfy_api.latest)

- The [MiniMax H3 model pack] (https://www.minimax.io/blog/minimax-h3) — the

MiniMaxH3ReferenceToVideo, MiniMaxH3SigmaShift, sampler and VAE nodes

- ~24 GB+ VRAM for H3 video generation (the model itself is ~20 GB)

- Python av/PyAV is optional (only needed for NVENC MP4 previews; WebP works

out of the box)

## Installation

[code]

cd ComfyUI/custom_nodes

git clone https://github.com/simsim9-stack/ComfyUI-MiniMaxH3-PreviewOverride.git

[/code]

Or download the ZIP from GitHub and extract it into ComfyUI/custom_nodes/.

Then:

1. Restart ComfyUI (the node registers on startup).

2. Hard-refresh the browser tab (Ctrl+F5) so the widget JS is loaded.

### Install the mini VAE (required for real previews)

Copy the trained decoder into your vae_approx folder:

```bash

# from this repo:

cp minivae/taeh3_decoder.safetensors ComfyUI/models/vae_approx/

```

Without this file the node falls back to Latent2RGB (the "colored noise" previews).

## Usage

1. Add *MiniMax H3 Preview Override** to your graph.

2. Wire the H3 model into it (e.g. after MiniMax H3 Sigma Shift).

3. Wire its MODEL output into your sampler's chain (guider + scheduler).

4. In the vae_name combo select taeh3_decoder.safetensors.

5. Queue. The widget on the node shows the video forming, step by step.

### Node inputs

| Input | Type | Default | Description |

|---|---|---|---|

| model | MODEL | — | MiniMax H3 model to attach the preview wrapper to |

| tiny_vae | VAE (optional) | — | TAE wired externally; leave empty to use vae_name |

| max_resolution | INT | 1024 | Max preview side in px; 0 = full sampler resolution |

| jpeg_quality | INT | 80 | JPEG/WebP quality of the streamed previews |

| suppress_default_preview | BOOL | true | Hide the default sampler preview overlay while sampling |

| preview_frames | INT | 8 | Frames sampled per step; 1 = single frame (fastest) |

| preview_fps | INT | 12 | Playback FPS for animated previews |

| vae_name | COMBO | taeh3_decoder.safetensors | TAE file from models/vae_approx |

Output: MODEL — the model with the preview wrapper attached.

### Widget

- Header: resolution · step/total · avg step time · ETA

- σ / Δ graph: sigma schedule with the per-step Δ (change in the latent) —

hover to scrub through captured steps, click to lock a frame

- step time graph: rolling per-step timing

## Example workflows

The examples/ folder has the three base MiniMax H3 modes, each with the

Preview Override node already wired between the model and the sampler:

| File | Mode | What's different |

|---|---|---|

| minimax_h3_t2v_preview_override.json | T2V — text to video | no reference inputs |

| minimax_h3_i2v_preview_override.json | I2V — image to video | one LoadImage → first-frame reference |

| minimax_h3_r2v_preview_override.json | R2V — reference to video | two LoadImage → character/scene references |

Common chain (all three):

```

UNETLoader → Sigma Shift → [MiniMax H3 Preview Override] → BasicGuider ─┐

CLIPLoader ─┐ ├─→ SamplerCustomAdvanced → VAEDecode → CreateVideo → SaveVideo

VAELoader ──┴→ MiniMaxH3ReferenceToVideo → conditioning + latent ───────┘

```

For R2V, reference videos and audio can be wired into the same node's

ref_videos / ref_video_audios inputs — the prompt then refers to them as

<Video k> / <Audio j>.

Load a file via Workflow → Open, pick your model files in the combo boxes

unet_name, clip_name, vae_name, audio vae), drop your own images into the

LoadImage nodes, and queue.

## How it works

- An OUTER_SAMPLE wrapper replaces the sampler's step callback. On each step the

packed NestedTensor is unpacked to the video stream [B, 24, T, H, W] and decoded:

1. Tiny VAE — vae.decode() of the TAE (true RGB, preferred)

2. Animated Latent2RGB (multi-frame, when no TAE)

3. Single-frame Latent2RGB (fallback)

- The node validates the TAE's latent channels (H3 needs 24). A mismatched TAE

(e.g. an LTX or Wan TAE) is disabled with one clear warning instead of erroring

every step.

- Encoding (JPEG/WebP/MP4) happens on a background thread so the sampler never

blocks; full VRAM VAEs are never used for previews.

## About the mini VAE

taeh3_decoder.safetensors is a decoder-only Tiny AutoEncoder (TAEHV

architecture, 24 latent channels, fp32) trained by the author on pairs of

(raw H3 latents, decoded frames) generated with the official H3 video VAE —

distilled from ~100+ H3 video generations. Holdout PSNR ≈ 25.5 dB.

It loads through comfy.sd.VAE straight into the TAEHV(latent_channels=24)

branch. Because it is decoder-only, ComfyUI logs a Missing VAE keys [...]

warning on load — that is expected and harmless (the node suppresses it).

## Troubleshooting

| Symptom | Cause / fix |

|---|---|

| Preview shows colored noise | TAE not loaded — check vae_name, put taeh3_decoder.safetensors in models/vae_approx/ |

| Missing VAE keys warning in the log | Expected for decoder-only TAE files; harmless |

| "Loaded TAE has N latent channels but the model needs 24" | You picked a TAE for another model (LTX/Wan/SD) |

| No widget / blank node | Restart ComfyUI and hard-refresh the browser (Ctrl+F5) |

| Widget shows only a single frame | preview_frames = 1 — set it to 8+ for animated previews |

| OOM during sampling | Do not wire a full video VAE into tiny_vae; only tiny decoders are safe |

## Credits

Inspired by [KJNodes'](https://github.com/kijai/ComfyUI-KJNodes)

Model Preview Override, adapted for the MiniMax H3 video latent.

MiniMax H3 by [MiniMax](https://www.minimax.io/).