Save Mask Sequence

This is the least glamorous node in the H3 Relay pack and the one I ended up using most. It writes a mask sequence to an .npz file in ComfyUI's output directory, so that the mask you hand-fixed at great expense survives the next thirty renders.

No graph output, no preview. It's an output node: it runs, it writes, it's done.

What it writes

An .npz archive at output/<filename_prefix>.npz containing a single mask array - the first frames masks of the batch, binarized at 0.5 and stored compressed. The default filename_prefix is person-tail, which is a pretty good hint about the intended use: save the last few frames of a tracked mask, the part that goes off the rails, so a later run can pick up the corrected tail instead of retracking the whole clip.

It returns nothing, but it does publish a UI payload - path, SHA-256 of the written file, frame count - so you get a receipt you can check in the ComfyUI console. The hash matters: Load Reviewed Mask Sequence and the cache identity both key off content, so a saved file is reproducible rather than merely present.

Two validations, both short: it refuses to write outside the output directory (so no ../../ in your prefix), and it refuses if the batch has fewer masks than frames, rather than silently writing a shorter sequence than you asked for.

One thing it does not write: the present array that Load Reviewed Mask Sequence checks for unreviewed frames. So a file saved here loads cleanly - it's a reviewed export by construction. Just make sure you actually reviewed it, because nothing downstream can tell the difference.

Inputs and outputs

Required: masks - a full-timeline MASK, typically your expanded/padded sequence or the raw tracked one; filename_prefix - a string, subfolders allowed (review/person-mask writes into output/review/); and frames - how many of the leading masks to save. Minimum 1.

That frames widget is the bit people skip over. The node has no notion of "start here" - it takes the head of the batch. If you want the tail, you need to slice the mask before it gets here (or set frames to your full source count and fix frames in place). It's a blunt tool; the pack's own defaults assume you're saving a full reviewed sequence and re-loading it whole.

Zero outputs. Wire nothing from it. It only needs to be in the graph, executing after your mask chain.

Install

Manager → H3 Relay → restart, or:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/akatz-ai/h3-relay.git

Needs numpy - undeclared by the pack but nearly always present in a ComfyUI environment. No GPU, no models, no ffmpeg. ComfyUI 0.37.0+.

Where people get burned

Output outside output directory - you put a leading slash or a .. in the prefix. Prefixes are relative to output/, and a path like /home/me/masks/person is going to be rejected rather than doing what you obviously meant. Annoying the first time, entirely correct.

Insufficient mask frames means your batch is shorter than frames. This almost always means you wired the unpadded source count somewhere upstream and the mask batch came out a few frames short of what you asked for - check source_frames, not h3_length, in your mask chain.

The bigger design gotcha: saved masks are pinned to a resolution and a source timeline. Upscale your source, retime it, or change the crop, and the file is useless - Load Reviewed Mask Sequence will try to nearest-resize it, which is better than nothing and worse than retracking. Save masks per source version, with a prefix that says which one.