MiniMax H3 Video Reference (Plan v2)

In MiniMax H3, a reference video is never just "a video." It can be something to edit, something to continue, a motion source, a style guide, or a temporal blueprint - and those jobs produce very different prompts. This node is the Plan v2 way of declaring which one you mean, before the pack's compiler writes anything.

That distinction is the point, and it's also where most reference workflows quietly go wrong. People feed a clip in and hope H3 "gets it." The model gets exactly one interpretation. The Plan v2 Video Reference makes you commit to the job first, and the compiler builds the H3 prompt around your answer instead of guessing.

Why it exists

This is the typed, newer half of ComfyUI-MiniMax-H3-Guide. The pack's older workflow used a single "how video is used" dropdown buried inside a big form node. Plan v2 splits everything into dedicated nodes that pass an ordered MINIMAX_H3_PLAN_V2 value down a chain, and the Video Reference is where a decoded clip enters that chain. It sits right after Project Setup, alongside its image and audio siblings.

The clever bit is motion transfer. If you pick Motion or action reference, the node keeps the clip on a native video route but the compiler also synthesizes a reusable action Subject out of it - the thing H3's prompt guide actually wants. So your subject ends up doing the action, not reproducing the whole reference clip.

The inputs that matter

The default video_use value is "Choose a video relationship," and leaving it there deliberately stops execution. The five real choices are: edit a source video, continue a source video, define reusable visible content, motion/action reference, or camera/cuts/rhythm/temporal-structure reference. That dropdown is the entire point of the node - everything else supports it.

• source_fps - the frame rate of your incoming IMAGE batch. Get this wrong and every duration downstream lies. The output h3_video is resampled to 24 FPS and aligned to H3's native 17k+5 frame grid.
• description - source facts plus the exact relationship you want. This is the prose that becomes the prompt's reference language, so be concrete.
• content_type, subject_name, target_subject, retention - only matter when the video defines reusable visible content or a motion transfer. For motion, target_subject must name something that already exists upstream in the plan.
• shot_scope - optional, e.g. 2 or 2-4, to scope the role to specific shots.

Outputs

h3_plan continues the setup chain. reference_handle connects to a Subject Binding or to an Audio Reference's paired-video input. h3_video is the corrected 24 FPS batch for the native H3 node. reference_preview is a string you can wire to a text viewer - it shows effective media timing, relationship, target, and the provisional native route. Read it once when things feel off; it's the pack admitting what it's about to do.

Installing

The pack has no Python dependencies and downloads no models itself - it's a compiler, not a loader.

cd ComfyUI/custom_nodes
git clone https://github.com/ethanfel/ComfyUI-MiniMax-H3-Guide

Restart ComfyUI and look under MiniMax H3 → Plan v2 (ComfyUI Manager also finds it as "MiniMax H3 Guide"). One real prerequisite: you need a ComfyUI build with native MiniMax H3 support - the MiniMax H3 Image to Video and Reference to Video nodes and the MiniMax tokenizer. Update ComfyUI if those are missing.

Where people get burned

• A 30 FPS source left at the default 24 in source_fps. The clip gets silently re-timed.
• Cumulative video references over H3's 15-second cap (each clip 2–15 s, 3 videos max). Watch reference_preview for the enforced numbers.
• Motion transfer without a target_subject. The node will tell you it's incomplete rather than invent one - that's the design working.
• Wiring h3_length out of the Guide in a reference-context workflow. That creates a backward cycle; feed the video reference its length from Target Timing instead.

The license worth remembering: H3's open weights are geofenced out of the US, EU, UK and Korea, so local ComfyUI use of the model itself is off-limits there. The pack doesn't change that - it just writes better prompts for when you can run it.