Load H3 RefMod Folder

Extract H3 RefMod is great at one character shoot at a time, but it gets tedious when you've got a folder of forty shots. Load H3 RefMod Folder is the bulk loader: it grabs every image and video in a directory, hands you an ordered reference list, and lets you point Extract at the whole batch at once. The README's example is a movie dataset; a whole character shoot from a handful of angles is the more everyday case.

The wiring is one line of intent: Load H3 RefMod Folder → refs_bundle → Extract H3 RefMod. Folder refs are appended after your autogrow refs, so if you've hand-picked a couple of anchor shots into ref_image_1, they still lead the canvas and the folder fills in around them.

How it works

Point it at a folder and it loads supported images (png/jpg/webp/bmp/gif) first, then videos (mp4/webm/mov/mkv/avi), each group sorted by filename, up to the caps you set. The refs output is an H3_REF_LIST plus an INT count showing how many made it in. Two of its three controls are your real dials:

• folder - an absolute path, or a folder name inside ComfyUI's input/ directory; empty string means input/ itself.
• max_items (default 32) - cap on media files loaded, images then videos.
• max_frames (default 240) - cap on video frames kept, uniformly sampled during decode. This is the memory governor: a long video is never fully decoded into RAM, so memory stays bounded by this cap times max_edge. 240 frames is ~10 seconds at 24fps.
• max_edge (default 1024) - longest pixel edge for loaded files, downscale only. Loading many 4K files at native resolution is what OOMs ComfyUI; Extract resizes to ref_resolution anyway, so 1024–1280 is plenty for folder extraction.

Install

ComfyUI Manager (search "ComfyUI-MiniMaxH3Mod") or:

cd ComfyUI/custom_nodes
git clone https://github.com/Luisacaotica/ComfyUI-MiniMaxH3Mod

Restart. Python deps safetensors, numpy, Pillow install automatically. For video decode you may need one of the optional backends - opencv-python or imageio - that are soft-imported and not in the hard requirements:

pip install opencv-python

(inside ComfyUI's Python environment). If the loader can't read your videos, that's the first thing to check. You also need H3 weights + its VAE in a current ComfyUI; remember H3's licence is territory-restricted (US/EU/UK/Korea excluded from local weights).

Common issues

Unreadable files are skipped with a console note rather than killing the run, so check the log if your count looks short - a corrupt or codec-less file silently isn't there. The count output is your fast sanity check: it should match what you expect from the folder. And keep the ordering caveat in mind: images load before videos, then by filename, so if you care which ref leads the moodboard, name your files deliberately. ComfyUI may reuse cached results when the folder hasn't changed - the node tracks file size and mtime, so adding or editing files does invalidate the cache, but touching nothing means you get the same list, which is usually what you want.