🐧 Restore Video Crop Frames

The easy half of video face work is cropping every frame around the face. The hard half is putting the processed crops back onto the moving background so the result doesn't flicker, seam, or blow up your VRAM. This node is that hard half. It's the back end of the 🐧 SuperNodes video crop-restore pair, consuming the metadata from Get Video Crop Frames and compositing each processed crop back onto its background frame, with proper blending and chunked GPU processing.

How it works

Core inputs: background_frames (what you composite onto - it defines the output size and coordinate space), cropped_frames (your processed batch), and restore_info (the metadata from Get Video Crop Frames). Then the blending decision:

• masks (optional) - per-frame blend masks where mask value is the paste alpha. So feather the mask itself to control edge softness - the node doesn't feather masks for you. Coordinate space is auto-detected by size: if a mask's H×W matches the crops or the recorded original crop size (including the cropped_masks output of Get Video Crop Frames, even if you upscaled the crops in between), it's treated as crop-space and resized with the crop; if it matches the background, it's used in place. Anything else is an error. Connecting masks overrides the feather controls entirely.
• feather_bbox - feather radius in pixels for the fallback path when masks aren't connected. 0 = hard edge.
• feather_mode - where that feather falls: inner (fades inside the bbox), outer (fades past it - needs crop padding to have content there), mid (straddles the edge).
• scale_method - interpolation for resizing crops and crop-space masks (lanczos, bicubic, etc.).

Mechanically: it reads each frame's recorded crop box and true bbox from restore_info, maps them into background space (the scale factors handle a background that's been upscaled since - say, the whole video got 2×'d), resizes each crop to its target slot, builds the alpha ramp from your masks or a Chebyshev-distance feather, and blends. Frames with no detection pass through untouched. The work is processed in VRAM-bounded chunks - the chunk size is computed from a ~4GB budget that also respects ComfyUI's reported free memory - so a long clip composites in passes instead of one giant tensor.

When you'd reach for it

• Face swap / face enhance / region inpaint on video, right after Get Video Crop Frames and whatever you did to the crops in between.

Install

ComfyUI Manager, search "ComfyUI-SuperNodes", or:

cd ComfyUI/custom_nodes
git clone https://github.com/sonnybox/ComfyUI-SuperNodes

Restart ComfyUI. No model downloads. The pack's only extra Python dependency is matplotlib (Sigmas Graph only). This pack is written against ComfyUI's newer extension API, so keep ComfyUI updated or the nodes won't register.

Gotchas

• Mask count must be at least the restored frame count; extras are trimmed, but too few is an error. If you're hand-building masks, get the batch size right.
• Wrong mask size = hard error, on purpose. The size-based auto-detection is strict so you don't silently composite garbage. If you're getting "masks size must match" errors, check whether you meant crop-space or background-space.
• feather_bbox/feather_mode are ignored when masks are connected. People set a nice feather, connect masks, and wonder why nothing changed - that's the documented behavior, not a bug.
• outer feathering needs padding from the crop stage to have anything to fade into. No padding, no outer feather.

Used properly - masks from Get Video Crop Frames, feathered - this produces blends that hold up on moving video, and the chunking means a 300-frame clip won't eat your entire GPU in one allocation. It's the most engineering-heavy node in the pack and it shows.