MiniMax H3 Director FaceRefine

Why this node exists

MiniMax H3's director setup defaults to a 0.4MP canvas - 864×480. Fine for a wide shot, terrible for the face in it: a head occupying 60 pixels comes out a smear, because the latent has nowhere to spend detail. Stills solved this years ago - detect the face, crop it, re-render it bigger, paste it back. That's FaceDetailer and ADetailer.

Two reasons that recipe doesn't drop straight into H3. H3 generates picture and stereo audio as one joint latent, so a generic stills detailer has nothing sensible to say about it. And you're not fixing one image - you're fixing every segment of a timeline that's already been sampled, refined and stitched. MiniMaxH3DirectorFaceRefine wires into the Director's face_refine port, tracks one face through each finished segment, and gives it its own H3 sampling pass at 768px - after the Director Refine node, if that's connected too. Leave it unwired and nothing changes.

How it works

The classic detect-crop-render-paste loop, tuned for H3. A YOLO face detector runs on every decoded frame; on the first hit it locks onto one subject and follows the nearest box frame to frame. Detection gaps get interpolated and the trajectory is smoothed over 20–50 frames so the crop doesn't jitter.

Then the interesting part: the crop frames are encoded through the video VAE and injected into the video stream of an H3 joint AV latent, so audio stays attached. The segment's own reference images ride along as identity anchors, which keeps the refined face the same person. Frame counts round up to H3's 17k+5 grid (5, 22, 39, …). The result is composited back through a feather-blurred mask, with 12-frame fades at segment seams so the join doesn't pop.

One thing it doesn't do: it follows a single subject. The upstream implementation it adapts had identity picking and SAM; those are gone. Largest or most central face, one per segment - a two-hander doesn't get two passes.

The inputs that matter

The required block is split by three UI section headers - bd_grp_face_detect, bd_grp_face_sample, and the optional bd_grp_face_paste. Those are collapsible labels, not knobs.

detector is your face YOLO weight (face_yolov8m.pt by default) and it has to live in models/ultralytics/bbox/ - the same weight Impact Pack and ADetailer have used for years. confidence (0.35) is the detection threshold; lower catches more small and profile faces. crop_factor (2.5) is how much head-room you crop, 2.0–3.0 being the usable band.

canvas_mode plus canvas_width/canvas_height (both 768) are the quality dial. manual uses your numbers; auto_capped_768 sizes to the biggest tracked face with a 768 cap. It snaps to a multiple of 32 either way, which H3 requires. select → centre_most is usually the fix when the crop keeps drifting to the wrong person.

Sampling: denoise (0.40), steps (8), sampler (euler), scheduler (simple). Read that denoise tooltip before copying your FaceDetailer habits - the author is explicit that H3 does not want the usual 0.25. Wiring sigmas overrides all three.

Paste: paste_region (face_only is the default; full_crop pastes the whole rectangle and is how you get a visible square on someone's cheek), mask_dilation (16), feather (24, in final pixels), colour_match, blend. And seed_mode - inherit reuses the Director's seed, offset uses seed + 1 + segment number, so consecutive segments don't converge on the same face.

Output and wiring

One output: face_refine, type MMX_DIR_FACE_REFINE, into the Director's face_refine input. No model or VAE inputs here - it borrows the Director's at run time. Downstream, images is the stitched result; images_pre_face_refine is the pre-stitch video, but only when the Director's「输出修脸前」toggle is on. That's your before/after.

Installing it

FaceRefine ships inside the Director pack, so installing the pack installs this node.

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

Or in ComfyUI Manager, Install via Git URL with the same URL, then restart. You need ComfyUI v0.30.0+ - it builds on the official MiniMax H3 nodes - and while requirements.txt pulls ultralytics, nothing detects faces until you drop face_yolov8m.pt into models/ultralytics/bbox/. The H3 side is the usual fl2va/ref2va UNET, Qwen3-VL encoder (CLIP Loader type minimax), video and audio VAEs.

Where people get burned

No detection is a hard stop. Zero faces in a segment raises "no face detected" rather than quietly returning the unmodified clip. Swap detector, lower confidence, or accept it's a landscape shot.

ultralytics is AGPL-3.0, which reaches the weights and runtime, not just the code. It also has a supply-chain scar: a poisoned Ultralytics release in December 2024 shipped a cryptominer to ComfyUI users through a detailing pack. Pin your version.

Empty detector dropdown means the weight isn't where it's scanned from - drop it in, restart, it appears. And square edges around the face are full_crop, or face_only with too little feather; try face_ellipse and raise it.

It costs a real extra sampling pass per segment at 768px, on top of the Director and any Refine pass. Fine on a 5-second clip, not free across ten segments; the Director's VRAM-cleanup-before-face-refine option exists for that handoff. And the pack ships no FaceRefine example workflow - you're wiring Director → this node → refine yourself.