Gift Mask Check Frames | 遮罩检查帧

The smallest node in the pack's matting chain, and the one that decides whether the chain self-corrects. It takes one shot's frames, picks a sparse set of them, and returns those frames plus an explicit list of their frame numbers. That's the whole node.

Why it exists: temporal matting models drift. A mask that starts perfect gradually loses the edge of someone's hair, or swallows a bit of background, and nothing inside the model notices. A fresh segmentation mask on a chosen frame is something that notices - if you compare the two at deliberate points. This is how you choose the points.

How it works

Given images for a single shot and an interval, it builds the index list 0, interval, 2*interval, … and always appends the shot's last frame if it isn't already there. The frames come back as a batch; the index list comes back as a JSON string.

Two details are load-bearing. The indices are shot-local, so the list always starts at 0 - the matting node validates exactly that. And the final frame is always included, so drift that accumulates toward the end of a shot gets caught at its worst point instead of surfacing on the next shot's first frame.

At the default interval=12, a 124-frame shot yields twelve check frames: 0 through 120, plus 123. Each costs a segmentation pass, and each is a possible reset point downstream - where a mismatch triggers a re-initialization, a warmup and a backward correction pass. So interval is a cost dial pulling on both ends of the chain at once.

Inputs and outputs

Inputs are images and interval (1–240, default 12), and that's it. It's per-shot by design: wire it to GiftAutoShotSplit's shots output, not to raw video frames.

check_frames is a batch, so the next node sees a plain IMAGE with N frames - no list semantics to trip over. It goes into a segmenter; in the shipped example that's ComfyUI-RMBG set to INSPYRENET. RMBG-2.0 is equally valid, and the author's docs are explicit that InSPyReNet is an example choice rather than a universal best pick. The masks that come back are what GiftAdaptiveMatting compares its own propagation against.

check_indices, the JSON string, is the part beginners break. It has to travel as a wire into GiftAdaptiveMatting's check_indices input, because the mask batch and the index list are validated as a matched pair: same count, every index inside the shot. Retype the numbers, or route the frames through anything that drops one, and you get a validation error instead of a subtly wrong matte.

Install

Nothing extra - it ships with the pack:

cd ComfyUI/custom_nodes
git clone https://github.com/lingziwyh/ComfyUI-GiftHelperSuite.git

Or install ComfyUI-GiftHelperSuite from Manager and restart. This node downloads no weights and imports nothing exotic; the models arrive with whatever segmenter you put after it. You do need that segmenter installed - ComfyUI-RMBG for InSPyReNet or RMBG-2.0 - plus VideoHelperSuite upstream, in the same Python that runs ComfyUI.

Common issues

"One full-resolution check mask is required for each check index." The mask batch and the index list no longer line up, or the masks came back at a different resolution than the video. This is the chain's number one failure and it's almost always a segmenter that resized its output, or a stray node in between that changed the frame count. Keep the mask path dumb: check frames → segmenter → matting node.

"check_indices must start at 0 and contain increasing frame indices within this shot." You fed this node the whole video while the matting node received per-shot frames, or something upstream merged shots. check_frames belongs on one shot.

The render takes forever and it's all segmenter time. Each check frame is a separate inference. Doubling interval roughly halves the cost and halves your correction chances. There's no universal answer - a locked-off talking-head shot needs far fewer checks than a scene where someone walks behind the furniture.

You can see the correction happen. A reset that fires and gets backfilled can still be perceptible on fast motion. Raise disagreement_threshold, or lower interval so the backfill has more anchors. Tune in that order, and read the correction_report string off the matting node rather than guessing.

The subject is still missed at the end of a shot. The ceiling is the segmentation model at the check frames: MatAnyone2 propagates what it's given and won't conjure up an object the segmenter never saw. If that's what's breaking, swap the segmenter - InSPyReNet and BiRefNet disagree on exactly this kind of input - before you touch interval.

One housekeeping note that isn't about this node at all: after switching source videos, set Video Combine's frame_rate to match and leave the loader's force_rate=0. Mismatched frame rates are the most common "the matting looks wrong" report that isn't about matting at all.