Koolook Matte — Sampler

Koolook Matte Sampler is the actual matting engine in the Matte workflow. Feed it frames and rough masks plus the pipeline from the Loader, and it runs mask-guided one-step matting: 12 latent channels (4 noise + 4 VAE-encoded frame + 4 VAE-encoded guide mask), a single denoising step at timestep 1, CLIP cross-attention zeroed, then decode through SVD's temporal VAE and take luminance as the alpha. One step means fast. "One step" means it's the method's whole identity - it's not a sampler in the diffusion-iteration sense, despite the name.

The output is a MASK: full-frame alpha, black where there's no subject, white where there is, soft edges where the model thinks the subject ends. In the crop mode it's the crop-space matte (paste it back with Focus Stitch); run without the crop and it's full-frame directly.

The settings that matter

• pipeline - the KOOLOOK_MATTE_PIPELINE from the Loader. Wire it once.
• images and masks - your frames and the coarse guide masks. The masks are the "tell me roughly where the subject is" input; the model refines them.
• max_resolution - cap on resolution (default 1024). This plus the two modes below is your VRAM/quality dial.
• window_size - frames sent through the UNet per pass. This is the big VRAM lever: lower = far less VRAM, so you can raise max_resolution (e.g. 1440) on a 24GB card. 0 = whole clip in one pass (legacy behavior, and legacy VRAM needs).
• window_overlap - frames re-processed and blended at each window boundary so temporal continuity doesn't flicker where windows meet. Must be less than window_size. 0 disables the blending.
• crop_to_mask - process only the union bounding box of the masks (Sammie-style ROI). Far fewer pixels through the UNet, much faster, and max_resolution applies just to the subject. The output matte is pasted back with zero alpha outside. This is the one to keep on.
• crop_padding - margin around the mask box before cropping, so soft edges and motion don't clip.
• resize_mode - shortest_side (default): cap the shorter side at max_resolution, never upscale, keep the long axis at full detail - sharpest matte, more VRAM. longest_axis: force the longer side to the cap - lower VRAM, softer edges. Sharpness versus fit, your call.

Also on the node but usually left alone: seed (42), fps (7), motion_bucket_id (127), noise_aug_strength (0) - the SVD conditioning values, which have sane defaults and only matter if you're matching a specific pipeline.

How it fits

The full graph is Loader → Focus Crop → Sampler → Focus Stitch → full-frame mask. If you don't need the crop trick, you can run Loader → Sampler directly on full frames, but you'll pay the VRAM cost. The pack also has an OOM auto-backoff that drops resolution while preserving the temporal window - so it degrades gracefully instead of hard-crashing.

Install

Part of ComfyUI-Koolook (Manager Git URL https://github.com/malkuthro/ComfyUI-Koolook.git, or git clone into custom_nodes/), restart, find it under Koolook Matte. Depends on the Loader's diffusers + huggingface_hub and the downloaded SVD/VideoMaMa weights. Install the pack once - a second copy double-registers and corrupts the workflow store on every boot.

Common issues

• OOM - lower window_size first, then max_resolution or switch to longest_axis. The window is the dominant VRAM cost.
• Edges flicker across windows - window_overlap is 0. Set it to a few frames (default 2).
• Matte only covers a box - that's crop_to_mask working as designed; paste back via Focus Stitch. If you want full-frame, turn the crop off.