DuckAttention Couple

DuckAttention Couple is the node that actually does regional prompting: it takes your model, a base prompt, and a set of masked regions - each with its own prompt - and returns a patched copy of the model that steers each region's pixels with its own conditioning. It's the "two characters with their own hair colors" node, and it attacks the single most stubborn failure of multi-subject generation: attribute bleed, where a prompt describing two people smears their traits together no matter how carefully you phrase it.

The mechanism is attention coupling, and it's worth understanding roughly even if you never touch the code. Inside the model's cross-attention, the node builds a mask stack: the whole canvas gets a base mask plus a global weight, each region gets its own mask scaled by its weight, and everything is normalized so every pixel sums to one. It then patches attention so each region's conditioning tokens are mixed into the keys/values only where that region's mask says so - the pixels inside the girl-on-the-left mask attend to the red-hair prompt, the pixels on the right attend to the blue-hair prompt, and the blend is controlled per-pixel. The implementation is a GPL-3.0 port of the cgem156-ComfyUI / sd-forge-couple approach, which is the well-traveled lineage of this technique.

The inputs that matter

• model - the MODEL to patch. The output is a clone with attention patched; your original loader stays untouched.
• base_prompt - a CONDITIONING for the whole scene. Keep it generic ("two people in a park"); the specifics live in the regions.
• global_prompt_weight - FLOAT, default 0.3, tooltip "Base prompt strength." The base prompt is meant to be a light scaffold, not the star - that's why the default is low.
• regions - ATTENTION_COUPLE_REGION, accepts a single region or a bundled list (from DuckAttentionCoupleRegion / DuckAttentionCoupleRegions).
• width / height - the generation resolution, in multiples of 8. The masks get interpolated to this size, and it must match your actual latent size.

Output: model, the patched clone - wire it into your KSampler in place of the original.

How to actually use it

Build the workflow forward: DuckAttentionCoupleRegion nodes each encode one region's prompt with a mask and weight, bundle them through DuckAttentionCoupleRegions, feed that plus a base-prompt conditioning into this node, and run your sampler on the patched model. The setup time is real - masks have to be painted or derived - so this is for compositions that need it, not everyday singles. When it's needed, it's the difference between a usable two-character scene and a smeared mess.

Install

Part of duckcomfy personal nodes. ComfyUI Manager → search "duckcomfy personal nodes", or:

cd ComfyUI/custom_nodes
git clone https://github.com/duckcomfy/duckcomfy_personal_nodes

Restart ComfyUI. No pip dependencies, no model downloads.

Gotchas

Three to know before you run. First, the mask-union assert: every pixel of the canvas must be covered by some mask, or the node errors with "areas that are zero in all masks" - leave gaps and it won't run. Second, size matters: width/height must match the latent you generate at, and region masks that are far off from image resolution produce the classic tensor-size-mismatch crash people hit with this technique. Third, the balance is everything: start with a light global_prompt_weight and adjust per-region weights to rebalance features, rather than cranking the base prompt. And a fair warning - the technique is CLIP-era; on LLM-encoded checkpoints the architecture assumptions may not hold the same way, so it's most reliable on SD 1.5 / SDXL-lineage models.