Jakkanna SCAIL-2 Validate Track

JakkannaSCAIL2TrackValidate is a pre-flight check for SCAIL-2 generation, and it exists because SCAIL-2 runs are expensive. On a mid-range card you're looking at minutes per clip - the KB's community numbers put a 14-second clip at ~19 minutes on a 5060 Ti - so discovering a broken mask track at frame 40 of sampling is a genuinely painful way to learn. This node finds that problem before the sampler ever starts.

What it does: it takes the SAM3_TRACK_DATA your SAM 3.1 node produced and verifies the track is actually usable. Three hard requirements, no negotiation:

• The track has exactly expected_frames frames. You tell it what the run should be - for the bundled workflows that's 81, SCAIL-2's native window - and it fails if the track disagrees.
• The track contains exactly one subject. SCAIL-2 is single-subject, and the node enforces it by refusing anything with more than one object in the packed masks.
• The reference_mask you connect is one nonempty subject sized to the source canvas, matching the track's recorded original size.

Then it measures the motion quality of that one subject and applies four thresholds, all floats with sane defaults:

• maximum_area_step_ratio (2.0) - how much the mask area may change between adjacent frames before it flags
• maximum_centroid_jump (0.15) - how far the mask's center may jump per frame
• minimum_adjacent_iou (0.1) - the floor for overlap between consecutive masks
• minimum_border_margin (0.005) - how close the subject may sit to the canvas edge

Anything that violates a threshold raises with a descriptive error - something like "track area changes by 3.4x between adjacent frames; limit is 2.0x" - instead of silently letting a smeared, flickering subject through to the sampler.

Outputs are modest: object_indices (a STRING holding the single subject's index, "0") and track_report (a JSON string). The report carries the resolved metrics - min and max area percent, the actual area ratio, centroid jump, IoU, border margin - plus a SHA-256 of the track masks. That report is exactly what the upstream JakkannaSCAIL2ProductionManifest node wants on its track_report input, and the hash is what lets the manifest spot a silently swapped track.

Inputs that matter: track_data (SAM3_TRACK_DATA), reference_mask (MASK), expected_frames (INT, forceInput), and the four thresholds. The defaults are fine for ordinary motion; the only reason to loosen them is genuinely fast or dramatic movement, and even then, nudge them one at a time and read the error messages - they tell you which threshold tripped.

Install: it's part of the Jakkanna pack - Manager, search "Jakkanna", or:

cd ComfyUI/custom_nodes
git clone https://github.com/teenu/ComfyUI-VNCCS-Utils-Maintained
cd ComfyUI-VNCCS-Utils-Maintained
pip install -r requirements.txt

Restart after, and don't run it in the same instance as the upstream vnccs-utils (duplicate node registrations will fight). The pack won't fetch SCAIL-2 or SAM 3.1 weights for you - those go in your models folders like normal.

The trap: beginners wire the reference mask from the wrong place and get a dimension mismatch that reads like a bug. It isn't - the mask has to live on the same canvas as the tracked video. Fix the mask source, not the node. And if you've hand-built a graph instead of the bundled workflow, this node is the cheap insurance between SAM 3.1 and your sampler. Leave it in.