Video Mask Editor (视频遮罩修复编辑器)

If you've tracked a subject through a clip with SAM 2 or SAM 3, you know the drill. Frames 1 through 63 are immaculate. Frame 64, the mask just… isn't there. And when that mask feeds a VACE inpaint pass, a Wan Animate run, or a subject-crop node, one garbage frame wrecks the whole take - the crop jumps, the inpaint smears, and you re-render three minutes of video to find out.

VideoMaskEditor exists for that moment. It sits between your segmentation output and whatever consumes the mask, stops the graph dead so you can paint over the bad frames by hand, then lets the diffusion pass run on the fixed version.

What it actually is

It's a mask editor, not a segmentation model. No API, no key, no weights to download - just a canvas UI and a handful of HTTP routes the pack registers on ComfyUI's own server.

The pack's framing is narrow and honest: segmentation models flicker, and hand-fixing beats re-tracking. Promptable masking has gotten very good - SAM 3 will mask a named object across a whole clip - but nothing in this stack is reliable across every frame, and the failure is rarely subtle.

How the pause works

When the node runs, it normalizes your tensors (squeezing 4D masks, repeating a single mask across the batch, bilinearly resizing anything that doesn't match the image resolution), then fingerprints the video from shape plus a sparse pixel sample. That hash isolates your edits per video, so swapping clips later doesn't drag the old session's masks along.

Then it scans for flicker: it sums each frame's mask area and flags any frame collapsing below 35% of its neighbours' average, with a second rule for near-zero masks. Crude, area-based, but it works - flagged frames get a ⚠️ on the timeline, so you jump straight to them instead of scrubbing.

In the default Interactive (Pause & Wait) mode the node blocks its Python thread and waits. Edits round-trip over HTTP and land on disk as one PNG per fixed frame under ComfyUI's temp directory, so nothing is lost if you close the tab. The editor opens from a button widget on the node; Continue releases the wait. Brush, eraser, magic wand, move-mask, feather, zoom - plus P and N to copy the previous or next frame's mask over the current one. That's the shortcut you'll actually live in, because a dropped frame almost always sits next to two good ones.

Inputs and outputs

Four inputs matter. images is the frame batch, masks is the mask batch - the tooltip says "SAM3 or another node's mask sequence", and it means anything that emits MASK. Wire both from the same source so frame n lines up with mask n.

mode has three settings, and the choice is real:

• Interactive (Pause & Wait) - default. Blocks until you save and continue.
• Use Edited or Passthrough - non-blocking; applies whatever edits are cached on disk and passes the rest through. This is the one for a re-run after you've already fixed things.
• Block Downstream - review only. Nothing after this node runs, which is the point.

feather_edges (0–64) Gaussian-blurs the output masks after editing - worth a couple of pixels if your downstream inpaint shows a hard seam, a bad idea on top of already-soft masks. reset_cache is the escape hatch: tick it to wipe this video's edits and fall back to the raw input masks.

Outputs are just masks and images - corrected batch, original frames - so you chain straight into your sampler or crop node.

Install

Manager first - search the pack name, restart. Manual is two lines:

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

The requirements are torch, torchvision, numpy, Pillow, aiohttp - all already present in a working ComfyUI install. Effectively a no-dependency node: no Triton, no model files, no downloads.

Where people get burned

The node is always-dirty by design: its IS_CHANGED carries a timestamp, so it re-executes on every queue and everything downstream re-runs. Nobody's caching a sampler behind it - that's the cost of a node that pauses.

Two more. The flicker detector flags area change, not badness - a fast cut, a hand slipping out of frame, or a subject genuinely leaving the shot all get a ⚠️. Look before you "fix". And the node holds the whole batch as CPU tensors while paused, serving frames as JPEGs on demand, so a 120-frame 720p clip parks over a gigabyte in RAM. Long clips work, just be patient.

If you can't tell whether you're looking at your edits or the originals, that's what reset_cache and the editor's reset-all button are for.