IAMCCS H3 Optional Face Detailer Router

Faces are where video models fall apart - H3 included. A dedicated face-detail pass can fix the mush, but a face-refine graph (track, crop, SAM mask, re-denoise the face region, stitch back) is expensive, and running it on every render when you don't need it is exactly the kind of VRAM waste this pack is built to avoid. The Face Detailer Router is the switch: it passes native frames straight through by default, and only pulls in the face-refined result when the Shotboard settings actually enable Face Detailer.

How it works

The node takes native_frames and native_audio plus two lazy inputs, face_detail_frames and face_detail_audio - the outputs of the pack's IAMCCS H3 Face Stitch node. Its check_lazy_status reads the Face Detailer settings from the shot plan (cine_linx): if the setting is off, it returns an empty list and the entire face-refine branch (which can contain detection, SAM, and a second H3 pass) never executes. Flip the setting on, and the router requests the face_detail_frames input, the branch runs, and the router hands the stitched frames out as its frames output, carrying the native audio (or the face branch's audio if it produced one).

The docstring lays out the four valid routes explicitly: native, native+face, native+upscale, and native+face+upscale. The router slots in before the upscale router, so the face pass happens on native resolution and the upscaler then treats the fixed faces as its input. That ordering matters - detail faces first, upscale after, and you don't re-mush the faces in the upscale.

Inputs and outputs

Required: cine_linx, native_frames, native_audio. Optional (and lazy): face_detail_frames, face_detail_audio. Outputs: frames, audio, and report - the report names which route was taken and, when enabled, the profile and whether a SAM mask was used.

Installing it

Part of IAMCCS-nodes (Manager, search "IAMCCS", or clone into custom_nodes). The face branch itself depends on the pack's face nodes (Face Track + Crop, Face Stitch, Face Mask SAM), which are in the same pack - but SAM masking needs a SAM model and the usual detection stack, so install those before expecting the refined branch to work.

Gotchas

The lazy contract is the trap. If Face Detailer is enabled in settings but face_detail_frames isn't connected, the node raises a ValueError at selection time - it will not silently give you native frames. That's deliberate: the alternative is an expensive face branch that runs every time but whose output is ignored. If you toggle the setting and see that error, connect Face Stitch. And if you're wondering why faces look untouched despite the branch being on the canvas - check report: "Face Detailer router: native H3" means the setting is off, whatever you wired.