H3 Video Reference

Why you'd reach for it

Video-to-video motion transfer was the thing the community singled out as genuinely impressive when H3's weights dropped - "can do motion control like Kling" was a launch-day thread. The problem is that a motion reference is only useful if you can say which motion, and "use the movement from this clip" doesn't scale to a prompt with three sources in it.

H3 Video Reference is the video half of the tagging system in the H3 RefMod suite: point it at a clip, give it a tag, say what role it plays, and then reference it by name in your scene prompt alongside your images and audio.

How it works

source has three modes, and they're not interchangeable. Connected video takes a native VIDEO and reads its components (frames, audio, frame rate). Connected frames takes an IMAGE batch off a video-loading node and needs you to supply fps yourself, because a batch of images has no timing - that's what the fps widget is for, and it defaults to 24. Load file reads a video directly from disk.

role decides what H3 is told to do with it, and the built-in guidance is specific rather than decorative: motion uses the referenced motion while retaining the target character's identity, performance uses the referenced performance while retaining identity, camera uses the camera movement and framing. scene and custom round it out.

start_seconds / duration_seconds trim the clip, and descriptor is what the @tag expands to in the prompt - the tooltip's example ("the living room with grey sofa") is a good template: describe the content, not the filename.

Then use_soundtrack, which is where this node earns its keep. Turn it on and the clip's audio is packaged as a second, paired audio reference with its own audio_tag, audio_role, audio_character and audio_instructions. The paired block is sent to H3 as one unit, and - important if you're watching VRAM or budgets - its audio cost is reported as included in the paired video block rather than as a separate line, because that's how the encoder actually produces it. Soundtrack is off by default, and it errors if you enable it on a source that has no audio.

Outputs: named_reference (H3RC_REFERENCE, into the main node), selected_video, selected_frames, selected_audio (the extracted soundtrack), fps, and selection_report. Handy detail: the video output is rebuilt as a video component at 24fps from the selected frames and soundtrack, so what you pass downstream is exactly what gets sent to H3.

Why the range matters

Trimming a reference is not cosmetic. A video reference is encoded as a clip, token cost is duration-dependent, and a 30-second reference can dominate a budget you were planning to spend on pictures. duration_seconds of 0 keeps everything from start_seconds onward, which is usually the wrong choice for a long source.

If the reference roles you care about are two clips at once, remember that each node is one source; two nodes with distinct tags is the pattern, not one node with two videos.

Install

ComfyUI Manager → search WorkflowX Configurator, or:

cd ComfyUI/custom_nodes
git clone https://github.com/haroonaslam/WorkflowX-Configurator
cd WorkflowX-Configurator && pip install -r requirements.txt

Restart and hard-refresh the browser. The node itself is pure graph work - it doesn't load a model - but the workflow it feeds needs ComfyUI with native H3 support, the H3 weights (large, and geofenced: the Community License excludes the US, EU, UK and Korea), the visual VAE for pictures and video references, and the audio VAE if you're sending soundtracks.

Where it goes wrong

"It says the soundtrack is enabled but this source has no audio" - that's the honest error for a frames-only source, and it's easy to hit after switching source from Connected video to Connected frames, because the audio socket you had connected is no longer being read.

Frames-mode fps mismatches are the quiet one. Feeding a 30fps batch while claiming fps = 24 doesn't error; it just makes your trim ranges land in slightly the wrong place and the encoded clip slightly the wrong speed. Set it from the loader that produced the frames.

And as with every reference in this suite: H3 owns the generation. A motion reference asks for movement, it doesn't guarantee it, and the pack's own README is candid that correct associations can't guarantee exact identity.