H3 Load Video + Face Select:
H3FaceSelect loads a video, detects every visible face, and decides which person should be treated as the subject before the rest of the workflow processes the clip. It performs one face-detection pass over the loaded frames, creates a visual preview showing detected faces with numbers, and stores the selected face information so a downstream H3 Face Track + Crop node can follow the chosen person without repeating face detection. You can select a subject manually, choose one using rules such as largest or leftmost face, or compare faces against an identity reference image. When cut detection is enabled, the video is divided into shots and a subject is selected separately for each shot, preventing face numbers from becoming confused after a hard cut. The node also preserves and adjusts audio when frames are skipped, capped, or sampled at intervals, reports detection and selection details, and identifies shots where the selected subject is absent or no face can be found.
H3 Load Video + Face Select Input Parameters:
video
The source video to load and analyze. You can choose a file from ComfyUI’s input folder with Browse or paste a full path to a file stored elsewhere; surrounding single or double quotes are removed automatically, which is useful when copying a path from a file manager. The video is decoded into frames, and those frames are used for face detection, preview generation, subject selection, and the images output. Default: empty string. There is no source-code-defined minimum or maximum length, but the value must identify an existing video file.
detector
The face-detection model used to find faces in each video frame. The available choices come from the installed ultralytics_bbox and ultralytics model lists; if no detector is discovered, the node offers face_yolov8m.pt as a fallback name. Choose a photographic face model for live-action footage and an anime or illustration-trained face model for drawn or stylized material. The detector affects which faces are available for selection, the quality of the bounding boxes, processing time, and whether small, profile, or stylized faces are found at all. Default: the first configured detector returned by the installed model list, or face_yolov8m.pt when no list is available. The selected model must exist in an appropriate Ultralytics model folder.
confidence
The minimum confidence required for a detector result to count as a face. Lower values can detect smaller faces, side profiles, partially obscured faces, or difficult stylized faces, but they can also introduce false positives that appear as selectable faces. Higher values reduce accidental detections but may cause the intended subject to disappear from some frames. Default: 0.35. Minimum: 0.05. Maximum: 0.95. Step: 0.05.
select
Determines how the subject is chosen from the detected faces. Detection remains automatic in every mode, while this setting controls which detected face is considered the subject. The available modes shown by the node are manual, identity_reference, largest_face, smallest_face, left_most, right_most, top_most, bottom_most, centre_most, closest_to_xy, and detector_score. In manual mode, you review the numbered preview and provide one face index for each shot through confirmed_pick; in identity_reference mode, the node compares detected faces with the supplied reference image; the other modes choose according to face size, position, distance from the frame centre or X/Y point, or detector confidence. The subject is chosen once per shot and then followed through that shot rather than being re-ranked independently on every frame. Default: manual. If cut detection is enabled, the choice is made again after each detected cut. To maintain the same person across cuts, use manual or identity_reference.
select_index
The zero-based position of the face in the ranking created by the selected automatic rule. For example, 0 means the first face in the chosen ranking, while 1 means the second. This is used by automatic selection modes and is ignored for the actual choice when select is manual or identity_reference. Face numbers are recalculated for each shot, so an index is not guaranteed to refer to the same person after a cut. Default: 0. Minimum: 0. Maximum: 63. If the requested index is larger than the maximum number of faces detected in any frame, the node clamps it to the highest available index and adds a warning to the report.
confirmed_pick
The manually confirmed face choice, entered as one zero-based face index per shot and separated by commas, such as 0,1,1. Face numbers correspond to the numbered faces shown in the preview. This value is used only when select is manual; it is ignored by automatic selection modes and identity matching. A separate entry is required for each detected shot, and the entries are positional, so changing cut detection or changing the video can make an old selection invalid. Default: empty string. No numeric range is defined because it is a comma-separated text value. Manual mode raises an error when this value is empty.
cut_detection
Controls whether the node searches for hard cuts and treats the video as multiple shots. The available choices are provided by the node’s cut-mode list; the source explicitly supports none as the default and uses the other available mode to enable cut detection. With none, the entire loaded video is treated as one shot and continuity runs across the whole clip. When enabled, each detected cut starts a new shot, face rankings restart, and the subject is selected independently for each shot. The cut information is also stored for downstream tracking so the tracker does not smooth a crop across a scene change. Default: none. The exact selectable options depend on the node’s _CUT_MODES definition.
cut_threshold
Controls how strongly a frame must differ from nearby frames before it is considered a hard cut when cut detection is enabled. Lower values make the detector more sensitive and may split the video at strong lighting changes or fast visual transitions; higher values are less sensitive and may miss subtle cuts. The node uses an adaptive scene detector that compares a frame with a rolling neighbourhood rather than simply reacting to ordinary sustained motion. This input has no effect when cut_detection is none. Default: 3.0. Minimum: 0.5. Maximum: 20.0. Step: 0.25.
skip_first_frames
Removes this many frames from the beginning before detection and selection. This can be useful for removing an unwanted leader, slate, or opening section. The count is applied before the node reports frame numbers and before frame_index is interpreted. When audio is present, the corresponding beginning portion is removed as well so the remaining audio stays aligned with the remaining images. Default: 0. Minimum: 0. Maximum: 100000.
frame_load_cap
Limits the number of frames retained after the starting offset and sampling settings are applied. A value of 0 means that all available frames are loaded. A positive value stops loading after that many retained frames, which can reduce processing time and memory use when you only need a segment. The node reports an error if the combination of this value, skip_first_frames, and select_every_nth leaves no frames. Default: 0. Minimum: 0. Maximum: 100000. For H3 processing, the report also warns when the retained frame count does not fit H3’s stated 17k+5 frame grid.
select_every_nth
Keeps every nth frame after the initial skip. A value of 1 keeps every frame; 2 keeps every second frame; larger values reduce the number of frames analyzed and output. Sampling can substantially reduce processing time, but it also removes intermediate motion information and changes the effective frame rate to the original rate divided by this value. Audio is trimmed to the surviving time range, while the reported fps reflects the changed effective rate. Default: 1. Minimum: 1. Maximum: 100. Step: 1.
identity_reference
An image containing the person you want the node to identify. This can be a portrait or a frame from the source video. When select is identity_reference, the node compares detected faces in each shot against this image and selects the matching face; a shot with no match above the identity threshold is marked as not containing the person and is left untouched downstream. This input is required in identity-reference mode and is ignored by all other selection modes. Default: no image connected. There is no numeric range.
identity_clip_vision
A CLIP Vision model used when identity_model is set to clip_vision. Connect a model from a CLIPVisionLoader so the node can create and compare visual face embeddings using that method. This input is not needed for insightface or ccip, and the node may fail if clip_vision is selected without a suitable model connected. Default: no model connected. There is no numeric range.
identity_model
Selects the method used to compare the detected faces with identity_reference. Available options are insightface, clip_vision, and ccip. insightface is intended primarily for photographic faces, while clip_vision and ccip can be more suitable for illustration or other material where photographic face-recognition models perform poorly. Default: insightface. The selected method affects compatibility with the artwork style, the meaning of the similarity score, and whether an additional CLIP Vision model is required.
identity_threshold
Sets the minimum similarity score required for a detected face to count as the same identity as the reference. Lowering the threshold can recover matches affected by stylization, unusual lighting, profile views, or low image quality, but it also increases the chance of selecting a different person. Raising it makes matching stricter and can mark more shots as not containing the subject. A shot with no face reaching this threshold is marked absent and is not selected for rendering. Default: 0.28. Minimum: 0.0. Maximum: 1.0. Step: 0.01. The effective threshold may use the selected identity method’s default when the supplied value is zero.
X
The horizontal pixel coordinate used only by select=closest_to_xy. Coordinates start at the top-left corner of the source frame and increase toward the right. The face whose centre is closest to this point is selected, even if the point does not lie directly on a face. For example, on a 960-pixel-wide video, X=480 points to the horizontal centre. Default: 0. Minimum: 0. Maximum: 16384. Step: 1. This value has no effect for other selection modes.
Y
The vertical pixel coordinate used only by select=closest_to_xy. Coordinates start at the top-left corner and increase downward. For a 544-pixel-tall video, Y=272 points to the vertical centre. The node compares this point with the centres of detected face boxes and chooses the nearest one. Default: 0. Minimum: 0. Maximum: 16384. Step: 1. This value has no effect for other selection modes.
frame_index
Specifies the loaded frame on which the X/Y measurement is made when select=closest_to_xy. The frame count starts at 0, and the index refers to the frames retained by this node, not necessarily the original file numbering. Therefore, after skip_first_frames or select_every_nth is used, 0 means the first retained frame. Choose a frame where the intended subject is clearly visible; the selected face is then followed forward and backward through that shot. Default: 0. Minimum: 0. Maximum: 999999. Step: 1. This input has no effect for other selection modes.
H3 Load Video + Face Select Output Parameters:
images
The processed batch of video frames as an IMAGE output. Frames are stored in ComfyUI image format with values suitable for downstream image and video nodes. The batch reflects skip_first_frames, frame_load_cap, and select_every_nth, so it may contain fewer frames than the original file. These are the original visual frames; H3FaceSelect does not itself crop, replace, or refine the selected person.
audio
The source audio aligned with the retained frames as an AUDIO output. When frames are skipped, capped, or sampled, the audio is trimmed to the corresponding time range so it remains aligned as closely as possible with the output frames and reported frame rate. If the source contains no audio, the node supplies a silent audio track so downstream save nodes can still receive a valid audio value.
face_pick
An H3FACEPICK data object containing the detection and selection information intended for H3 Face Track + Crop. It includes the detected face boxes and confidence values for each frame, shot segments, the selected face for each shot, source dimensions, detector settings, selection settings, and identity information when identity matching is used. This is the important connection for avoiding a second face-detection pass: connect it to the downstream tracking node so that node can follow the decisions already made here. A pick with no face has a frame value of -1, while an identity shot marked absent is recorded as not containing the reference subject.
preview
A visual review image containing one card per detected shot. Each card shows the frame on which the shot’s selection was locked, outlines all detected faces, numbers them according to the ranking used by the selected mode, and highlights the chosen face in green. Other detected faces are outlined in blue; for closest_to_xy, the target point is also shown. Use this output with a PreviewImage node to confirm manual face numbers before entering them in confirmed_pick.
report
A text summary describing the source filename, retained frame count, resolution, frame rate, audio availability, number of detections, maximum faces in one frame, number of shots, selection mode, and the selected face and lock frame for each shot. It also reports warnings such as missing faces, absent identity matches, mismatched manual selections, clamped face indices, unavailable cut detection, and frame counts that do not fit H3’s 17k+5 grid. This output is useful for checking whether the node interpreted the video and selection settings as intended.
frame_count
The number of frames actually retained and returned through images. This value reflects the applied skip, cap, and every-nth settings rather than the original video’s full frame count. It is useful when configuring downstream H3 processing, especially because the report warns when this count is not on the expected H3 frame grid. Type: integer.
fps
The effective frame rate of the returned image sequence. It matches the source rate when every frame is kept and becomes the source rate divided by select_every_nth when frames are sampled. Use this value with downstream video-saving or processing nodes so motion timing remains consistent. Type: floating-point number.
H3 Load Video + Face Select Usage Tips:
- Connect
previewto a PreviewImage node before filling inconfirmed_pick; the preview numbers are the face indices you should enter, starting at0. - In manual mode, enter exactly one comma-separated index for every detected shot, such as
0,1,1. If you change the video, cut settings, detector, or confidence, click the face-picking workflow again because the old entries may no longer correspond to the same shots. - Use
identity_referencewhen the same person must be followed across hard cuts. Manual and identity selection are safer than a simple face index when people change position or face rankings between scenes. - For photographic footage, start with
insightface; for anime, illustration, or strongly stylized material, try an appropriate detector and considerclip_visionorccipfor identity matching. - If faces are missing, lower
confidence gradually, such as from0.35to0.25, and check the preview for false positives. Do not lower it excessively without reviewing the resulting boxes. - Choose a detector that matches the material. A photographic detector may find little or nothing in anime artwork, while an anime detector may perform better on illustrated faces.
- Enable cut detection when the video contains scene changes and the subject may change between scenes. Leave it off only when treating the entire clip as one continuous shot is intentional.
- For
closest_to_xy, setXandYusing source-frame pixels and chooseframe_indexwhere the intended face is clearly visible. Remember that the index refers to the retained sequence after frame skipping and sampling. - Use
frame_load_capandselect_every_nthto reduce memory use and processing time for tests, but restore full-frame sampling for final work when smooth motion and accurate tracking matter. - Keep the selected detector and confidence consistent with downstream tracking expectations; the
face_pickpayload records these settings so mismatches can be diagnosed. - Review the report before starting a long H3 render. Pay particular attention to absent identity shots, no-face shots, clamped indices, and warnings about the H3
17k+5frame-count grid. - When possible, adjust
frame_load_capso the retained count fits the H3 grid indicated by the report. The report suggests a nearby lower count when the current frame count is unsuitable.
H3 Load Video + Face Select Common Errors and Solutions:
No video chosen. Use Browse, or paste a path into `video`.
- Explanation: The
videoinput is empty or contains only spaces and quotes, so the node has no source file to load. - Solution: Use Browse to select a video from the ComfyUI input folder or paste a valid full file path into
video.
Video not found: <path>
- Explanation: The supplied path does not point to an existing file, and the filename could not be resolved from ComfyUI’s input folder.
- Solution: Check the spelling, extension, and folder location. Use Browse when possible, or paste the complete path without accidentally omitting part of it.
select is manual, but no face has been chosen. Click Pick faces on this node and choose one in each shot, or set select to a rule such as largest_face.
- Explanation: Manual mode requires a confirmed selection and does not automatically assume that face
0is the intended subject. - Solution: Review the
preview, enter one face index per shot inconfirmed_pick, or changeselectto an automatic rule.
select is identity_reference, but nothing is wired into the identity_reference input. Connect a picture of the person, or choose a different select mode.
- Explanation: Identity selection cannot work without a reference image.
- Solution: Connect a clear portrait or a frame containing the intended person to
identity_reference, or choose another selection mode.
Face detector '<name>' not found in ultralytics_bbox / ultralytics model folders.
- Explanation: The selected detector name is not available in the configured Ultralytics model directories.
- Solution: Install or place the detector in the expected
ultralytics_bboxorultralyticsmodel folder, refresh the model list, and select the installed name. Make sure the model is compatible with the type of material you are processing.
No face detected in any frame. Lower `confidence`, or use a detector that suits this material - a photographic face model finds nothing on anime.
- Explanation: The detector did not produce any accepted face boxes throughout the loaded video. The confidence threshold may be too high, the faces may be too small or obscured, or the model may not suit the footage.
- Solution: Lower
confidencein small steps, use a detector trained for the footage style, check that the video frames are valid, and inspect whether the subject is visible in the retained frame range.
No face found in identity_reference. Use a clearer picture of them, or an identity_model that suits this material.
- Explanation: The selected identity method could not find a usable face in the reference image.
- Solution: Provide a clearer, larger image with the face visible, crop away distracting content if needed, or select an identity method better suited to photographic or illustrated material.
skip_first_frames=... / frame_load_cap=... / select_every_nth=... select no frames out of ...
- Explanation: The frame controls remove or skip every available frame, leaving nothing to analyze.
- Solution: Reduce
skip_first_frames, increaseframe_load_cap, or lowerselect_every_nthto1or another value that leaves at least one retained frame.
identity_model=clip_vision without a suitable CLIP Vision model
- Explanation: The
clip_visionidentity method requires a model connected toidentity_clip_vision, but no usable model was supplied. - Solution: Load a compatible CLIP Vision model with CLIPVisionLoader and connect it to
identity_clip_vision, or chooseinsightfaceorccip.
cut detection unavailable, treating the video as one shot: <details>
- Explanation: The optional scene-detection component could not be loaded or initialized. The node continues by treating the entire retained video as one shot.
- Solution: Install or repair the scene-detection dependency used by the workflow if shot splitting is important, or leave cut detection disabled and review the single-shot behavior.
confirmed_pick holds ... entry(s) but this video has ... shot(s)
- Explanation: The number of manually confirmed face indices does not match the number of detected shots. Because entries are positional, the selections may describe the wrong shots.
- Solution: Run the face review again after the current cut settings and detector are finalized, then enter exactly one confirmed index for each shot.
shot(s) ...: the reviewed face number is higher than the number of faces found there, so the last face was used
- Explanation: A manually selected index is no longer available at the frame used for that shot, often because the detector or confidence setting changed.
- Solution: Review the new
previewand choose a valid face index. If the intended face is missing, lower the confidence or use a more suitable detector.
select_index=... is out of range: at most ... face(s) were ever detected in one frame, so ... was used.
- Explanation: The requested automatic face index is higher than the number of faces detected in any single frame.
- Solution: Lower
select_indexto an available zero-based index, or improve detection if additional faces should be present.
... shot(s) contain no face at all; the tracker interpolates across those.
- Explanation: Some shots contain no accepted face in any frame. The node still returns the video, but downstream tracking must interpolate through those sections.
- Solution: Confirm that the subject is genuinely absent. If the face should be visible, lower
confidence, choose a better detector, or adjust the loaded frame range.
... shot(s) marked as not containing the subject; those frames keep their original pixels.
- Explanation: Identity matching found no face in those shots that reached
identity_threshold. Those sections are intentionally treated as not containing the reference person. - Solution: If the subject is present, lower
identity_threshold, provide a clearer reference, choose a more suitableidentity_model, or improve detection. If the subject is absent, this warning is expected.
... frames is off H3's 17k+5 grid; H3 rounds up to ... and the difference is padded, refined, then discarded.
- Explanation: The retained frame count does not match the frame-count pattern expected by H3 processing. H3 can pad the sequence internally, but the extra padded frames are later discarded.
- Solution: Adjust
frame_load_cap,skip_first_frames, orselect_every_nthso the report’s suggested count is used when practical. This avoids unnecessary padding and makes the downstream render more predictable.
