ComfyUI-H3-FaceRefine addresses a specific MiniMax H3 problem: a face can remain poorly formed when it occupies only a small part of the frame, even in a high-resolution video. The pack tracks the subject, makes a face-sized crop, regenerates that crop through H3 and stitches it into the original footage.
This guide follows the author's README, example-workflow directory, and dependency file, reviewed October 22, 2026. The instructions are documentation-based. We have not executed the graph or measured an improvement, and H3Vid does not currently offer this multi-stage workflow online.
Repair the right problem
A full-frame upscaler and a face-refinement pass have different jobs. Upscaling increases the image size or detail; FaceRefine changes what H3 sees by making the tracked head fill a larger processing canvas. Its result is generated facial detail, not a recovery of evidence that was absent from the original pixels.
Use it when an otherwise useful shot has a small, unstable face. If identity already changes between people or the source has rapid cuts, solve selection and tracking first. Better-looking crops pasted onto the wrong subject are still the wrong result.
Install the pack and its actual dependencies
Clone Carasibana/ComfyUI-H3-FaceRefine under ComfyUI/custom_nodes and install its requirements with ComfyUI's Python interpreter. You need a recent native H3 setup and a face detector such as face_yolov8m.pt in models/ultralytics/bbox/.
The example templates additionally depend on VideoHelperSuite, the NativeAudioLock custom node and Impact Pack. These requirements are easy to miss: a detector file being present does not necessarily register the folder names saved inside an example graph. Impact Pack supplies those registrations, while NativeAudioLock supplies the template's lip-sync node.
GGUF loaders and a SAM model are optional for the supplied muted branches. Reselect the diffusion model and text encoder after loading a template, because their stored filenames may differ from your installation. Match an acceleration LoRA with its intended step count rather than keeping an unrelated scheduler setting.
Choose Auto Select or Manual Select
The two templates differ in how they choose the subject. Auto Select suits a shot where one stable rule identifies the person: the largest face, the central face or another documented rank. Manual Select uses H3 Load Video + Face Select to decode, detect cuts and let you choose a face per shot before generation.
For Manual Select, choose the video, enable automatic hard-cut detection when needed, open Pick faces, review the outlined faces for each shot and confirm your selections. A manual graph with no confirmed pick fails rather than guessing a person. Changing the video, detector, frame range or cut settings invalidates the saved choice and requires another review.
Use the preview to check where the crop follows the face through turns and occlusions. The transform output records crop placement for the stitch-back stage; preserve that path instead of reconstructing positions from the rendered crops.
Fix “Required input is missing: model” after upgrading
Version 1.1.0 changed H3 Per-Frame Denoise from a latent-path operation to a node that takes and returns MODEL. An old 1.0 graph therefore needs rewiring:
- Route the H3 model into the node's required
modelinput. - Route its
modeloutput onward to the guider used by sampling. - Review the renamed
denoise_multiplier_small_faceanddenoise_multiplier_large_facecontrols alongside the base denoise setting.
Merely providing the input while leaving the guider connected to the old model bypasses the intended modification. The README says this is the release's required wiring change; the old selection names migrate automatically to their new equivalents.
Hard cuts need shot-level decisions
Face numbering and spatial continuity can change at a cut. Automatic detection uses PySceneDetect, supplied as scenedetect>=0.7, so selection, smoothing and interpolation can restart per shot. It detects hard cuts; do not assume every dissolve or complicated transition becomes a clean shot boundary.
If the dependency cannot import, the pack treats the clip as a single shot and reports that fallback. A successful queue therefore does not prove cut detection worked. Read the report before trusting a multi-shot result.
For an identity reference, choose a matcher appropriate to the material. The README distinguishes photographic face matching from CLIP Vision or CCIP options for illustration. A low detector threshold and a low identity threshold solve different problems: finding a face and deciding whose face it is.
Version 1.1.2 changes lost-subject behavior
Earlier tracking could jump to a nearby person when the subject turned away or became occluded. The author says 1.1.2 restricts reassociation to a plausible nearby face. Unresolved frames retain the original pixels as the refined composite fades, and the report lists them under lost: rather than counting them as found.
This update needs no additional rewiring. Inspect the red preview frames and the reported ranges, especially in crowds. A retained original face during an occlusion can be the correct conservative result; it is not evidence that refinement failed everywhere.
Start with a short clip containing the problem, inspect crop stability, then compare the stitched video with the source at normal playback speed. Listen to the saved audio as well. Keep the original footage and graph so a local improvement can be accepted without losing a usable shot.
The cover is an imagegen concept illustration of crop-based face refinement, not a measured before-and-after result.