SAM3 Text Prompt to Seed Mask

The one annoying step in every SAM2Matting workflow is making the seed mask - you have to paint or generate a white blob on the exact frame you want to seed. This node is the shortcut: instead of painting, you type woman in red jacket, and SAM3's concept detection finds that subject on one frame and hands you the mask. It's the difference between opening a paint tool and typing a sentence.

What it needs

The hard requirement is that the model loader must be on the sam3 variant. SAM2.1 doesn't do text-guided concept detection, so if you feed this node a sam2.1_base_plus model it has nothing to work with. SAM3 is the current tier of Meta's Segment Anything line, and this is exactly the job its promptable concept segmentation was built for: a short noun phrase returns a mask for every matching instance in one pass, which is what collapsed the old GroundingDINO-plus-SAM two-model pipeline.

The inputs

• text_prompt - a short subject description, default person. Be specific enough to disambiguate: woman in red jacket beats person on a busy scene.
• frame_index - which frame SAM3 inspects. Pick one where the subject is clearly visible.
• confidence_threshold - drops detections below this score (default 0.5). Raise it if the node grabs the wrong thing.
• selection - highest_score uses the best single detection; combine_all merges every detection above the threshold. Use the latter when there are multiple instances you want as one mask.

The outputs and how you wire them

Four outputs come back, and two of them are the point:

• seed_mask - the white-foreground mask, wired into SAM2Matting Video's initial_mask.
• mask_frame - the matching frame index, wired into the same node's mask_frame. This is why you don't have to keep track of the frame yourself.
• preview - a checkerboard image showing the cutout on that frame. Look at it before running the full clip; it's your chance to catch a bad selection.
• top_score - the highest detection score, useful for judging whether your prompt actually nailed the subject.

The pack's sam3_text_prompt_video.json example workflow shows the full chain: load SAM3, prompt it, preview the single frame, then pass both outputs into temporal matting.

The gotchas

SAM3 requires CUDA, full stop - no CPU fallback. And the first prompt is noticeably slower than later ones, because the detector is cached in system RAM and swapped onto the GPU only while generating a seed mask, so it doesn't keep a second SAM3 vision backbone resident in VRAM. That's a deliberate trade that saves you memory at the cost of a slow cold start.

One more thing that's easy to trip on: the same license caveats that apply to the whole pack. SAM3 itself carries Meta's custom SAM License rather than the Apache 2.0 that SAM and SAM2 use, and the upstream SAM2Matting weights are non-commercial CC BY-NC-SA. Fine for personal work; read the licenses before you build anything you charge money for.