SSR Encode Query

EncodeSSRQuery ("SSR Encode Query") is the brain of this pack. It takes a reference image, a sentence about what you want from it, and returns the thing every other node in the graph is waiting on: the SSR_EMBEDS that eventually steer your sampler. The one-line pitch - "the text query decides what gets copied from the image" - is the whole reason SSR exists, and this node is where that decision is made.

Why you'd reach for it

If you've used IP-Adapter, you know the drill: feed a reference image, get a global influence. SSR-Encoder (CVPR 2024, arXiv 2312.16272) is the "selective" upgrade. Same reference image, but your query text picks the subject. Load a photo of a woman wearing a wolf-fur coat and query "wolf, fur" - you get the fur's texture; query "woman" - you get the woman. The example workflow that ships with the pack does exactly this with two chained EncodeSSRQuery nodes, one at scale 0.5 and one at 0.4. That's the superpower: one reference, many interpretations, no finetuning.

How it works

The node runs your image through the CLIP vision encoder and grabs six intermediate layers (every fourth one, from index 3 onward) rather than just the final pooling vector. Then it encodes your query text with the CLIP text encoder. A small trained network called the aligner - the ssr_aligner you loaded - merges the text query against those six multi-scale image feature maps, cross-attending the text into each and concatenating the results. Out comes a subject embedding of 462 tokens (77 × 6). Downstream, SSR's trained attention layers treat those tokens as extra key/value context and add them, scaled, on top of normal text attention.

Inputs that matter

Most of them have sensible defaults, so a beginner only really sets three:

• positive (STRING, multiline) - your subject query, like wolf, fur. This is the "what to take from the image" instruction.
• positive_scale (FLOAT, default 0.4, range 0–10) - how hard the subject gets pulled in. 0.3–0.6 is the comfortable zone; much higher and the query starts to override your main prompt.
• image (IMAGE) - the reference. Feed it through an ImageScale set to ~512×512 first; the example workflow does, and it keeps the vision pass honest.

The rest you wire and mostly forget: clip (the CLIP text encoder, tooltip: "The CLIP model used for encoding the text"), clip_vision (the vision encoder), ssr_aligner (from LoadSSRAligner), negative and negative_scale (default 0 - off; a negative query only encodes if both the text and scale are set). The optional prev_ssr_embeds input is the chaining mechanism: run one EncodeSSRQuery, feed its output into the next node's prev_ssr_embeds, and you stack subjects (fur and woman). The output is SSR_EMBEDS, which goes to ApplySSR.

Installing

Manager: search "SSR Encoder" in the Custom Nodes Manager, install, restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/logtd/ComfyUI-SSREncoder

No pip step - no requirements.txt ships with the pack. You do need the model files in ComfyUI/models/ssr/: ssr_aligner.safetensors (~25MB) and ssr_attentions.safetensors (~73MB), both from huggingface.co/logtd/ssr_encoder. And critically, this node needs the right encoders: an SD 1.5 CLIP text encoder (wire it from the same checkpoint as your base model) and the stock clip_vision_large.safetensors (that's CLIP ViT-L/14, the file ComfyUI ships by default). The aligner's dimensions are hard-coded for this pair, so SDXL and Flux CLIPs won't fit - this is a strictly SD 1.5 tool.

Common issues

If nothing happens, the usual suspects are an empty query, a positive_scale of 0, or a missing ssr_attentions wire on the ApplySSR side (EncodeSSRQuery produces embeds fine but nothing consumes them). A dimension error at encode time means you've paired the wrong CLIP or vision encoder with the SD 1.5 aligner. And don't over-ask: the upstream authors themselves note the balance between selectivity and subject fidelity is delicate - a too-vague query ("person") gives you mush, a too-narrow one ("brown fur, 4k, studio light") fights your main prompt. Start at 0.4 and nudge.