Donut Subject Mask Preview

What it actually is

This one confuses people because it doesn't behave like a node in a graph. It has no outputs at all - no IMAGE, no MASK, nothing to wire onward - and if you add it by hand from the node menu you'll mostly get a red error, not a picture.

It's the queued job behind Edit Studio's "Auto select subject" button. You choose Auto subject (or Prompt selection) as the mask mode on Reference B, hit auto-select, and the frontend queues this node to compute the soft foreground mask for that reference image. No Krea model is loaded and no generation runs - it's a masking job, not a sampling job. That's deliberate: it means you can get a subject cutout in a second or two instead of sitting through a full queue to find out whether the mask was any good. There's also an HTTP route that serves the finished mask PNG back into the UI, which is how the preview appears.

Worth knowing what's under it: ComfyUI's native BiRefNet nodes. BiRefNet is the segmentation network that displaced rembg's u2net for anything with a hard edge - hair, fur, mesh, semi-transparent fabric - and it's MIT-licensed and now ships in core. This node is a convenience layer over that, not a new segmentation model.

How it works

Two paths, chosen by model_name:

• Auto subject runs native LoadBackgroundRemovalModel + RemoveBackground on the reference and caches the result. The cache key is the image's content fingerprint plus the model's size/mtime, so re-queuing the same reference is instant.
• Prompt selection runs native SAM3_Detect with a text prompt and a detection threshold, using sam3.1_multiplex_fp16.safetensors out of models/checkpoints/. That path needs a prompt and needs SAM3 support in your core build.

Either way the result is written as a content-addressed 8-bit grayscale PNG under ComfyUI/user/donut/edit_subject_masks/ and handed back via the node's UI payload. The mask is a soft matte, which is the whole reason it's worth using over a hand-drawn one.

The inputs

From the node's schema, and this is the complete list:

• image_b (STRING) - the content-addressed reference id, the donutref:… handle Edit Studio publishes when you upload Reference B. This is why hand-wiring the node fails: it isn't a file path, and the reference has to already exist in Edit Studio's store.
• model_name (STRING, default birefnet.safetensors) - which segmentation model. The prompt-selection model name is the other valid value.
• request_id (STRING) - the frontend's request correlation id. You don't set this.
• mask_b_prompt (optional, multiline) - the thing you're selecting, e.g. hat. Only used by prompt selection.
• mask_b_threshold (optional, 0.01–1, default 0.5) - detection threshold for prompt selection. Raise it when you're catching too much; lower it when the object keeps getting missed.

Nothing comes out of the node. The mask lands in Edit Studio's Saved mask slot, where you can paint on it, then reuse it forever without a model.

Using it without fighting it

Don't build a graph around this. In Edit Studio, set Reference B's mask mode to Auto subject and press auto-select. Refine it in the painter if the edges need work. Then, once you're happy, switch the mode to Saved mask - that path needs no segmentation model, no weights and no GPU work on later runs.

If you'd rather supply your own mask, the External mask mode is where you plug in anything from Grounding/SAM or a YOLO node. One gotcha from the pack's own docs: it must be exactly one mask at Reference B's original width and height - not A's dimensions, not the cropped output size - and white keeps the subject. ComfyUI's Load Image alpha MASK may need inverting.

Installing the pack

Same as everything else in DonutNodes - Manager, search DonutNodes, or:

cd ComfyUI/custom_nodes
git clone https://github.com/DonutsDelivery/ComfyUI-DonutNodes.git donutnodes
cd donutnodes
python -m pip install -r requirements.txt

Use the Python interpreter that launches ComfyUI, restart, refresh.

The weights are the part people miss. Auto masking wants:

ComfyUI/models/background_removal/birefnet.safetensors

Prompt selection additionally wants sam3.1_multiplex_fp16.safetensors in models/checkpoints/. In the V5 workflow, picking the mask mode and hitting Download missing fetches the right BiRefNet file from a pinned Comfy-Org source with size and hash verification. The node itself never downloads anything.

Troubleshooting

• "Smart Mask needs native BiRefNet support. Update ComfyUI and restart." Your core build lacks LoadBackgroundRemovalModel / RemoveBackground. Update, don't hunt for a custom-node pack - it's core.
• "Prompt selection requires native SAM3 support" - same story for SAM3_Detect.
• FileNotFoundError on the model - the file is in the wrong folder. background_removal, not checkpoints, unless you're on the prompt path.
• "Reference B is too large for Smart Mask; use an image under 32 megapixels." Downscale the reference.
• The mask grabs more than one object. BiRefNet selects foreground, not a named subject - it will happily keep several people. That's exactly the case prompt selection or the manual painter exists for.