SAM2Matting Streaming Options

This node does zero compute itself. It's a bag of settings - a single streaming_options output you plug into SAM2Matting Video Background (Streaming) to override its defaults. The honest headline is that you can leave it disconnected forever and get good results, because the defaults are chosen sensibly. But the moment your long render is slow, your temp disk is full, or your matte edges flicker, these are the knobs that fix it.

The inputs that matter

• cache_mode - how the streaming pipeline stores model-resolution frames on disk between stages. lossless_zstd (default) preserves the exact resized RGB with moderate disk use; jpeg_low_disk is the smallest cache but JPEG slightly changes the model input, which the tooltip flags as a quality trade; raw_fast skips compression entirely, fastest when you have temp disk to spare. Default stays unless disk is the bottleneck.
• worker_threads - CPU workers for frame prep, matte compression, and compositing. More helps until your CPU or disk saturates. It does not parallelize SAM inference, which stays sequential - this is the one thing people expect it to do and it can't.
• pipeline_depth - how many frames each bounded CPU stage keeps in flight. 8 is the recommendation. Higher hides CPU/disk latency but uses more RAM; the tooltip suggests dropping to 2–4 under memory pressure. It's a queue limit, not a batch size.
• video_encoder - auto tries NVIDIA NVENC first and falls back to CPU libx264 if NVENC can't start. You can also force either one explicitly. If you see NVENC fail in the logs, libx264 still gives you a correct result, just slower.
• output_fps - 0 keeps the source rate; a positive value drops or duplicates frames while preserving clip duration.
• crf - the H.264 quality target. Lower is better and bigger; 18 is the default. With NVENC it's mapped to NVENC's comparable constant-quality control.
• preserve_audio - transcodes the source audio into the result as AAC. Turn off for a silent output.
• verbose_log - reports stage progress, throughput, the actual compute device, cache sizes, and CUDA memory. It defaults to on, and that's the right call; the streaming node is a black box otherwise, and this log is how you'll diagnose any slowdown.

The one optional input, edge_stabilization, is the closest thing to a creative control here: it blends each alpha toward a three-frame temporal median to suppress one-frame matte-edge flicker. 0.35 is the gentle default. Bump it up if edges shimmer frame to frame; keep in mind high values can flatten very fast, thin, or translucent detail, so go easy on it.

When it earns its keep

Drag it in when a long render is RAM-bound (drop pipeline_depth), when temp disk is filling up (switch cache_mode), or when you want a specific encoder rather than trusting auto. Otherwise, don't clutter the graph. The streaming node's defaults are the same values baked into this node, so disconnecting it is a feature, not a shortcut. If you do wire it in, it's just a config object - no ordering or timing concerns, plug it in and rerun.