H3 Reference Splitter (genkai)

MiniMax H3's reference-to-video mode is the interesting half of that model: instead of one start frame, you hand it a set of pictures, clips and audio and it composes from the whole context - the same trick instruction-edit models use, applied to video. Native ComfyUI nodes want those references as individual IMAGE and AUDIO sockets, numbered and in a specific order.

H3 Reference Splitter is the adapter: one H3_REFS bundle in, eighteen typed sockets out.

How it works

It's the second half of a pair with H3 Media Loader, and it's a bundled port of the splitter from Adudeguyman's Fantastic H3 media pack (MIT, upstream 1.7.1). The bundle carries references in visual slot order; the splitter unpacks them per type:

• picture_1 … picture_9 - IMAGE
• video_1, video_2, video_3 - IMAGE
• video_audio_1 … video_audio_3 - AUDIO
• audio_1, audio_2, audio_3 - AUDIO

The rule you must not break: disabled references are skipped, and the remaining references of each type are numbered in visual slot order - left grid first, then the right-hand sections. So if you disable picture slot 2, whatever was in slot 3 becomes picture_2. Wire your graph first and then start switching slots off, and every reference downstream shifts by one. It won't error; it'll just use the wrong image, which is worse.

The second thing people trip on: video references come out as IMAGE, not as a VIDEO. You get frames, not a video object. That's what the H3 reference inputs take, but if you were expecting to pass one of these to a node that wants VIDEO, you'll be looking at a dead-end wire and assuming the port is broken.

The inputs and outputs that matter

There's one required input, references, of type H3_REFS - and only H3 Media Loader produces that type. The splitter declares all eighteen outputs regardless of what's in the bundle; the ones with nothing behind them simply don't carry data, so leave them unconnected rather than hunting for something else to plug in.

When you wire them up: connect output 1 to the model's corresponding native reference input 0 and continue in order. That ordering convention is the upstream pack's, and it's the difference between a reference set that lands on the right slots and one that's silently permuted.

Brackets around the whole approach

Two honest limits, both about H3 rather than about this node.

The reference and audio budgets are the model's, not the loader's. Nine pictures is a generous UI, but H3's own limits still apply, so filling every slot and hoping for the best is not a strategy.

And the licence: H3's community licence scopes its grant to a territory that excludes the US, EU, UK and South Korea, outputs included. This pack is MIT-licensed glue - that part is clean. The weights are a separate question, and it's the one to actually read.

How to install it

cd ComfyUI/custom_nodes
git clone https://github.com/GENKAIx/Genkai-ComfyUI-Nodes

Manager search Genkai-ComfyUI-Nodes works the same. Restart, Ctrl+F5, then look under GENKAI → Media. The original Adudeguyman pack is not required - the splitter's decoder and HTTP handlers ship inside this pack. No models, no pip installs.

If you already have this pack installed as GENKAI_nodes from an earlier name, replace that install rather than keeping both; duplicate registrations of the same node identifiers are a bad time.

Common issues

The references input won't accept anything. It only takes H3_REFS. Nothing else in ComfyUI produces that type, which is correct - the loader-to-splitter link is the intended path.

Wrong reference in the wrong slot. You changed the enable switches after wiring. The numbering is positional over the enabled references, not over the slots.

Extracting audio from a video reference. That's the loader's job, done per slot: video sound can be off, paired with the video, or standalone. The splitter reports what it was given - if video_audio_2 is empty, the loader was told to drop that clip's sound.