MiniMax H3 Role Replacement Inputs

Swapping the person in a video for a character from a reference image is the most-wanted and least-documented trick on MiniMax H3. The native path wants a reference frame stack, a width, a height, a length that lands on H3's latent grid, a character image, and a prompt whose <Picture N> / <Video N> tags actually match your assets. Get any one of them wrong and you get a video where the face flickers between identities, or an error forty seconds into sampling.

HenjiccH3RoleInputs - MiniMax H3 Role Replacement Inputs, category Henjicc/Video - is a pre-flight node. It takes your asset strip and emits all of those things, already consistent.

What it does with your source video

It expects a HENJICC_MEDIA bundle (from the pack's Super Input) whose profile is MiniMax reference mode, containing exactly one video and up to nine images. No standalone audio, and the video's own soundtrack must be switched off - the node rejects both, because the H3 role-replacement path doesn't take audio references and silently dropping them would be worse than erroring.

The video is decoded with a bounded PyAV pass at a 24 fps target grid, fitted into a megapixels budget (default 0.4) and capped at a 768-pixel short edge, dimensions snapped to 32. Then it does the thing you'd otherwise do in your head: H3 works on a frame grid of 17k+5, so the true frame count gets rounded up to the next 17k+5 and the gap is filled by repeating the last frame. That padded stack is reference_frames. The unpadded, honest frames come out separately as video_frames, and duration is the real length in seconds (frames ÷ 24, a float - not your widget value).

The inputs you actually set

• media - the asset bundle. Profile must be MiniMax reference or you get "Role replacement requires MiniMax reference mode."
• megapixels - 0.05 to 1, default 0.4. Your reference video gets downscaled into this budget before anything else happens. Raising it costs VRAM quadratically for detail H3 probably can't use at 480p-ish output.
• duration - integer 4 to 15 seconds, default 5. Ignored when…
• match_source_duration - is on. Then the node measures the clip's real length instead, bounded to 15 seconds, and skips re-probing the file to do it.

The outputs, and where they go

reference_frames is the padded stack that goes into the host's H3 reference/role video node. width, height, length are the integers that node's widgets want - length is the padded count, so it's always ≥ your real frames and always ≡ 5 mod 17. video_frames is the unpadded version, for anything frame-accurate. character is the first reference image as a single IMAGE, which is what a character-swap LoRA or native character input expects. prompt is your compiled prompt with H3-style labels (<Picture 1>, <Video 1>) already substituted. duration is the real float duration - wire it into HenjiccH3VideoOutput so the final trim matches what was actually generated. images is the full reference list.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/henjicc/ComfyUI-Henjicc.git ComfyUI-Henjicc
python -m pip install aiohttp av numpy Pillow

Restart, hard-refresh, or just install comfyui-henjicc from Manager. Video decoding needs av (PyAV), which is in that list - but the actual H3 model work happens in ComfyUI's own comfy_extras.nodes_minimax_h3, so pair this with a ComfyUI new enough to have it.

Common issues

"Role replacement requires MiniMax reference mode." The Super Input detects its mode from what's downstream, but the reference/first-last task choice inside a MiniMax mode is explicit. Set it in the panel; don't assume it followed your wiring.

"This role replacement workflow does not support audio references or video soundtracks." Turn off "use soundtrack" on the video item and remove any audio items. The node validates this up front rather than letting H3 fail obscurely.

Padding surprises you. reference_frames has more frames than video_frames by design - up to 16 extra copies of the final frame. If a downstream node counts frames, that's why.

Long or wildly-specified sources. The decoder bails after 7,200 decoded frames and tells you to trim first. Also, and this is not a node problem: MiniMax H3's community licence excludes the US, EU, UK and Korea from its applicable territory for the open weights. Worth knowing before you build a workflow around it.