ComfyUI-H3-FaceRefine Introduction
ComfyUI-H3-FaceRefine helps improve small faces in MiniMax H3 videos. When a person appears far from the camera, their head may occupy only a tiny part of each frame. H3 can struggle to render that face clearly even when the finished video is 720p or higher. Increasing the video’s overall resolution does not necessarily solve the problem, because the face is still small within the frame.
The extension finds a subject’s face, follows it through the video, and gives H3 a larger, consistent view of that area. It then places the refined result back into the original frames. The approach is inspired by Impact Pack’s FaceDetailer, adapted for moving video rather than a single image.
You can use it to:
- Improve a distant character’s facial detail without regenerating the entire scene.
- Keep the refinement focused on one person in a multi-person shot.
- Choose the subject automatically, from a reference image, or by hand for each shot.
- Inspect the tracking before committing to an H3 render.
Example results: source versus refined video, source frame, and refined frame.
How ComfyUI-H3-FaceRefine Works
Think of the process as temporarily moving the camera closer to your subject’s face:
- Find the face. A detector draws a box around faces in each frame. You decide which person to follow.
- Make a steady close-up. The extension follows that person and smooths the crop’s movement and size. This matters because a box that jitters can make the refined face appear to shimmer or “boil.”
- Give H3 more room to work. Each crop is resized onto a consistent canvas. Instead of seeing a tiny head in a wide scene, H3 sees the subject and some surrounding hair and background.
- Return to the original composition. The extension records where each crop came from, then stitches the refined face into its corresponding source frame.
See the crop H3 receives and the refined crop it returns. The input still and output still make the detail easier to inspect.
Tracking is especially important when a face turns away, becomes covered, or crosses another person. If the extension cannot confidently locate the chosen subject, it can leave those frames unresolved and fade the refinement out, retaining the original pixels instead of refining the wrong person.
A shot is a continuous stretch of video between hard cuts. When cut detection is enabled, the extension chooses or reacquires the subject and smooths the crop separately within each shot. It does not try to move one crop box across an abrupt camera change.
ComfyUI-H3-FaceRefine Features
Two starting workflows
The included H3 Face Refine Auto Select and H3 Face Refine Manual Select templates share the same refinement process. They differ in how you identify the subject. Open them through Workflow → Browse Templates, or use the JSON files in example_workflows/.
| Workflow | Best for | How the subject is chosen |
|---|---|---|
| Auto Select | A clip where a simple rule reliably identifies your subject | A ranking such as largest_face, the supplied default |
| Manual Select | Crowds, changing compositions, or a subject who is not consistently the largest face | You choose a face separately for each shot with Pick faces |
For either template, use the same character reference images and prompt used for the original video. Ref 1 supplies the identity; Ref 2 is optional for wardrobe or another look. The templates take audio from the source clip. If you have a separate vocal track for lip sync, the audio loader can be unmuted and connected in its place.
Both templates include a muted SAM mask pair. As supplied, they use a rectangular paste mask and do not require a SAM model. Unmuting the pair enables a face-shaped mask; the author recommends lowering feather to about 4–8 when doing so.
H3 Load Video + Face Select
This node loads video and audio, detects faces and hard cuts, and passes your subject choice to the tracker. When you connect its face_pick output to H3 Face Track + Crop, the tracker can reuse its detections rather than detecting the same video again during the graph run. View the node.
You can Browse… for a video, which copies it into ComfyUI’s input folder, or paste a full path to read a file where it already lives. The latter can avoid duplicating a large source clip.
With select = manual, click Pick faces to see one representative frame per shot. Faces are outlined and numbered from left to right; select the person you want in each shot and press Use these. Choose not in this shot when your subject is absent, so that shot keeps its original pixels. Face numbers can change after a cut, so check every shot even when the same character appears throughout. View the picker or an example across several shots.
Other useful controls include:
identity_reference: Choose the person who resembles a supplied image in each shot. This can help follow the same character when face numbers change.closest_to_xy: Choose the face nearest coordinates you enter. Preview coordinates shows a crosshair and highlights the nearest detected face before you render. Coordinates use source-frame pixels measured from the top-left. View the coordinate preview.cut_detection: Set toauto (pyscenedetect)for clips with hard cuts. If it detects too many cuts, raisecut_threshold; if it misses cuts, lower it.- Frame controls:
skip_first_frames,frame_load_cap, andselect_every_nthlet you work with part of a clip or fewer frames. Skipping every nth frame also changes the effective outputfps.
The picker reuses a previous scan when its relevant settings have not changed. Changing the video, detector, confidence, frame range, or cut settings clears saved picks because the old face numbers might no longer describe the new scan.
H3 Face Track + Crop
This node follows the chosen face, fills detection gaps where possible, smooths the crop, and produces both the crops and a transform that tells later nodes where to put them back. Its preview draws the crop box on the video; its report describes detections, gaps, lost-subject frames, and magnification warnings. View the node.
| Setting | What changing it does |
|---|---|
detector_confidence (default 0.35) | Lower values may find more small or turned faces, but may also accept false detections. This is separate from identity matching. |
crop_factor (default 2.5) | A larger crop includes more surrounding hair and background but magnifies the face less. The author suggests 2.0–3.0 as a useful range. |
canvas_mode | manual uses your exact canvas dimensions. auto_no_downscale sizes from the largest crop; auto_capped_768 also caps it at 768. Both automatic modes use a minimum of 512 × 512. |
canvas_width / canvas_height (default 768) | Set the generation canvas in manual mode. A larger canvas gives H3 more pixels to work with but increases processing demands. |
smooth_window (default 21) | Smooths crop position. Increase it if the box shakes; decrease it if it trails fast head movement. |
size_smooth_window (default 51) | Smooths crop size. Increasing it can reduce the “breathing” caused by rapidly changing crop scale. |
smooth_method | gaussian emphasizes jitter reduction; savgol better preserves the shape of a gradual camera push-in at large windows; moving_average is a simpler alternative. |
size_mode | per_frame adapts crop size as a face grows or shrinks in the shot. max_of_clip holds one size throughout and is more suited to a static shot. |
The preview box is green when the chosen face was detected, yellow when a fallback body detector estimated the head position, and red when the subject’s position was unresolved and interpolated. Refinement fades out across yellow and red stretches. Save or inspect this preview before a costly render if the shot contains occlusions or several people.
Keep the outputs connected: canvas_w and canvas_h should drive H3’s width and height; frame_count should drive its length. The transform must reach the nodes that need crop positions, including H3 Face Stitch Back. If an automatic canvas size differs from the H3 dimensions, latent injection cannot proceed.
Choosing and keeping the right face
Automatic selection makes its initial choice once per shot. The tracker then follows that face by continuity rather than repeatedly selecting whichever face currently ranks first.
| Choice | When it may help |
|---|---|
largest_face / smallest_face | Follow the nearer or more distant person. |
left_most / right_most | Choose a person by horizontal position. |
top_most / bottom_most | Choose a person by vertical position. |
centre_most | Follow someone near the middle of the frame. |
closest_to_xy | Choose the face nearest a specified point on a specified frame. |
detector_score | Choose the detection with the strongest detector score. |
identity_reference | Match a supplied image; available on the video-and-face-select node. |
manual | Make a reviewed choice in Pick faces; available on the video-and-face-select node. |
For ranking choices, select_index = 0 means the first-ranked face, 1 the second, and so on. A ranking is not a person’s identity: when two people cross or change apparent size, their rankings can change. Manual picks are the clearest option when a rule repeatedly chooses the wrong person.
On the tracker, identity_track helps hold one subject in a crowd. A connected identity_reference is consulted only when identity tracking is enabled; otherwise the selection rule decides. The optional fallback_detector uses a body detection to estimate where the chosen person’s head should be when no face is found. For a shot where the subject is entirely absent, absent_shots = by_identity can omit that shot when identity matching has a usable anchor. Check the report: its sampling may miss a very brief appearance.
Per-frame denoise and stitching
H3 Per-Frame Denoise adjusts processing across frames using the tracking information. It takes a MODEL input and returns a patched MODEL; connect that output onward to the guider and scheduler. Its two strength controls are denoise_multiplier_small_face and denoise_multiplier_large_face.
H3 Face Stitch Back uses the saved transform to return each refined crop to its original frame. Together, these nodes let the workflow concentrate generation on the face while preserving the surrounding video.
ComfyUI-H3-FaceRefine Models
The extension’s own nodes require a face detector. The full H3 workflows also need the models used by H3 and any optional features you enable. A model’s purpose matters more than collecting every option: start with the detector suited to your artwork, then add optional models only when your workflow calls for them.
| Model or model type | Purpose and when to use it |
|---|---|
face_yolov8m.pt | A photographic face detector and a practical starting point for human video. The extension looks for it in models/ultralytics/bbox/. |
| Anime face detector | Use an illustration-oriented detector when a photographic detector misses drawn or stylized faces. It belongs in models/ultralytics/bbox/. |
person_yolov8m-seg.pt | Optional body detector for estimating head position when a face is not detected. Both supplied templates have it wired as fallback_detector; its folder is models/ultralytics/segm/. |
| Comfy-Org MiniMax H3 models | The diffusion model, Qwen3-VL text encoder, and video/audio VAEs used by the H3 workflow. These are the ComfyUI-ready H3 weights, not alternative face detectors. |
| Turbo LoRA | Optional speed-up. The examples use an 8-step v1.0 LoRA at strength 1.0 with an eight-step scheduler; match the scheduler’s step count to the turbo LoRA you choose. |
| CLIP Vision model | Optional identity comparison through identity_model = clip_vision. Connect it with CLIPVisionLoader, especially for stylized or illustrated characters. |
InsightFace buffalo_l | Optional identity comparison through identity_model = insightface, suited to photographed faces. It is downloaded on first use. Review the InsightFace model licensing information before using its pretrained models. |
| CCIP | Optional identity comparison designed for anime characters. It is not included as a dependency of this extension. |
| SAM model | Optional model for the templates’ muted, face-shaped mask pair. You do not need it for the templates as supplied. |
For photographic footage, begin with a photographic face detector and insightface identity matching. For anime or other illustration, use an appropriate illustrated-face detector first: an identity model cannot compare faces the detector never finds. Then consider clip_vision for broad stylized material or ccip for anime-specific matching. CLIP Vision compares appearance, so similarly colored characters may be harder to distinguish.
identity_threshold scores are not interchangeable between identity models. Set it to 0 to use the chosen model’s recommended default, then inspect the report’s observed scores before adjusting it.
The example workflows’ stored H3 model and text-encoder choices may name files you do not have. Re-select the files available in your own loaders when opening a template. A muted ComfyUI-GGUF loader pair is also present as an optional lower-memory alternative; it is not part of the default path.
What's New with ComfyUI-H3-FaceRefine
Version 1.1.2
- More reliable subject tracking after a face disappears. In a multi-person shot, the tracker no longer switches to another person simply because the chosen face is temporarily missing. If it cannot find a face near the subject’s last position, it leaves those frames unresolved, interpolates the crop, and fades the refinement out so the original pixels remain. This is particularly useful for turns, brief coverings, and spins.
- Clearer tracking feedback. A new
lost:report line lists affected frames and ranges; lost frames also appear in the face and dropout counts. Thepreviewmarks them red, making a mistaken or interrupted track easier to spot. - Better body fallback in crowds.
fallback_detectornow chooses the body whose head is nearest the subject’s expected position rather than simply choosing the largest body.
Saved workflows from 1.1.0 load without rewiring.
Version 1.1.0
- New H3 Load Video + Face Select node. It finds faces and hard cuts while loading video, offers Pick faces and Preview coordinates, and passes its detections to the tracker. This makes per-shot subject selection visible before rendering.
- Hard-cut detection.
auto (pyscenedetect)lets tracking, smoothing, gap filling, and composite fading restart at shot boundaries. If PySceneDetect is unavailable, the run continues but treats the clip as one shot and says so in the report. - Nine clearly named ranking choices. Selection expanded from
largestandmost_centralto the nine positional, size, coordinate, and detector-score options listed above. Saved choices migrate tolargest_faceandcentre_most. - More tracking outputs and controls. The tracker gained
frame_count,face_pick,absent_shots,identity_model, and cut-detection options. - Larger default canvas and an automatic size floor. Manual canvas dimensions now default to 768; automatic modes do not shrink below 512 × 512, helping avoid an unhelpfully small H3 input.
- Changed H3 Per-Frame Denoise wiring. The node now requires a
MODELinput and emits a patchedMODELoutput. Workflows saved against 1.0.0 need this connection added or validation reportsRequired input is missing: model.
Troubleshooting ComfyUI-H3-FaceRefine
The wrong person is refined
- Inspect the tracker’s
previewandreportto see when it first chose a face and whether it later lost the subject. - For a straightforward composition, try a different
selectrule orselect_index. - For crowds or changing shots, use H3 Load Video + Face Select, choose
manual, and pick the subject in every shot. Mark shots where they are absent as not in this shot. - If using an identity reference, check that it shows the intended person clearly and that your detector finds faces in this type of artwork.
The crop shakes, lags, or looks like it changes size
- View the animated tracking
previewbefore rendering again. - If the box shivers, increase
smooth_window. If it trails a fast-moving face, decrease it. - If the face seems to grow and shrink unnaturally, try a larger
size_smooth_window. - If the problem occurs at a hard cut, enable
cut_detection = auto (pyscenedetect)and check the number of shots in the report. Very short shots have fewer frames available for smoothing.
Faces are missing from detection
- Confirm the selected detector suits the image style. A photographic detector may miss anime faces.
- Lower
detector_confidencecautiously to catch more small or turned faces, then check for false positives in the preview. - For occasional missed faces in photographic footage, consider a body model as
fallback_detector. Yellow preview boxes show where that fallback was used. - If the subject moves far while hidden, the tracker may not reacquire them at the new position. Inspect the red frames and consider a different clip or shot-level selection.
The workflow will not queue or the result does not align
- For
Required input is missing: model, route the model into H3 Per-Frame Denoise and connect itsmodeloutput onward to the guider and scheduler. - For a canvas or latent-size mismatch, connect the tracker’s
canvas_wandcanvas_hto H3’swidthandheightinstead of typing separate values. - Connect the tracker’s
frame_countto H3’slength, especially when absent shots are omitted. - If manual selection is enabled, finish Pick faces and press Use these. An unanswered manual choice intentionally prevents the graph from running.
- If an example template’s detector or H3 model dropdown names a missing file, select the corresponding model available in your setup.
Frequently asked questions
Will this improve every face in a video?
It is designed to follow and refine a chosen subject. For a crowded scene, identify the person you mean with a manual pick, identity reference, or suitable ranking rule.
Why is a high-resolution source not enough?
The issue is often the face’s size within the frame. A distant face can still be only a few pixels tall in a 720p-or-higher video. Cropping gives H3 a larger view of it.
What do red and yellow preview boxes mean?
Yellow indicates a head position estimated from a fallback body detection. Red indicates an unresolved position filled from neighboring frames. In these stretches, the composite fades toward the original footage.
Why do my face numbers change between shots?
Each hard cut starts a new view and a new set of detections. The picker therefore asks you to choose the subject separately for each shot.
Do I need a SAM model?
Not for the supplied templates as shipped. Their SAM mask pair is muted.
Why does cut detection say the video is one shot?
If PySceneDetect is missing or fails to load, the workflow continues without automatic hard-cut detection and reports that it is treating the clip as one shot.
Can I preview a video from a path outside ComfyUI’s input folder?
The video-and-face-select node can read a pasted path in its default configuration. On a remotely accessible or shared ComfyUI setup, the H3_FACEREFINE_STRICT_PATHS setting can restrict those paths to ComfyUI’s own folder; in that configuration, use Browse… to bring a video into input.
Learn More about ComfyUI-H3-FaceRefine
- ComfyUI-H3-FaceRefine repository: The extension’s source, examples, and project information.
example_workflows/: The annotated Auto Select and Manual Select workflows, also available through ComfyUI’s template browser.- ComfyUI-VideoHelperSuite: Background on loading, previewing, and saving video in ComfyUI. Its preview controls can help you compare the input and output clips.
- ComfyUI-Impact-Pack: The source of FaceDetailer, which inspired this video-focused approach, and a dependency of the supplied workflow templates.
- Comfy-Org MiniMax H3: The ComfyUI-ready H3 model files used by the broader workflow.
