Skip to content

About

Live true-RGB per-step previews for MiniMax H3 in ComfyUI - with a trained 24-channel tiny autoencoder decoder

Resources

Stars

11 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

MiniMax H3 Preview Override

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

ComfyUI

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 — 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

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

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:

# 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' Model Preview Override, adapted for the MiniMax H3 video latent. MiniMax H3 by MiniMax.

License

MIT — see LICENSE. © 2026 InsanE_GeN

About

Live true-RGB per-step previews for MiniMax H3 in ComfyUI - with a trained 24-channel tiny autoencoder decoder

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages