MiniMax H3 Reference to Video — Guide 0 CLIP Context (BFS)

The problem it solves

MiniMax H3 motion transfer gives you two ways to feed it a source clip. You can encode it as aligned guide latents (MiniMax H3 Add Guide) - good motion control, but the text encoder never sees the clip. Or you can pass it as a native video reference, where it enters both the language model and the diffusion reference path, which brings its own numbering and semantics along for the ride.

The first option leaves your Qwen text encoder blind. Try telling it "the blonde performer in the yellow shirt follows <Subject 1>" when nothing in the graph ever showed Qwen that video, and watch it invent a performer. The second option fixes that and then hands you a pile of reference-latent behaviour you may not have wanted, because native video references are numbered entities competing with your pictures.

MiniMax H3 Reference to Video - Guide 0 CLIP Context (BFS) splits the two. Your guide enters the text encoder only - as <Video 1>, with real timestamps - and adds no native guide video reference latents at all. Motion still comes from Add Guide, separately, from the same frames.

How it works

It's a subclass of ComfyUI's native MiniMaxH3ReferenceToVideo, so the schema, the image references, the audio references and the VAE paths are all the native implementation. Only two things change.

First, a new optional input guide_video_0 and its sampling control clip_video_fps. When a guide is connected, the node wraps your CLIP in a request-local adapter. On tokenize, that adapter splices the sampled guide frames in as a video item positioned after any images and before any real video references - which is why the guide is <Video 1> and your ref_videos start at <Video 2>. It's request-local: your CLIP object and cached conditioning are untouched.

Second, it verifies. The adapter counts H3's minimax_video_block tokens in the tokenized output and raises if the expected blocks aren't there: "CLIP did not produce the H3 video vision blocks. Use the native MiniMax H3 CLIP loader." That's a genuinely good failure - the alternative is a graph that runs, looks fine, and silently ignores your guide video.

The frames are sampled at clip_video_fps, capped to the source rate (never duplicating frames), resized to H3's canvas multiple, and given real timestamps. No video VAE encoding happens for the guide. The target latent starts empty and the console logs the details: [BFS H3 CLIP context] ... guide: input=N frames at 24 fps; used=M; requested=2 fps, effective=2 fps; ... native guide video reference latents: OFF.

Inputs and outputs

• clip - the native H3 CLIP loader. Not a VLM, not something else's text encoder; the tokenizer check will catch you.
• vae and audio_vae - H3's own.
• guide_video_0 (optional) - your motion guide or current shot, as native 24 fps frames. Qwen sees it at clip_video_fps; connect the same frames to Add Guide for motion.
• clip_video_fps (default 2, range 0.5–24) - the experiment dial. 2 fps is H3's native presentation; try 4 or 8. Higher costs context and encoding time and does not change output fps.
• width / height (1344×768) and length (124, i.e. about 5 s at 24 fps; the author notes the trained range is roughly 124–362).
• ref_image_size - match scales references down to the generation's pixel area; max uses a 2048px short edge for identity fidelity, and is several times slower because reference tokens attend through every step.
• ref_images, ref_videos, ref_video_audios, ref_audios - native autogrow inputs. With a guide connected, ref_videos are <Video 2>, <Video 3>, <Video 4>, capped at three.

Outputs are positive and LATENT. Neither goes straight to a sampler: wire both into MiniMax H3 Add Guide with the same guide frames, the same VAE and frame_idx = 0, then take Add Guide's conditioning to your guider.

Install

Manager → search ComfyUI-BFSNodes, or:

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

Restart ComfyUI afterwards. The Python requirements are ordinary (torch, numpy, Pillow, safetensors, librosa, opencv-python, scenedetect); what matters is a ComfyUI current enough to include the native MiniMax H3 nodes and a native H3 CLIP loader, since this node builds directly on them.

Where people get burned

Expecting this to improve identity. Checkpoints trained with guide_latent_only never saw the source video in Qwen, so this is an inference-time experiment, not a demonstrated quality win. Compare against plain aligned guide with everything else fixed - same shot, prompt, references, seed, sampler - before deciding it helps.

Cached results. In the Shot Planner loop, cached renders can return the old output and the [BFS H3 CLIP context] logs won't appear at all. If you don't see the log, your new conditioning never executed.

Audio confusion. Guide audio does not ride along with guide 0 - supply it through Add Guide. Reference soundtracks stay paired to their own ref_video_N inputs.

Frame counts. Video inputs get trimmed to your requested target length and rounded down to the 17k+5 grid. Ask for 124 and hand it 120 frames and you'll get 107, which is correct behaviour and still surprising the first time.