H3 Face Track + Crop

H3 Face Track + Crop is the engine of the ComfyUI-H3-FaceRefine pack - the node that takes a video clip, finds the face on every frame, and hands MiniMax H3 a batch of crops where the face fills the canvas instead of being a few dozen pixels of smudge. Everything else in the pack hangs off what this node produces.

Why it exists: H3 renders faces poorly when the head occupies a small fraction of the frame. That's a property of head-size-in-frame, not of output resolution, so it persists at 720p and above. The fix is the same loop FaceDetailer made standard for stills - detect, crop, re-render at proper resolution, paste back - adapted to video. This node is the detect-and-crop half, and it's where all the temporal thinking happens.

How it works

Per frame, a YOLO face detector (face_yolov8m.pt by default, the same Bingsu/adetailer weights ADetailer and Impact Pack use) finds the face. Frames where detection fails get their gaps filled by interpolation, and the crop trajectory is then smoothed with a gaussian window - because a crop box that shivers frame-to-frame makes the refined face boil, even when the original subject sat still. Each crop is sized so the face holds a constant fraction, then everything is resized to one canvas size, since H3 generates a single fixed WxH for a whole sequence.

Two optional inputs make it smarter. Give it an identity_reference image and it'll pick the subject by face identity (via InsightFace buffalo_l embeddings) instead of by size - the difference between tracking your person through a crowd and latching onto whoever's briefly biggest. And a fallback_detector (a person/body model) supplies a real head position on frames where the face detector finds nothing, rather than blindly interpolating.

The inputs that actually matter

• images - your clip from the video loader.
• detector - face_yolov8m.pt is the good default.
• confidence (0.35) - lower catches more profiles, at the cost of false positives.
• crop_factor (2.5) - crop side as a multiple of face height; 2.0–3.0 is the useful range. Bigger gives the seam more context to land in, but less magnification.
• canvas_mode - auto_capped_768 is the sane default: sizes the canvas from the largest crop, clamped to 768 (H3's native short edge, and a sensible VRAM ceiling). manual uses the two values below; auto_no_downscale never shrinks a crop but can get expensive on clips with close-ups.
• smooth_window (21) / size_smooth_window (51) - raise the first if the box shivers, and note the second is deliberately bigger: size jitter makes the crop breathe, which reads as shimmer.

Outputs - and one you must not skip

• crops → H3 Inject Video Latent's images (and the SAM mask node).
• transform → the spine of the whole pack: H3 Face Stitch Back, H3 Per-Frame Denoise and H3 Face Mask (SAM) all need it.
• preview - a debug view of the tracked boxes.
• report - detection stats; watch for magnification < 1.0x, which means a crop is being downscaled and real detail discarded. Raise the canvas, or skip clips that are close-ups throughout.
• canvas_w / canvas_h → must be wired to the H3 node's width/height. In the auto modes the tracker chooses the size; if the H3 node disagrees, the latent shapes differ and injection refuses.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/Carasibana/ComfyUI-H3-FaceRefine.git

Restart, and the nodes appear under MiniMax H3/Face Refine (ComfyUI Manager finds the pack by title too). ultralytics, scipy and insightface auto-install. The one model you must supply yourself is the face detector, face_yolov8m.pt, dropped in models/ultralytics/bbox/. Everything else - the H3 diffusion model, text encoder, VAEs - you already have if you're generating H3 video.

One onnxruntime gotcha worth knowing before identity tracking: insightface needs it, and the pack deliberately pins no variant. Install onnxruntime-gpu alongside an existing CPU onnxruntime and the CPU package shadows it, CUDAExecutionProvider disappears, and identity matching silently runs on CPU. Check with python -c "import onnxruntime; print(onnxruntime.get_available_providers())".

For multiple people in one shot: run the pipeline once per subject, each with that person's identity_reference and their own refs on the H3 node, then chain them - feed run 1's stitched output in as run 2's base_images. The composites accumulate.