MiniMax-H3 Downscaled Latent Guide (BFS)

This node is not for everyone - and that's the useful thing to know

If you're doing ordinary H3 video work, close the tab. This is a compatibility node for H3 upscale LoRAs trained with the target_crop_v2 / target_grid_stride_v1 geometry in the author's own ai-toolkit fork. No LoRA trained that way, no reason to be here.

What it fixes is a specific mismatch. H3's native Add Guide node enlarges your guide up to the output canvas - reasonable for normal guides, wrong for these LoRAs, which were trained with a guide that stays small and whose coordinates come from the target's patch grid at a fixed stride. So this node encodes your guide at the lower resolution, then patches the returned model so the packed spatial coordinates line up with what the LoRA saw during training. Practically: an upscaling pass where you show the model a 256×192 version of the frame and get a 1024×768 one out, with the guide genuinely informing the detail instead of being upscaled into mush first.

Worth placing in context: video upscaling is the least settled job in the whole upscaling field, because an upscaler that is excellent frame by frame can still make fine texture jitter, unable to agree with itself from one frame to the next. Showing the model a coherent low-resolution guide and letting it regenerate at higher resolution - which is what these LoRAs do - sidesteps that entirely. It's a different bet from bolting a per-frame upscaler onto your decode.

Wiring it matters more than the settings

The contract is: connect both the model and positive outputs to your guider/sampler, and use the returned model for sigma scheduling too. The latent you sample is the target latent - the one from MiniMax-H3 Guide Target - not a guide latent. Get either of those wrong and you'll get a plausible-looking render that isn't doing what you think.

The example image workflow is: H3 Ref2V model + your upscale LoRA through a normal LoRA loader, a caption encoded without ever passing the guide image into the VLM (this part matters - the training prompt is just text: h3upscale, increase resolution and restore fine details while preserving the original content and visual style.), a Guide Target of 1024×768 at 1 frame, then this node with downscale_factor = 4, frame_idx = 0, and the guide image from your source.

The inputs worth reading the tooltip on

Required, and all of them count: model (after your LoRA loader), positive, vae, latent (the target), image (a single image, or video frames already resampled to 24 fps - the node does not touch your frame rate), downscale_factor (1–8, default 4), frame_idx.

lora_name exists purely to validate metadata - pick the same checkpoint so the node can check its training geometry against what you asked for. It does not load the LoRA. That's the single most misread control in the pack; load your LoRA the normal way.

Then a set of optional geometric experiments from the 1.47.0 wave of "reference layouts": guide_rope_layout (overlap/sidecar), reference_rope_layout (native/overlap/sidecar), reference_source_phase, reference_phase_scale, reference_sidecar_margin, source_id (default 1, and it must match your LoRA's training control channel). The defaults preserve the plain behaviour. Legacy checkpoints effectively imply overlap/native/phase-off, so changing only the inference geometry on a LoRA trained without those tricks does not make it able to use them.

There's also audio + audio_vae for an aligned guide soundtrack; it's cropped to the clip and never routed to the text encoder.

Outputs are model, positive and guide_preview - that last one is the actual reduced pixels that got encoded, and you should look at it. It's the only way to see that your source was silently fitted and Lanczos-downscaled rather than used as-is.

Geometry you can check on paper

Each target pixel axis must be a multiple of 32 × downscale_factor, which is where most ValueErrors come from. At 1024×768 with factor 4: guide pixels 256×192, guide latents 16×12, target latents 64×48. A single image is one guide latent-time slice; 73 frames is 22 slices, and time uses H3's (1,4,4,4,4) pattern rather than a uniform stride. 17n+5 frame counts only (5, 22, 39, 56, 73, 90, 107, 124). The node rejects invalid lengths rather than stretching your motion to fit.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/alisson-anjos/ComfyUI-BFSNodes
cd ComfyUI-BFSNodes && pip install -r requirements.txt

You need a ComfyUI build with native H3 support and a matching VAE/layout API; the pack raises explicit errors when the H3 internals it patches don't match, which is much better than the alternative. Also: the author is refreshingly blunt here - preprocessing and coordinates are covered by CPU parity tests, but a full pretrained GPU sampling run wasn't part of that change, and matching geometry doesn't prove your LoRA is any good. Compare LoRA strength 0 against 1 on held-out inputs before you judge the upscale.