Load Mask Video (FFMPEGA)

If you've used SAM3 to mask anything in a video, you know the sting: every single queue, it re-segments the whole clip. Text prompt, ~3.5 GB model, VRAM allocated, frames tracked, and it produces the identical mask it produced ten runs ago while you were only iterating on the sampler settings. Load Mask Video is the escape hatch. It reads a pre-generated black-and-white mask video and hands it downstream as a MASK tensor, so you segment once and reuse it forever.

What it is, mechanically

One input, one output, and no cleverness in between. You pick a mask video, it decodes frame by frame with OpenCV into a MASK tensor of shape (N, H, W), white = masked area. That tensor plugs into anything that takes a MASK - the pack's compositing paths, MatAnyone2 for video matting, an inpaint pass, or the mask pass-through on several other FFMPEGA nodes.

The memory cost is close to nothing; it decodes on demand rather than loading the whole thing into VRAM the way a segmentation model would.

The one input, and the gotcha

mask_video is a dropdown, not a path field. It's populated from ComfyUI's input directory - ComfyUI/input/ - filtered to files ComfyUI recognises as video. So the workflow is: save your SAM3 mask output to a video (the pack's AI masking modes do this), then get that file into ComfyUI/input/ before it will show up in the list. If your dropdown is empty, that's why, not a bug. Copy it in:

cp /path/to/your/mask.mp4 /path/to/ComfyUI/input/

Then refresh the node's widget list. Same convention as ComfyUI's core Load Video / Load Image nodes, and the same convention traps people every time.

Why you'd bother

SAM is what this ecosystem reaches for when it needs to mask a named object rather than cut the foreground out of a frame - and SAM 3 made that explode because a short noun phrase returns masks for every matching instance at once, which folded the old GroundingDINO-plus-SAM pipeline into one model. The trade is that it's a heavyweight model with a memory cost, and it is deterministic. Re-running it to get the same answer is pure waste.

That matters more in video than in stills, because video is where you iterate. You'll queue a dozen variations of a composite or a matte, and the mask is the one variable that never changes. Cache it, load it, move on. It's also the honest way to use a mask you made by hand in another tool - a rotoscope, a rough paint pass, anything that exports a B/W video.

And if you're wondering about mask quality rather than masking speed: hard masks are the right tool for compositing a solid object; genuinely semi-transparent material (hair, veils, glass, smoke) is matting territory, where a model predicts fractional alpha instead of a binary label. This node just moves whatever you give it - it won't upgrade a hard mask into a soft matte.

Install

ComfyUI Manager → search ComfyUI-FFMPEGA → Install, or:

cd ComfyUI/custom_nodes
git clone https://github.com/AEmotionStudio/ComfyUI-FFMPEGA.git
pip install -r ComfyUI-FFMPEGA/requirements.txt

Restart. No model downloads for this node - you're supplying the mask. The segmentation side of the pack (SAM3 / SAM 3.1, auto_mask, the sam3_masking mode) downloads its own models on first use, and the pack's install script pulls SAM3 with --no-deps from a pinned commit specifically so an upstream push can't change what you install. If you only ever load masks with this node, you don't need any of that.

Where people get burned

Frame count mismatch. The mask tensor has as many frames as the mask video. Feed a 200-frame mask alongside an 81-frame generation and one of them is going to be trimmed or error - keep the mask video's frame count and dimensions matched to the clip it belongs to.

Wrong polarity. White means masked. If you saved a mask where the subject is black on white background, everything downstream is inverted and you'll spend twenty minutes blaming the compositor.

Resolution, not just count. The mask is decoded at the video's own resolution. If your generation runs at a different size, resize the mask or use the resize block on whatever consumes it - a silently stretched matte shows up as a fringe along the edges long before you notice the source was 1920×1080 against a 832×480 render.