SAM3 Propagate

This is where SAM3 video actually earns its keep. You seeded a target on one frame with SAM3 Video Segmentation; this node takes that state and follows the object through the whole clip, spitting out a mask for every frame. That's the thing you can't do with a still-image segmenter - SAM3 keeps the object's identity consistent as it moves, turns, or gets partly hidden, so you end up with a temporally stable mask track instead of a hundred independent guesses that flicker.

You'd use it for rotoscoping, masking a subject for video inpainting or relighting, or generating the per-frame masks that video object-removal pipelines need. It's the propagation half of a two-node dance: Video Segmentation says what, Propagate does the tracking, and SAM3 Video Output turns the result into usable images and masks.

How it works

Propagation walks the timeline from your seed frame, using SAM3's memory of the target to predict its mask on each successive frame. The direction control decides which way it walks - forward from the seed, backward, or both - which matters because your clearest reference frame isn't always frame zero. Seed the object mid-clip where it's most visible, then propagate both ways to cover the whole thing.

The inputs and outputs that matter

Two required:

• sam3_model - the SAM3_MODEL from LoadSAM3Model. Propagation needs the actual model, not just the state.
• video_state (SAM3_VIDEO_STATE) - the seeded state from SAM3 Video Segmentation.

The optionals that matter:

• direction (default forward; also backward, both) - which way to track from the seed frame.
• start_frame (default 0) / end_frame (default -1 = to the end) - limit propagation to a slice of the clip instead of the whole thing.
• offload_model (default off) - free VRAM after the run.

Outputs: masks (SAM3_VIDEO_MASKS) - the per-frame mask track; scores (SAM3_VIDEO_SCORES) - per-frame confidence; and video_state (SAM3_VIDEO_STATE) - the updated state passed through, so you can chain another operation. The masks and video_state both feed SAM3 Video Output, which is what converts them into standard MASK/IMAGE.

How to install it

Comes with the pack. Manager: search SAM3, install the top version. Manual:

cd ComfyUI/custom_nodes
git clone https://github.com/PozzettiAndrea/ComfyUI-SAM3.git
cd ComfyUI-SAM3
pip install -r requirements.txt --upgrade
python install.py

then restart, with sam3.pt in ComfyUI/models/sam3/ (installed by install.py). The README mentions an experimental comfy-env/pixi one-click path.

Common issues & troubleshooting

The mask drifts or loses the object partway. Occlusion or fast motion threw off the track. Re-seed on a frame where the object is bigger and clearer, and consider propagating both directions from a mid-clip seed rather than forcing a single forward pass from a weak first frame.

Only half the clip got masked. Check start_frame / end_frame - if end_frame is set short, propagation stops there. Set it to -1 for the full timeline. And if direction is forward but your seed is late in the clip, everything before it stays unmasked; use both.

Out of memory on a long video. Propagation holds mask state across frames. Trim or downscale the clip, or use start_frame/end_frame to process it in slices. Turning on offload_model helps free the GPU once the track is done.

Outputs look like odd custom types. They are - SAM3_VIDEO_MASKS/SCORES/STATE only make sense to other SAM3 nodes. Send them to SAM3 Video Output to get back normal MASK and IMAGE.