comfyui-h3-facerefine

ComfyUI-H3-FaceRefine is a set of ComfyUI custom nodes for post-processing MiniMax H3 video. It addresses the case where H3 renders faces poorly because a head occupies only a small part of the source frame. The pipeline detects and tracks a face, normalizes the crop to a larger canvas, passes that crop through H3, and stitches the generated face back into the original video using the recorded crop transform. Its approach is modeled on Impact Pack's FaceDetailer but extended for frame-to-frame video work. Main components include: - H3 Load Video + Face Select: loads video and audio, detects faces, optionally detects hard cuts, and selects a subject before the graph runs. It can use a manual Pick faces interface, ranking rules, or an identity reference image. - H3 Face Track + Crop: tracks the selected subject across each shot, produces crops and transform data, outputs canvas dimensions and frame count, and handles smoothing, interpolation, missing faces, and shot boundaries. - H3 Per-Frame Denoise: applies per-frame denoising controls as a model-path patch, taking and returning a MODEL input. - H3 Face Stitch Back: composites the refined H3 output back into the source frames and preserves the original audio path. Subject selection supports automatic ranking modes such as largest, smallest, leftmost, rightmost, topmost, bottommost, centremost, closest to X/Y coordinates, and detector score. Identity-based selection can use InsightFace for photographic faces, while CLIP Vision or CCIP are suggested for illustrated or anime material. A user-supplied face detector is required, such as face_yolov8m.pt; an anime face detector is recommended for non-photographic content. The pack uses PySceneDetect for optional hard-cut detection. When available, cuts split the video into shots so the subject can be selected separately per shot and tracking is not smoothed across a cut. If PySceneDetect is unavailable, the video is treated as one shot. Tracking reports identify lost-frame ranges, and lost frames can be highlighted in preview. When the subject disappears, the tracker avoids jumping to another person and can interpolate the crop while fading the composite out to retain original pixels. Two annotated workflow templates are included: Auto Select, where a ranking rule chooses the face, and Manual Select, where the user chooses one face per shot. The templates are available through ComfyUI's template browser and can also be loaded from the example_workflows directory. They use the tracking node's frame count and canvas dimensions to keep H3 generation aligned with the source clip. Installation is performed by cloning the repository into ComfyUI/custom_nodes and restarting ComfyUI. The nodes appear under the MiniMax H3/Face Refine menu. Python packages including ultralytics, scipy, insightface, and scenedetect can be installed from the project requirements. A recent ComfyUI build with the core MiniMax H3 nodes is required, along with the H3 model, text encoder, and VAE unless those are already installed. The example workflows additionally use VideoHelperSuite for saving, ComfyUI-H3-NativeAudioLock for audio/lipsync handling, and Impact Pack for model-folder registration. SAM and GGUF components are present but muted by default; SAM models, GGUF loader support, CLIP Vision, InsightFace models, and turbo LoRAs are optional depending on the workflow configuration. For videos loaded by pasting an absolute path, the pack serves local previews outside ComfyUI's input directory. Setting H3_FACEREFINE_STRICT_PATHS to a non-empty value restricts those routes to files inside ComfyUI's own folder, which is useful when ComfyUI is exposed beyond localhost.