ComfyUI‑H3‑FaceRefine

What it is

• A collection of custom nodes for ComfyUI that improve tiny faces in videos generated with the MiniMax H3 diffusion model.
• The nodes detect a face on each frame, crop it, let MiniMax H3 re‑generate a higher‑quality version, and then stitch the result back into the original video.

Why it matters

• MiniMax H3 struggles when a head occupies only a few dozen pixels, even at 720p+. The problem is not resolution but the tiny face size in the input.
• By feeding the model a cropped, face‑filled canvas, the diffusion model can render much sharper, more detailed faces.

Key components

Node	Role
H3 Face Track + Crop	Detects faces, tracks them across frames, crops to a fixed‑size canvas, and outputs the crop and tracking data.
H3 Load Video + Face Select	Loads a video, runs a single detection pass, finds hard cuts (via PySceneDetect), and lets the user pick the subject face per shot.
H3 Per‑Frame Denoise	Applies a per‑frame denoising mask; now works on the model stream rather than just the latent.
MiniMaxH3ReferenceToVideo / H3 Inject Video Latent / H3 Face Stitch Back	Glue the refined face back into the original video, handling audio, VAE decoding, and compositing.

What’s new (v1.1.2 & v1.1.0)

• More robust tracking – when the target face disappears, the tracker no longer jumps to a different person; it interpolates the missing frames and reports the loss.
• Subject‑loss reporting – the node’s textual report now lists frame ranges where the face was not found.
• Fallback detector now uses the nearest body instead of the largest one.
• Auto‑select workflow – a new node (H3 Load Video + Face Select) that loads the video, detects all faces, detects hard cuts, and lets you manually pick the subject per shot.
• Cut detection – optional integration with PySceneDetect to split clips at hard cuts, ensuring face identity is reset per shot.
• Expanded select options – nine ways to choose a face (largest, smallest, left‑most, etc.) and a new frame_count output for wiring into MiniMax H3’s length.
• Canvas defaults – default canvas size raised to 768 px (MiniMax H3’s native short edge) with a minimum clamp of 512 px.

Installation & dependencies

1. Clone the repo into ComfyUI/custom_nodes/ and restart ComfyUI.
2. Required packages are installed from requirements.txt (ultralytics, scipy, insightface, scenedetect).
3. You must provide a face detector model (e.g., face_yolov8m.pt in models/ultralytics/bbox/). Optional models (anime face detectors, CLIP‑Vision, SAM, InsightFace) enhance specific features but are not mandatory.
4. For the example workflows you also need a few other custom‑node packs (VideoHelperSuite, Impact‑Pack, H3‑NativeAudioLock, optionally GGUF and SAM). The README lists exact URLs.

How to use (quick start)

• Open one of the two supplied workflow templates:
  1. Auto Select – lets the node pick a face automatically using a ranking rule (default: largest_face).
  2. Manual Select – opens a UI where you pick the desired face per shot.
• Provide the source video (via VHS_LoadVideoPath or H3 Load Video + Face Select).
• Supply reference images and the prompt you used for the original MiniMax H3 video.
• Queue the graph; the pipeline will:
  1. Detect and crop the face, enlarge it to the canvas.
  2. Run MiniMax H3 on the crop.
  3. Denoise (optional) and stitch the refined face back.
  4. Preserve the original audio and save the final video.

Who it’s for

• Artists and creators who already use MiniMax H3 for video generation and are frustrated by low‑detail faces.
• Anyone needing a drop‑in ComfyUI solution that works on existing H3 workflows without rewriting the whole pipeline.

Limitations

• The refinement works best when the face can be reliably tracked; rapid motion or frequent occlusions will cause interpolation artifacts.
• The node relies on an external face detector; quality depends on the chosen model (photo vs. anime).
• If scenedetect is missing, cut detection is disabled and the whole clip is treated as a single shot.

---

All information above is taken directly from the repository’s README.