LoadVideoReference

MiniMax H3's headline party trick, as far as the community was concerned, wasn't the 2K output - it was video-to-video motion transfer, the thing people compared to Kling on launch day. To use it you hand the model a clip as context, not as a latent and not as a stack of decoded frames. The reference socket is ref_videos.ref_video_0, its type is VIDEO, and that type is not an image batch.

That distinction is where most people first get stuck, and it's the whole reason this little loader is worth knowing.

What it actually does

Follow the data, because the node is three lines and the surprise is in the third line.

Upstream, your TOML registers a path:

[h3.refs]
motion = "<load type=video key=motion>/home/you/refs/pan.mp4</load>"

[h3.prompt]
_t = """<Video motion> drives the camera path; keep the subject from <Picture hero>."""

PromptDecodeV2 parses that into a LOAD_REFERENCES object and exposes it as its seventh output. The <Video motion> tag in the text becomes <Video 1>, which is slot 1, which is the socket the H3 node calls ref_video_0.

Then LoadVideoReference does references.get("video", n) and, when it finds a path, calls InputImpl.VideoFromFile(ref).

That's the interesting bit. InputImpl.VideoFromFile is from comfy_api.latest, and what it returns is a handle - an object pointing at the file on disk. Frames are decoded lazily, downstream, when something actually asks for them. Queue a 30-second 4K reference and this node costs you approximately nothing; the memory bill shows up wherever the video finally gets read.

Compare that to VideoHelperSuite's Load Video (Upload), which hands you an IMAGE batch - every frame, decoded, in VRAM, plus a separate audio output. Different tool, different job. If you want frames to feed a sampler, you want that one. If you want to pass a clip to a node that declares VIDEO, you want this.

Inputs and outputs that matter

• references - LOAD_REFERENCES, from PromptDecodeV2's References output. Without that wire the node has nothing to look up.
• n - INT, 1 to 10, default 1. The video slot index. Slot 1 is <Video 1>, which is ref_video_0.

One output: VIDEO. Wire it to ref_videos.ref_video_0 on the H3 reference node, or any other VIDEO input (CreateVideo, SaveVideo, the video-input side of most 2026 video packs).

Note the pack also has LoadImageReference and LoadAudioReference with the same two-input shape. Same plumbing, different slot list - the get("video", n) versus get("picture", n) is the only real difference.

Install

ComfyUI Manager, search comfyui-toml-prompt, or:

cd ComfyUI/custom_nodes
git clone https://github.com/morino-kumasan/comfyui-toml-prompt

Restart. No pip step - the pack's requirements.txt is empty - and no model downloads of its own. Your .toml goes in ComfyUI/custom_nodes/comfyui-toml-prompt/prompts/, which is the directory PromptLoader enumerates. Ignore the README's install block: it still calls the repo comfyui-utils and uses an [email protected]: URL that fails without SSH keys.

Where people get burned

A NameError the moment you queue. The pack imports InputImpl from comfy_api.latest inside a try/except ImportError block alongside torch, PIL and numpy - and swallows the failure. On a ComfyUI old enough to predate that API, the nodes still register and look perfectly installed, then throw NameError: name 'InputImpl' is not defined on the first run. Update ComfyUI. This is the one dependency on the whole pack, and it's not in any requirements file.

Wiring a frame batch into a VIDEO input. They're different types and the graph will refuse the connection, but people work around it by converting, then wonder why nothing matches. If your source node gives IMAGE, you're on the wrong loader.

An empty slot is silent. The node returns None when n points at nothing, rather than raising - so a reference you forgot to include in key_name_list produces a confusing failure two nodes later instead of here. Slot numbers come from the order the parser first encounters each alias, so a <Video name> tag earlier in your selected keys can outrank a <load> that looks like it comes first. Use names, not numbers, and let the parser do the counting.

Codec roulette. Whatever ComfyUI can already open in its own video nodes is what this can open - it hands the path to the same container machinery. An .mp4 your install chokes on won't decode here either, and the error will surface downstream, not in this node.

Absolute paths. The path string is passed straight to the file API, with no join against your prompt directory. Relative paths resolve against ComfyUI's working directory and will bite you on the next launch.