BFS H3 Reference Attention Binding (Experimental)

What you're actually buying

H3's native images are conditioning, and reference-to-video conditioning is a negotiation: the model decides how much each Picture gets to influence each patch of the output. Usually that's fine. Sometimes Picture 1 is the face you care about and the model is treating it as set dressing, and there's no prompt wording that fixes a weighting problem.

BFS H3 Reference Attention Binding (Experimental) puts a thumb on that scale. Give it a Picture index and a gain, and generated video tokens will attend to that Picture harder. Add a mask and it happens only where the mask is white.

The framing in the docs is refreshingly deflationary: "an inference experiment, not a trained identity tracker or a proven quality fix." It won't keep a face consistent for you. It changes one multiplier in the attention stack.

The exact rule

For a target-video query sitting inside mask weight m, and a key belonging to Picture i, the attention logit gets:

m * log(gain_i)

So the unnormalized attention weight is multiplied by gain_i ** m, before the shared softmax normalises across all keys. Which means, and the author says this explicitly: it is not multiplying reference pixels, not multiplying V tensors, and not a promise that the final attention probability rises by that percentage. 1.25 is a neutral-ish starting nudge, not "+25% identity."

Scope is narrow on purpose. Only target-video queries against native image keys get touched. Target-to-guide keys keep TARA's temporal penalty untouched, other keys keep their original rules, and Picture indices don't shift. Soft masks are area-downsampled to target patch resolution and averaged across H3's latent temporal spans, so you don't need pixel-perfect masks.

Inputs you'll set

model in, MODEL out - and it goes after TARA:

Model + LoRA → TARA → Reference Attention Binding → CFGGuider

Use the resulting model for the scheduler too. Nothing new connects to the positive socket; the pictures and guide stay on the existing Native Reference Set to Video path.

picture_index (1–9) is the existing native Picture number. Video indices are counted separately, so Picture 3 is Picture 3.

reference_strength is the gain for that Picture - 1 is neutral, start at 1.25, then compare 1 / 1.25 / 1.5 with the same seed, prompt and everything else. other_reference_strength is the gain for other Pictures inside the same region; keep it at 1 initially, try 0.75 to reduce identity mixing. It also damps your background and continuity Pictures, so don't crank it down indiscriminately.

target_mask is optional. No mask means the gain applies to the whole output video. A mask means: one static mask, or one mask per prepared shot frame at 24 fps. Critically, it describes output/guide positions, not the reference photograph - you're marking where in the generated frame this Picture should dominate. And this node performs no tracking, so whatever produced the mask had to follow the subject.

enabled off returns the original model with no policy attached.

Install

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

Restart, hard-refresh the browser, and load examples/h3_tara_reference_binding.comfy.json rather than building it by hand the first time. You need TARA in the graph, a CUDA GPU with FP16/BF16 native FlashAttention that supports LSE (merged log-sum-exp), and the H3 models of course. Nothing extra to pip install or compile for the reference-control code itself.

The licence context, since it comes up: H3's open weights are under MiniMax's community licence, which excludes the US, EU, UK and Korea from its Applicable Territory. Whatever you think of that, it's the terms the weights ship under.

Common issues

Mask length mismatch. target_mask must be either one frame or exactly the prepared 17n+5 shot length, padding included. A whole-clip mask fed into a 107-frame shot will throw. Slice it - that's precisely what Apply Cast Reference Bindings does for you.

"Remove Model Sparse Attention." While nonzero gains are active the prototype composes reference gains with TARA through exact Flash Partitions and LSE merging. Kitchen's fused one-pass path gets bypassed, and sparse routing isn't supported at all. Leave the sparse attention node out of the graph for this experiment.

It's slower, and that's the trade. Partition overhead can make this slower than the fused TARA-only Kitchen path. You're paying for granularity.

Identity still mixes. Two subjects means two chained binding nodes - Picture 1 with A's tracked mask, Picture 2 with B's. Overlapping masks combine their log gains, which is usually not what you want; keep them disjoint if you can. And the node doesn't read your prompt: explicit identity assignments in the text are still required.

Quick sanity check. The log prints [BFS H3 reference binding] ACTIVE and using Flash Partitions when the policy is live. If you don't see those lines, your gains are neutral or enabled is off and you're looking at a placebo diff.

Don't trust it blindly. Six CPU checks pass against a dense softmax oracle; per the author, there's no GPU video-quality, speed, Windows or browser validation for this prototype. Compare against your own baseline at the same seed before you conclude anything.