Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-H3-FaceRefine

ComfyUI Extension: ComfyUI-H3-FaceRefine

Repo Name

ComfyUI-H3-FaceRefine

Author
carasibana (Account age: 343 days)
Nodes
View all nodes(7)
Latest Updated
2026-09-13
Github Stars
0.57K

How to Install ComfyUI-H3-FaceRefine

Install this extension via the ComfyUI Manager by searching for ComfyUI-H3-FaceRefine
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-H3-FaceRefine in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

ComfyUI-H3-FaceRefine Description

ComfyUI-H3-FaceRefine improves small faces in MiniMax H3 videos by selecting and tracking a subject, creating steady close-up crops for H3 to refine, then blending the result into the original frames.

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:

  1. Find the face. A detector draws a box around faces in each frame. You decide which person to follow.
  2. 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.”
  3. 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.
  4. 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/.

WorkflowBest forHow the subject is chosen
Auto SelectA clip where a simple rule reliably identifies your subjectA ranking such as largest_face, the supplied default
Manual SelectCrowds, changing compositions, or a subject who is not consistently the largest faceYou 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 to auto (pyscenedetect) for clips with hard cuts. If it detects too many cuts, raise cut_threshold; if it misses cuts, lower it.
  • Frame controls: skip_first_frames, frame_load_cap, and select_every_nth let you work with part of a clip or fewer frames. Skipping every nth frame also changes the effective output fps.

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.

SettingWhat 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_modemanual 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_methodgaussian emphasizes jitter reduction; savgol better preserves the shape of a gradual camera push-in at large windows; moving_average is a simpler alternative.
size_modeper_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.

ChoiceWhen it may help
largest_face / smallest_faceFollow the nearer or more distant person.
left_most / right_mostChoose a person by horizontal position.
top_most / bottom_mostChoose a person by vertical position.
centre_mostFollow someone near the middle of the frame.
closest_to_xyChoose the face nearest a specified point on a specified frame.
detector_scoreChoose the detection with the strongest detector score.
identity_referenceMatch a supplied image; available on the video-and-face-select node.
manualMake 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 typePurpose and when to use it
face_yolov8m.ptA photographic face detector and a practical starting point for human video. The extension looks for it in models/ultralytics/bbox/.
Anime face detectorUse an illustration-oriented detector when a photographic detector misses drawn or stylized faces. It belongs in models/ultralytics/bbox/.
person_yolov8m-seg.ptOptional 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 modelsThe 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 LoRAOptional 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 modelOptional identity comparison through identity_model = clip_vision. Connect it with CLIPVisionLoader, especially for stylized or illustrated characters.
InsightFace buffalo_lOptional 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.
CCIPOptional identity comparison designed for anime characters. It is not included as a dependency of this extension.
SAM modelOptional 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. The preview marks them red, making a mistaken or interrupted track easier to spot.
  • Better body fallback in crowds. fallback_detector now 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 largest and most_central to the nine positional, size, coordinate, and detector-score options listed above. Saved choices migrate to largest_face and centre_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 MODEL input and emits a patched MODEL output. Workflows saved against 1.0.0 need this connection added or validation reports Required input is missing: model.

Troubleshooting ComfyUI-H3-FaceRefine

The wrong person is refined

  1. Inspect the tracker’s preview and report to see when it first chose a face and whether it later lost the subject.
  2. For a straightforward composition, try a different select rule or select_index.
  3. 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.
  4. 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

  1. View the animated tracking preview before rendering again.
  2. If the box shivers, increase smooth_window. If it trails a fast-moving face, decrease it.
  3. If the face seems to grow and shrink unnaturally, try a larger size_smooth_window.
  4. 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

  1. Confirm the selected detector suits the image style. A photographic detector may miss anime faces.
  2. Lower detector_confidence cautiously to catch more small or turned faces, then check for false positives in the preview.
  3. For occasional missed faces in photographic footage, consider a body model as fallback_detector. Yellow preview boxes show where that fallback was used.
  4. 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

  1. For Required input is missing: model, route the model into H3 Per-Frame Denoise and connect its model output onward to the guider and scheduler.
  2. For a canvas or latent-size mismatch, connect the tracker’s canvas_w and canvas_h to H3’s width and height instead of typing separate values.
  3. Connect the tracker’s frame_count to H3’s length, especially when absent shots are omitted.
  4. If manual selection is enabled, finish Pick faces and press Use these. An unanswered manual choice intentionally prevents the graph from running.
  5. 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.

ComfyUI-H3-FaceRefine Related Nodes

RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

ComfyUI-H3-FaceRefine detailed guide | ComfyUI