BFS H3 Native Reference Set to Video

What it's for

MiniMax H3's native Reference to Video node is happy to take pictures, videos and a prompt. What it won't do is notice when the prompt and the pictures disagree - it will encode Picture 3 instructions against a set of two images without a word of complaint, and you'll find out by watching a stranger's face appear at second four.

BFS H3 Native Reference Set to Video is the encoder wrapper that checks first. It takes the same reference set your prompt writer used, the prepared guide video, and the finished prompt, validates that the three agree, and then calls the native node with them.

That's it. It's a thin node with a strict doorman. In a workflow where a VLM writes your prompt, the doorman is the whole value.

How it works

Underneath, bfs_h3_native_workflow.py hands everything to MiniMaxH3ReferenceToVideo.execute() from ComfyUI's own comfy_extras.nodes_minimax_h3 - so there's no reimplementation of H3's conditioning to drift out of sync with core. Your references set becomes ref_image_1 … ref_image_N in order, and reference_video becomes ref_video_1, which in H3's numbering is <Video 1>.

Before that call, four checks:

1. Section validation (optional, validate_h3_sections, on by default): the prompt must start with motion_transfer: or body_swap:, must contain all six sections - subject_definitions:, summary:, retention_analysis:, detailed_description:, overall_soundscape:, non_diegetic_music: - exactly once each and in order, and none may be empty. A VLM that got cut off by a token limit fails here instead of inside sampling.
2. Picture indices: every <Picture N> in the prompt must exist in the attached set, with an error naming the labels you actually have.
3. Set size: 1 to 9 references, which is the native node's own limit.
4. Geometry: width and height must be positive multiples of 32, length must be 17n+5, and the prepared video's frame count must equal length. That last one is the check that catches a stale cached frame count, and the error is explicit - "Prepared native reference video length differs from generation length" - instead of a runtime crash deep in attention.

Note what it does not do: no Add Guide. reference_video goes in as a native video reference, not guide latents. TARA, if you want temporal alignment, is a separate MODEL patch you apply elsewhere on the model path. Bypassing this node for the plain native one gives you the same conditioning minus the validation.

Inputs worth setting

• references - the BFS_H3_REFERENCE_SET from Describe References. Use the same set; that's the contract.
• reference_video - the reference_video_24fps frames from Prepare Native Video.
• prompt - socket only (forceInput), so it must come from Build Native Prompt → Generate Text. You can't type it here, by design.
• width, height, length - defaults are 512×288 and 107 frames, but wire them from Prepare Native Video's width, height and length outputs. The whole point of that node is deriving geometry from your actual clip; leaving these at defaults throws that away.
• ref_image_size - match scales each reference down to the generation's pixel area; max uses the reference pipeline's 2048px short edge for best identity fidelity. max can be several times slower, because reference tokens ride through every sampling step.

Outputs: positive (CONDITIONING) and latent (the empty target latent), which go to your guider/sampler with H3's model and VAE, and effective_prompt - the same prompt string that was encoded, exposed so you can preview exactly what the model read. Handy the first time you suspect the prompt, not the sampler, is the problem.

Install

ComfyUI 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. Dependencies are modest - torch, numpy, Pillow, safetensors, librosa, opencv-python, scenedetect - but the ComfyUI side needs to be current enough to ship the native MiniMax H3 nodes, since this wrapper subclasses/calls into them directly. The author's example workflow targets BFSNodes 1.115.21+.

And check your licence situation before you get attached to a workflow. H3's community licence excludes the US, EU, UK and South Korea from its Applicable Territory for the open weights - that's a legal constraint on running this locally, not a technical one, and no node pack can help you with it.

Where people get burned

Length mismatch. The most common failure, and it's always the same story: someone typed 107 into length while the prepared video has 124 frames. Wire the integer outputs and stop typing them.

Silent prompt truncation. If you turn validate_h3_sections off because it keeps erroring, you don't get a warning later - you get a video that ignores half your prompt. The error is telling you to raise Generate Text's token budget.

ref_image_size: max on a long clip. Identity gets a bit crisper and your render time multiplies. Try match first, and only go max when the face genuinely isn't holding.