Minimax_H3_Face_Cut

Small faces in video generation come out smeared, and no checkpoint fix exists - a face that occupies 60 pixels of a 960-wide frame has nowhere to spend latent budget. The standard answer is the detailing loop: detect, crop, upscale, re-render, paste back. Minimax_H3_Face_Cut is the detect-and-crop half, built for H3's chunked long-video output rather than for a single still.

You'd reach for it when you've got a finished H3 clip - long, chunked, and mostly good - whose faces are the weak part. It is step one of three: Cut → Face_Resample → Face_Blend. It doesn't repaint anything. It hands the other two nodes something they can work with.

How it works

Three passes, in order, and the order is the point.

Shot detection first. PySceneDetect (content detector, pure CPU, no model) cuts the video into shots. Faces get cropped per shot, not per frame, so the crop window doesn't teleport when the camera cuts. If scenedetect isn't installed, the node warns and degrades to running detection without shot segmentation rather than erroring - a dependency that fails soft.

YOLO detection second. A YOLO face model boxes every face in every frame, batched. Detections in tracking gaps are folded back into existing tracks before new identities are considered, which is what stops two people crossing from shattering one identity into three.

Optional identity tracking third. With sec_model set to SeC-4B weights, the bundled engine does multi-person identity arbitration on pixel masks (boxes as a fallback), then bridges residual gaps by in-track interpolation. With sec_model on None you get single-face mode: the largest face per frame, no mask, no tracking.

Then each face gets a window: expanded by expand percent, smoothed across frames, cropped, and upscaled to a uniform res × res square. That uniformity is what lets the next two nodes treat a whole video as a stack of rows instead of a special case per frame.

Inputs that matter

Required and worth understanding:

• face_model - the YOLO weights, from ComfyUI/models/elementEasy/. Nothing selected means it errors out immediately. Accepts .pt/.pth/.onnx/.engine/.torchscript.
• vae - only used in latent mode. If you wire images (recommended), it's ignored entirely.
• res (512) and expand (20) - the crop canvas size and the margin around the detected box. Bigger expand gives the model context to keep the face consistent; too big and you're resampling hair and wall for no reason.
• yolo_threshold (0.3) - lower it if faces are being missed.
• skip_ratio (0.8) - a face already at least this fraction of res is left alone and produces no output row. Sensible default; it's why crop_images can have fewer rows than frames.
• upscale_model - optional SR from ComfyUI/models/upscale_models/. Use an ESRGAN/RealESRGAN-type image upscaler; face-restoration models (GFPGAN, CodeFormer) are the wrong tool here, since Face_Resample is doing the restoration. Faces under 192px get one SR pass, then a bicubic resize to exact size.
• sec_model / sec_threshold / max_identities - the identity-tracking trio. None = single face.

The two you'll tune for your card are unload_main_models (on, and you want it on with 12–16GB - it moves H3/VAE/CLIP out of VRAM before the crop/SR stage, and SR models load via spandrel outside ComfyUI's scheduler, so a resident main model will push you over) and sr_batch (4 at 16GB, 8–16 at 24GB+; it changes speed and VRAM peak, never results).

Outputs: crop_images (uniform crops, all frames kept) → Face_Resample. face_pack (the geometry ledger) → Face_Resample and Face_Blend. masks → Face_Blend directly, bypassing Resample. shot_info → the parameter node only, never into a geometry port. identity_refs → eyeball it before running Resample, because a wrong anchor means the wrong identity gets repaired.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/supElement/ComfyUI_MinimaxH3_AutoContext.git
cd ComfyUI_MinimaxH3_AutoContext
pip install -r requirements.txt

Manager route: search ComfyUI_MinimaxH3_AutoContext. Then put models where the node looks - YOLO into models/elementEasy/, SeC-4B (fp16 recommended) into models/sams/, SR into models/upscale_models/ - and restart so the dropdowns refresh. The author's model downloads live at huggingface.co/cglearned/Minimax_H3_Face_Cut.

Two dependencies the README doesn't spell out. The requirements file ships scenedetect but not ultralytics, and the YOLO detector imports it lazily at runtime - so Face_Cut installs cleanly and then dies with an ImportError on first run until you pip install ultralytics. It's AGPL-3.0, which matters if you're shipping commercially. The bundled SeC engine also wants transformers>=4.49 (Qwen2.5-VL support), which the requirements file leaves to you.

Common issues

A sudden slowdown with no OOM on a 16GB card. Windows spills VRAM overflow into "shared GPU memory" silently. Keep unload_main_models on, drop sr_batch to 2.

SR failed to load. It falls back to lanczos automatically. If you're getting colour blotches on small faces, swap to a RealESRGAN_x4plus-type model; if they persist, they're coming from VAE round-trips downstream - lower the step count.

UNCOVERED warning. No face in that frame range at all; it passes through untouched. If that's wrong, yolo_threshold is too high.

Masks all zero. Normal in single-face mode. In multi-identity mode, check the SeC log lines above.

Changed the model, VAE, SeC weights or the code and nothing updated. Tick clear_cache, or delete ComfyUI/output/cache/node_<node id>/. clear_cache only clears this node's own directory - Face_Resample invalidates its crop-row cache on content hash automatically, but node-id changes mean deleting each directory by hand.