Sonder Reference Image Bridge

The Sonder Reference Image Bridge is where your timeline references stop being an editing concept and become tensors. Inside the ComfyUI-Sonder-Editor timeline editor, you stage a character's face, an outfit, a location - Library members sitting on Reference lanes, each scoped over a range of frames. When you select a render window and run the prompt, this node decodes the members that are effective for that window and hands them to whatever reference-conditioned model your workflow targets. The result is that one workflow keeps working while the model changes underneath it, which is the whole Sonder pitch.

How it works

The bridge takes a reference_set from Sonder Reference Selector - wire the Selector's reference_set output straight in. What comes out depends on the lane's recipe, which is the editor-side setting that decides how staged members are assembled:

• Slot recipes emit one member per output socket (r01, r02, …). MiniMax H3 Pictures, which takes separate reference inputs, is the classic case: stage three members and you get three populated sockets.
• Non-slot assemblies - batch, sheet, or temporal - emit one payload per lane. A sheet recipe composites members into a single panel-grid image; a temporal recipe lays them along time. LTX IC-LoRA Ingredients and Best Face ID work this way, reading one composed reference image.

Order matters and never drifts: payloads concatenate by lane index, and each member goes out in staged order. The sockets are fixed - r01 through r16 - and a lane reserves its widest staged member count even when it isn't currently effective, so an inactive lane leaves its outputs reading (unused) instead of shoving later lanes around. ComfyUI type-checks sockets by position, so that stability is deliberate.

One documented quirk: MiniMax H3 video lanes also flow through this bridge, emitting 24 fps IMAGE sequences on the model's 17n+5 frame grid. If you're driving H3 video references you'll see batches of frames rather than single images.

The only input you'll fiddle with

unused_slots decides what a slot the recipe doesn't drive emits:

• placeholder (default) - a black image at scene size. A consumer node with a required input needs this or the link can't exist.
• nothing - no value at all, for consumers whose inputs are optional. Use it when a placeholder would otherwise be treated as real content - a black image fed to an optional reference input is worse than nothing.

The canvas tells you when you've wired a dead slot into a required input: it reads (unused · required input) right on the link. That's the node's way of saying "you staged two members but your model wants nine."

Where it sits in the workflow

Selector → Image Bridge → your model's reference inputs. If you don't run Sonder Editor's timeline, you'll never use this node - it has no meaning without a project, staged lanes, and a render selection upstream. If you do, it's the difference between hand-loading reference images per shot and having the editor decide which character is on screen for this window.

Install and gotchas

Install the whole pack once - the bridge, the Selector, and the audio/prompt siblings arrive together:

cd ComfyUI/custom_nodes
git clone https://github.com/SonderSaid/ComfyUI-Sonder-Editor.git
cd ComfyUI-Sonder-Editor
pip install -r requirements.txt

Then restart ComfyUI. ComfyUI-Manager lists Sonder Editor once it's on the Registry; until that first publish lands, the clone above is the reliable route. Things that actually bite:

• Recent ComfyUI required. This bridge uses the newer V3 node API and only loads on current builds. If it's missing from your node list, update ComfyUI first.
• ffmpeg helps. The pack bundles an imageio-ffmpeg fallback, but the README recommends a system ffmpeg on your PATH for the widest decode/export format support.
• OpenCV conflicts. The pack deliberately uses opencv-python-headless; if another custom node installed the full opencv-python, the two fight and cv2 imports can break. Keep one variant - headless - across your whole environment.
• No model downloads, no torch install. The pack ships no weights and refuses to touch torch, so it can't clobber the CUDA-matched build ComfyUI already gave you.

If your outputs look like a black-image surprise, check unused_slots before suspecting your model - a placeholder is almost certainly what you're seeing.