BFS H3 Apply Cast Reference Bindings

What this node actually does

BFS H3 Apply Cast Reference Bindings is the last link in BFSNodes' click-to-Picture chain. You clicked a performer in the source video, SAM 3.1 tracked them across the clip, and now something has to turn those tracked masks into an effect the sampler will obey. That's this node. Its one output is a MODEL, and its job is to bake per-Picture reference gains into that model before it reaches the guider.

Reach for it when a MiniMax H3 workflow keeps mixing two characters' faces. Prompt text can say "the man on the left" all day; if the encoder is being fed two reference Pictures of two different people, the attention has no spatial reason to prefer one. This node gives it one. The repo's own docs are blunt about the scope - it applies a regional attention adjustment, and it "is not inpainting or pixel/background locking." Set your expectations to "the model looks at the right reference here," not "this face is welded in."

The mechanism, in one paragraph

Under the hood it doesn't reinvent anything: it instantiates the pack's own Reference Attention Binding node once per tracked Picture and passes each mask in as that node's target_mask. So for a two-performer shot you get two chained attention policies, each saying "inside your mask, weight keys belonging to Picture N by this much." If you connect loop_state, it first slices the full-video track down to the current shot's frame range, then trims to prepared_length - and if the track is shorter than that, it repeats the last mask frame to fill. That padding is why a 107-frame H3 shot works with a mask that only tracked 95 frames.

Inputs worth touching

model is the H3 model coming out of TARA. cast_masks is the bundle from BFS H3 SAM 3.1 Cast Tracking - it's a lazy input, so a disabled upstream branch doesn't force SAM to load.

prepared_length is the frame count of the shot you're generating: default 107, min 5, stepping by 17. That 17-step is the H3 latent grid (17n+5). If your sampler is working on a different prepared length, this is the field that silently mismatches and gives you a mask that's the wrong length.

reference_strength (default 1.25) and other_reference_strength (default 1.0) are the two knobs that matter. 1.0 is neutral for both. The author's starting point is 1.25 / 1.0; nudge the second down toward 0.75 when identities still bleed into each other inside the mask. Don't lower it blindly - it also damps the background and continuity Pictures.

enabled false returns the model untouched. Wire the output to your guider and to the scheduler, same model in both places.

Install

Same pack, same steps as everything else here:

cd ComfyUI/custom_nodes
git clone https://github.com/alisson-anjos/ComfyUI-BFSNodes.git
cd ComfyUI-BFSNodes
pip install -r requirements.txt

Restart ComfyUI, then hard-refresh the browser tab - several nodes in this pack ship a web/js panel and won't show their UI until the frontend reloads. You also need a ComfyUI build that has the native SAM 3 nodes (comfy_extras/nodes_sam3.py) for the tracking upstream of this node, and sam3.1_multiplex_fp16.safetensors in ComfyUI/models/checkpoints if you're using the pack's optional SAM loader.

Worth knowing before you invest: BFSNodes has essentially no community footprint. Searching the modidex Reddit corpus for the pack name returns two threads across all of r/comfyui, r/StableDiffusion and r/civitai. There's no pile of users who already hit your bug. The repo's H3_CAST_AND_TOKEN_CONTROLS.md and H3_REFERENCE_BINDING.md are unusually detailed, and they're honest that the validation is CPU-side logic checks - no browser or GPU end-to-end run was signed off. Treat it as an experimental branch you're testing, not a production dependency.

Common issues

"Full-video masks must use the same loaded 24fps video as Loop Start." The tracks were made from a different clip than the loop is slicing. Both have to come from the same 24 fps load - the usual culprit is a second VideoHelperSuite loader with different trim/skip settings somewhere in the graph.

Masks track nothing on some frames. The SAM node's report output lists per-Picture empty_frames and mean_coverage; if coverage is zero for a stretch, this node will happily apply a gain to a region where nothing was found. There is no automatic closed-loop mask repair - go back and fix the selection points, or split the shot at the moment tracking breaks.

It got slower. While nonzero gains are active, the reference policy composes through exact Flash Partitions with LSE merging, and Kitchen's fused one-pass path is bypassed. That's expected, not a bug. Sparse attention (sol-attn) isn't supported in this path either - remove the sparse attention node while you're experimenting.

One picture per node, many nodes per shot. With two subjects you need two binding nodes, and the masks have to actually follow the right person through the frame. This node doesn't segment, track, or guess.