MiniMax H3 RAFT Mask Propagation / 光流遮罩传播 (Advanced)

If you've ever hand-masked a face in one frame of a video and wished the mask would just follow the person for the rest of the shot, this is that wish, built properly. It takes one reviewed person or object mask on a keyframe and propagates it through the whole shot using bidirectional RAFT optical flow - forward and backward - with forward-backward confidence checks. The output is a mask for every frame, so you can feed it into face refine, skin finish, or targeted inpainting without drawing dozens of masks by hand.

The two guardrails in its design are worth knowing before you use it, because they're exactly where naive mask-tracking tools fail:

• It stops at detected cuts. When RAFT's flow confidence collapses (a hard edit), propagation halts. No mask bleeding across a cut into an unrelated shot.
• It never assigns identity automatically. You tell it who/what to track by providing the mask. It won't decide "oh this is a person, track all people." If you want two identities tracked, you run the node once per identity. The README says it plainly: don't treat color trajectories as identity.

The inputs that matter

• frames - your decoded shot. keyframe_masks - one or more masks, batched. keyframe_indices - the 0-based frame numbers those masks belong to, as comma-separated text (default "0", meaning the first frame). The count must equal the MASK batch; the tooltip says so explicitly.
• model_name / model_type - the RAFT weights from models/optical_flow (raft_small default, raft_large available). model_type must match the actual architecture - the pack won't block you by filename, which is friendly, but it also means you're responsible for matching them.
• minimum_confidence (default 0.08) - how sure the forward-backward flow must be before a frame's mask region is trusted. Lower it and the mask crawls into uncertain areas; raise it and it shrinks.
• consistency_threshold (default 2.0) - the per-pixel consistency gate.
• extend_edges (default on) - grows the mask slightly so you don't lose the subject's outline to flow drift. Turn it off if you need pixel-exact edges.
• scene_cut_threshold (default 0.2) - the cut detector's sensitivity, same idea as the motion audit node.

Outputs: propagated_masks (one per frame), confidence_masks (so you can see where the propagation is unsure), a preview image, and report_json.

The workflow it belongs to

This node's natural home is the pack's 07-motion-detail flow: run the RAFT motion audit first to find the cuts, then run this once per identity with your reviewed keyframe mask. Long occlusions and re-entries need fresh anchor points - the README is explicit that after a long occlusion or a person re-entering frame you must add new anchors rather than expecting the mask to magically resume.

Install

Same pack, same routine:

cd ComfyUI/custom_nodes
git clone https://github.com/T8mars/comfyui-minimax-h3-audio-T8.git minimax-h3-audio-T8

or ComfyUI Manager → "MiniMax H3 Audio T8" → restart. Update ComfyUI itself first. The RAFT model goes in ComfyUI/models/optical_flow/ - without it the model_name dropdown will be empty.