Ref Folder Cowboy

Batch video pipelines have a per-clip problem: every clip in a folder needs its own set of reference images, and wiring six ref slots per clip by hand doesn't scale. This node loads up to six reference images from a folder onto six fixed outputs in natural-sort order - and here's the trick that makes it safe to wire once and forget: empty slots output None, and optional inputs like the MiniMax H3 ref_image sockets treat None as "not connected." So all six outputs stay wired through the whole batch, and a clip with no refs just runs ref-less instead of erroring.

How it works

Give it a directory and it lists the image files (png, jpg, jpeg, webp, bmp) in natural-sort order - the vid1 < vid2 < vid10 ordering, not alphabetical - and puts the first six on image_1 through image_6. count reports how many were found and names gives the filenames in slot order, which is useful for logging and for branching when a clip genuinely has no refs.

The filename_key input is the batch-pipeline hero. Wire a VideoFolderCowboy.filename output into it and the node loads from directory/<filename_key>/ instead - so clip 000.mp4 pulls refs from refs_by_clip/000/, clip 001.mp4 from 001/, and so on. That single wire is what turns a per-clip render pipeline into something that runs the whole folder unattended.

Two robustness details are worth knowing:

• An empty or missing folder is not an error. Every slot passes None and the run continues. The design assumes some scenes have no character refs.
• Cache-busting via mtime. IS_CHANGED is computed from file modification times, so if you replace a ref file in the folder, the node re-runs instead of serving the stale image ComfyUI cached.

The outputs

image_1..image_6 (each a single IMAGE, None when the folder has fewer than that many), plus count and names. Wire the six image slots into H3's six ref_image inputs, or into the pack's Ref Preview Cowboy to eyeball them, and leave them that way forever - the None behavior makes re-wiring unnecessary.

Installing it

Part of TrentNodes; one install:

cd ComfyUI/custom_nodes
git clone https://github.com/TrentHunter82/TrentNodes.git
cd TrentNodes
pip install -r requirements.txt

ComfyUI Manager ("Trent Nodes") works too, with the recurring caveat that the author's day-one repo rename left a duplicate registry entry that occasionally makes Manager flag the pack as "unsafe" - the manual clone is the reliable path. Requires OpenCV (in requirements); no model downloads.

Where people get burned

• Assuming an empty folder is a bug - it's the intended "run ref-less" signal. Branch on count if you need to do something different when there are zero refs.
• Cache not updating after replacing a ref - it does update, via mtime, but only if the file's modification time actually changed. Copying a file over an existing one usually updates mtime; some sync tools preserve it, and then you'll want to touch the file.
• Slot order surprises - order is natural-sort, not creation order. If your refs are named ref1.png … ref10.png, natural sort gets them right; plain alphabetic order would put ref10 after ref1.