H3 Face Track + Crop:
H3FaceTrackCrop detects and follows a face through an image or video sequence, then creates a stable crop around the selected subject for MiniMax H3 video refinement. It adjusts the crop position and size from frame to frame, smooths unwanted detector movement, and resizes every crop to one consistent canvas size required by H3. The node can follow the largest or otherwise selected face, maintain the identity of one person in a crowd, use a manually chosen face from an upstream face-selection node, detect hard cuts between shots, estimate the head position when a face temporarily disappears, and optionally skip shots where the tracked person is absent. It also creates transformation information so downstream nodes can place the refined result back into the original frames. Its main purpose is to make the face large and consistently positioned for H3 while reducing shaking, subject switching, detail loss, and incorrect face generation during occlusions or detection dropouts.
H3 Face Track + Crop Input Parameters:
images
The source image sequence or video frames to analyze and crop, using the ComfyUI IMAGE type. The frames must remain in their original order and should not be resized between this node and an upstream H3FACEPICK selection. The node detects faces across the sequence, follows the chosen subject, and returns one crop for each retained frame. There is no numeric range or default because this is a required image input.
detector
The face-detection model used to locate faces in each frame. Available options are the detector files registered under the Ultralytics face-detection folders, with face_yolov8m.pt used as a fallback option when no registered detector list is available. The detector affects which faces can be found, how reliably small or stylized faces are detected, and how much processing is required. Choose a model suited to the visual style of your footage; an anime or illustration-compatible detector is generally preferable for stylized material. This is a required model-selection input, and its exact options depend on the detector files installed in your ComfyUI model folders.
confidence
The minimum detection confidence accepted by the selected detector. The default is 0.35, with a minimum of 0.05 and a maximum of 0.95. Lower values can recover small, blurry, turned-away, or stylized faces, but they can also introduce false detections. Higher values reduce false positives but may create more missing frames and therefore more interpolation. If the report says that few faces were found, try lowering this value gradually; if unrelated objects are being detected as faces, raise it.
crop_factor
The crop side length expressed as a multiple of the detected face height. The default is 2.5, with a minimum of 1.2 and a maximum of 8.0, using steps of 0.1. A value of 2.5 makes the face occupy approximately 40 percent of the crop height, giving H3 a clear face while leaving room for hair and background. Smaller values magnify the face more but risk cutting off important context; larger values include more surroundings but reduce magnification. Values around 2.0 to 3.0 are generally the useful starting range. The crop is also adjusted to match the selected canvas aspect ratio and is constrained to stay inside the source frame.
canvas_width
The output crop width in pixels when canvas_mode is manual. The default is 768, with a minimum of 128, a maximum of 1344, and a step of 32. Larger dimensions preserve or create more detail but increase H3 processing and memory use; for example, a 768-pixel canvas uses about 2.25 times the latent-token area of a 512-pixel canvas. In automatic canvas modes this value is replaced by the size calculated from the tracked crop, so it does not determine the final canvas there.
canvas_height
The output crop height in pixels when canvas_mode is manual. The default is 768, with a minimum of 128, a maximum of 1344, and a step of 32. It controls the vertical resolution passed to H3 in manual mode and should normally be chosen together with canvas_width to match the intended output shape. In automatic modes, the node selects a square canvas based on the largest crop and this value is not used as the final height.
canvas_mode
Controls how the final crop canvas size is selected. The available options are manual, auto_no_downscale, and auto_capped_768, with manual as the default. manual uses canvas_width and canvas_height exactly as entered. auto_no_downscale sizes a square canvas from the largest crop so that no crop is downscaled before H3 receives it, which preserves source detail but can become expensive for close-ups. auto_capped_768 follows the same principle but limits the result to 768 pixels and is usually a safer memory choice. Both automatic modes enforce a minimum of 512 by 512 and snap the size to multiples of 32; manual mode does not apply that minimum.
smooth_window
The number of frames used to smooth the crop centre. The default is 21, with a minimum of 1, a maximum of 201, and a step of 2. At 24 frames per second, 21 frames represent approximately 0.9 seconds. Increasing this value reduces box shaking but can make the crop lag behind quick head movements; decreasing it follows fast movement more closely but may leave visible jitter. Use a larger value for calm talking-head footage and a smaller value for rapid movement.
size_smooth_window
The number of frames used to smooth the crop size. The default is 51, with a minimum of 1, a maximum of 201, and a step of 2. Size usually benefits from heavier smoothing than position because rapid changes make the crop appear to breathe or shimmer. Increase this value when the face repeatedly grows and shrinks due to detector noise; reduce it when the footage contains a genuine, fast push-in or pull-out.
smooth_method
The mathematical smoothing style applied to the crop centre and size. The options are gaussian, savgol, and moving_average, with gaussian as the default. gaussian generally provides the strongest jitter rejection, savgol preserves the shape of a deliberate zoom or push-in better at larger windows, and moving_average is a simple older box-style filter that may leave more residual movement. Start with gaussian for stable results, then try savgol if an intentional zoom becomes too flattened.
size_mode
Determines whether the crop size changes over time. The options are max_of_clip and per_frame, with per_frame as the default. per_frame adjusts the crop according to the detected face height so the face occupies a consistent fraction of each crop and is the correct choice for push-ins, pull-outs, and changing camera distance. max_of_clip uses one size based on the largest smoothed face measurement across the entire video and is mainly useful for genuinely static shots. The selected size is still smoothed according to size_smooth_window.
identity_reference
An optional image containing a clear face of the person you want to follow. It is read only when identity_track is enabled. When usable, it lets the node choose the intended person by visual identity instead of relying only on face size or position, which is especially useful in crowds or when another person becomes larger in the frame. The selected identity model determines whether the reference can be recognized reliably; for stylized or illustrated references, clip_vision or ccip may be more suitable than insightface. There is no default image, and the input is optional.
identity_track
Enables identity-assisted subject tracking. The default is True. When enabled, the node uses continuity as the inexpensive primary method and consults an identity embedding mainly when multiple faces are similarly plausible or overlap. If identity_reference is connected, it is used to name the intended person; otherwise, when appropriate, an identity anchor is built from clear frames within the clip. When disabled, the reference image is ignored and the node uses the selection rule instead. This option is particularly important for crowd scenes, but it may be unnecessary for a single clear face.
identity_threshold
The minimum similarity score required before an identity match is accepted. The default is 0.28, with a minimum of 0.0 and a maximum of 1.0, using steps of 0.01. The useful scale depends on identity_model: insightface commonly uses values around 0.28, CLIP Vision scores are typically much higher, and CCIP uses its own score range. Setting the value to 0 asks the selected model to use its recommended default. If the threshold is too low, the tracker may accept the wrong person; if it is too high, it will fall back to position continuity more often. The returned report prints observed scores to help you tune this setting.
select
Chooses the face when no connected identity reference determines the subject. The default is largest_face. Available options are largest_face, smallest_face, left_most, right_most, top_most, bottom_most, centre_most, closest_to_xy, and detector_score. The choice is made when the subject is first locked in a shot, after which continuity follows that face rather than re-ranking every frame. largest_face and smallest_face use face height, directional choices use the centre of the face box, centre_most uses distance from the frame centre, closest_to_xy uses the supplied X, Y, and frame_index, and detector_score uses the detector confidence. With hard-cut detection enabled, the choice is made again for each shot.
fallback_detector
An optional detector used only on frames where the face detector finds no face. The default is none; otherwise, the available options are none plus the installed Ultralytics detector names. A person or body detector can estimate a head position from the top of a detected body box, which is often better than blindly interpolating when someone turns away. It does not replace the face detector and does not identify the subject by itself; it chooses the body nearest the expected tracked position. If the fallback model is used, the preview marks those frames in yellow.
fallback_head_frac
Specifies how far below the top of a fallback body box the estimated head centre should be placed, measured as a multiple of the recent face height. The default is 0.5, with a minimum of 0.0, a maximum of 1.5, and a step of 0.05. A value of 0.5 is suitable for many rear-view or partially hidden heads. Increase it if the estimated crop sits too high on the body; decrease it if it sits too low. This setting matters only when fallback_detector is enabled and a face is missing.
select_index
Selects a numbered face from the ranking created by select. The default is 0, with a minimum of 0 and a maximum of 63. The index is zero-based, so 0 means the first face, 1 means the second, and so on. The node waits for the first frame that contains the requested ranking position, then follows that subject through the shot. If the requested index never exists, it is clamped to the largest index that was observed and the report issues a warning. This parameter is ignored when an identity reference is connected or when face_pick is supplied.
identity_model
Selects the model used for face-identity matching. The available options are insightface, clip_vision, and ccip, with insightface as the default. insightface uses ArcFace and is intended mainly for photographed human faces, but its own detector may not recognize illustrations. clip_vision uses the connected ComfyUI CLIP Vision model and works across photographs, anime, 3D, and stylized images, although it compares visual appearance rather than strict identity. ccip is designed for matching illustrated or anime characters and requires the external dghs-imgutils installation described by the node pack. The last two modes use boxes found by this node's detector, so they should be paired with a detector that recognizes the visual style.
cut_detection
Controls whether the video is divided into separate shots before tracking and smoothing. The options are none and auto, with none as the default. none treats the entire sequence as one continuous shot, which is appropriate for a single H3-generated shot. auto uses adaptive PySceneDetect analysis to find hard cuts, then resets continuity and performs smoothing and interpolation separately on each shot. This prevents the crop from sliding between unrelated scenes, but a false cut can reduce smoothing within a continuous shot. If a face_pick input is connected, its supplied shot boundaries are used instead.
cut_threshold
Controls how strongly a frame must differ from its neighbours to be considered a hard cut. The default is 3.0, with a minimum of 0.5, a maximum of 20.0, and a step of 0.25. Lower values detect more subtle cuts but can incorrectly split continuous motion; higher values detect only clearer cuts. This setting is used only when cut_detection is auto. The report lists the number of cuts and their resulting shot structure, so use that information to decide whether to raise or lower the threshold.
identity_clip_vision
An optional CLIP_VISION model connection used only when identity_model is clip_vision. Load the model with a ComfyUI CLIPVisionLoader and connect it here. Larger ViT-L or ViT-H models generally separate visually similar characters better than smaller models, but they may require more memory. This input has no effect when another identity model is selected.
absent_shots
Controls whether shots where the tracked subject is not found should be identified and excluded from rendering. The options are off and by_identity, with off as the default. by_identity samples faces in each shot and marks a shot absent when none reaches the identity threshold. Frames in such shots retain their original pixels during compositing and may be removed from the crop batch, although some absent frames may be retained as padding to satisfy H3's frame-grid requirement. Sampling is not exhaustive, so a very brief appearance can be missed. This option requires a working identity anchor.
X
The horizontal source-frame coordinate used by select=closest_to_xy. The default is 0, with a minimum of 0 and a maximum of 16384. Coordinates start at the top-left and increase to the right; for a 960-pixel-wide frame, 480 is the centre. The nearest detected face centre to this point is selected on frame_index or the closest usable frame after it. The coordinate does nothing for other selection modes.
Y
The vertical source-frame coordinate used by select=closest_to_xy. The default is 0, with a minimum of 0 and a maximum of 16384. Coordinates start at the top-left and increase downward; for a 544-pixel-tall frame, 272 is the centre. The nearest face centre to this point is selected. This value is used only with select=closest_to_xy.
frame_index
The zero-based frame on which the X and Y selection point is evaluated. The default is 0, with a minimum of 0 and a maximum of 999999. Choose a frame where the intended face is clearly visible. If the requested frame has no suitable face, the node searches forward for a frame containing the requested index and then follows the selected subject through its shot. This setting is used only with select=closest_to_xy.
face_pick
An optional H3FACEPICK result from H3 Load Video + Face Select. It supplies already-detected face boxes, confidence values, shot boundaries, and the chosen face for each shot, preventing this node from running the detector a second time. When connected, select, select_index, cut_detection, and cut_threshold are unused, and the detector and confidence inputs are generally unused unless another operation still requires them. The source frames and dimensions must match exactly; do not trim or resize the images between the face-pick node and this node.
H3 Face Track + Crop Output Parameters:
crops
A constant-size IMAGE batch containing the tracked face crops in crop order. Each crop is positioned around the smoothed subject location, resized to the selected canvas dimensions, and prepared for H3 processing. When absent shots are removed, this batch may contain fewer frames than the original input, and the corresponding source-frame mapping is stored in transform. The batch may include a small amount of padding when necessary to meet H3's required 17k+5 frame grid.
transform
An H3FACEXFORM data object describing how every crop relates to the original frames. It includes crop boxes, source and canvas sizes, source-frame indices, shot segments, absent-frame flags, detection flags, confidence weights, face rectangles in canvas coordinates, and the crop factor. Downstream stitching or compositing nodes use this information to place refined crops back into the correct original-frame locations and to fade out frames where the face was not reliably detected. This output is essential; passing only the image crops downstream is not enough to reconstruct the original sequence correctly.
preview
An IMAGE batch showing the original frames with the calculated crop rectangle drawn on top. Green outlines indicate frames with a real face detection, yellow outlines indicate positions estimated using the body fallback detector, and red outlines indicate positions filled through interpolation. When closest_to_xy is used, the selected point is also shown with a crosshair. Use this output to check whether the crop follows the intended person before spending time on H3 generation.
report
A STRING containing a detailed tracking and crop summary. It reports the selected subject and lock frame, detector and identity information, detected and interpolated frame counts, body-fallback usage, dropout runs, crop dimensions, face coverage, magnification, jitter before and after smoothing, shot cuts, absent shots, frame-grid warnings, and possible identity or selection problems. Read this output when the preview looks incorrect or when you need to tune confidence, smoothing, identity threshold, canvas size, or crop factor.
canvas_w
An integer containing the actual canvas width used for crops. In manual mode this matches canvas_width; in automatic modes it is the calculated square size, normally at least 512 and snapped to a multiple of 32. Wire this output into the corresponding H3 width setting so the generated latent and the crop batch use the same dimensions.
canvas_h
An integer containing the actual canvas height used for crops. In manual mode this matches canvas_height; in automatic modes it matches the automatically calculated square canvas. Wire this output into the H3 height setting to prevent a mismatch between the refined video dimensions and the crop dimensions.
frame_count
An integer containing the number of crop frames actually returned. It can be lower than the input frame count when absent shots are dropped, and it can differ from the original sequence even though the transform output remembers the original source-frame positions. Use this value wherever a downstream H3 or video node needs the effective crop-batch length.
H3 Face Track + Crop Usage Tips:
- Start with
confidence=0.35,crop_factor=2.5,smooth_window=21,size_smooth_window=51,smooth_method=gaussian, andsize_mode=per_frame. These settings provide a balanced starting point for most face-focused clips. - Use
identity_track=Truefor crowds, overlapping faces, or clips where the intended person is not always the largest face. For a specific person, connect a clear reference image and choose an identity model suited to the artwork style. - For photographs, try
identity_model=insightface. For anime, illustration, or 3D characters, tryclip_visionwith a connected CLIP Vision model orccipif its required package is installed. - If the subject is lost when turning away, select a suitable body or person detector in
fallback_detector. Keepfallback_head_frac=0.5initially and adjust it only if the yellow preview rectangles sit too high or too low. - Use
cut_detection=autofor montages or clips containing multiple camera shots. Leave it atnonefor a single continuous H3 shot, because unnecessary cuts can shorten the effective smoothing window. - If the crop shakes, increase
smooth_windowfor positional movement and increasesize_smooth_windowseparately for breathing or zoom-size fluctuations. If the crop visibly lags behind a fast head movement, lower the corresponding window. - Choose
smooth_method=savgolwhen a deliberate push-in or pull-out is being flattened by Gaussian smoothing. Usemoving_averageonly when you specifically prefer simpler box-style smoothing. - Use
canvas_mode=auto_no_downscalewhen preserving all available source detail is more important than memory usage. Useauto_capped_768for a safer general-purpose balance, or use manual 512 or 768 dimensions when you need predictable VRAM usage. - Watch the report for magnification below
1.0x. If crops are being downscaled into the canvas, raise the canvas size, lowercrop_factor, or reconsider processing a clip that is already a very tight close-up. - Use
select=closest_to_xywhen you know approximately where the desired person appears. SetX,Y, andframe_indexto a frame where that person is clearly visible, then inspect the preview and crosshair. - Connect
face_pickwhen you need deliberate per-shot face choices or want to avoid running face detection twice. Keep the image dimensions and frame count identical between the face-pick node and H3FaceTrackCrop. - Always inspect
previewbefore launching an expensive H3 render. Green, yellow, and red rectangles quickly show whether the node is detecting the face, using body fallback, or interpolating through a dropout. - Wire
canvas_wandcanvas_hinto the H3 width and height settings. In automatic canvas modes, do not manually override those values downstream because the crop and generated latent must agree.
H3 Face Track + Crop Common Errors and Solutions:
No face detected in any frame. Lower confidence, or this video has no usable face and should be skipped.
- Explanation: The selected detector did not find any face in the supplied frames, or every detection was rejected by the confidence threshold.
- Solution: Lower
confidencegradually, choose a detector trained for the visual style, check that the frames actually contain usable faces, and make sure the detector model is installed in an Ultralytics model folder.
Every shot is marked as not containing the subject, so there is nothing to refine.
- Explanation:
absent_shots=by_identityclassified all shots as lacking the tracked person, leaving no frames for refinement. - Solution: Set
absent_shotstooff, provide a clearer identity reference, loweridentity_threshold, select a more suitable identity model, or unmark the absent shots in the upstream face-pick workflow.
Face detector '...pt' not found in ultralytics_bbox / ultralytics model folders.
- Explanation: The detector name is available in the workflow but its model file cannot be found in the expected ComfyUI model directories.
- Solution: Install or copy the selected detector into the appropriate
models/ultralytics_bboxormodels/ultralyticsfolder, refresh the model list, and select the installed filename.
face_pick describes ... frames but ... arrived. The images and the pick have to come from the same loader.
- Explanation: The upstream face-pick data describes a different number of frames than the
imagesinput. This commonly happens after trimming, skipping, or changing the video between the two nodes. - Solution: Connect both inputs from the same video-loading chain and do not remove, reorder, or trim frames between
H3 Load Video + Face Selectand H3FaceTrackCrop.
face_pick describes ...x... frames but ...x... arrived. Every box would land in the wrong place.
- Explanation: The selected face boxes were created for different image dimensions, so their coordinates would no longer point to the correct faces.
- Solution: Do not resize the images between the face-pick node and this node. Recreate the face pick after resizing, or provide the original-size frames.
identity_model unavailable, tracking by continuity: ...
- Explanation: The requested identity backend could not be loaded or encountered a dependency or model error. The node continues with position continuity instead of stopping.
- Solution: Check the missing package or model named in the report, use
clip_visionwith a valididentity_clip_visionconnection, install the required CCIP dependencies when usingccip, or disable identity tracking if continuity is sufficient.
no face found in identity_reference by ...
- Explanation: The selected identity model could not detect a usable face in the reference image. The node may build an anchor from the video instead, which might not represent the intended person.
- Solution: Supply a clearer, larger face image with less obstruction, choose a model suited to the reference style, or use
clip_visionorccipfor stylized artwork.
identity_reference is connected but identity tracking is off, so it was not read.
- Explanation: The reference image is intentionally ignored when
identity_track=False. - Solution: Turn
identity_trackon if the reference should identify the person, or disconnect the reference and useselectandselect_indexdeliberately.
fallback detector failed: ...
- Explanation: The optional body detector could not be loaded or failed while processing missing-face frames. The main face tracking process continues without that fallback.
- Solution: Check that the fallback detector exists and is compatible, choose
noneto use interpolation, or select an installed person/body detector and try again.
... face(s) is off H3's 17k+5 grid.
- Explanation: The retained crop count does not match H3's preferred frame-count pattern, so H3 will pad the sequence with reference content before processing.
- Solution: This is a warning rather than a fatal error. If possible, use absent-shot handling or frame selection to produce a suitable count, and ensure downstream stitching uses the returned
transformso padded frames are discarded correctly.
magnification below 1.0x - their crops are DOWNSCALED into the canvas
- Explanation: Some source crop regions are larger than the selected canvas, so they are reduced before H3 receives them and later enlarged again during stitching, which can lose detail.
- Solution: Raise the canvas size to at least the reported required value, choose an automatic canvas mode, lower
crop_factor, or accept the warning when the source already contains sufficient detail.
longest dropout is ... frames
- Explanation: The face was not reliably detected or resolved for a long run of frames. The crop position is interpolated, while the composite weight fades so those frames normally retain their original pixels.
- Solution: Inspect the red preview rectangles, lower
confidence, add afallback_detector, improve lighting or source quality if possible, or reduce the clip if the subject is absent or fully turned away for too long.
select_index=... is out of range
- Explanation: The requested face number never existed in a frame with that many detections, so the node clamped the index to the largest available value.
- Solution: Lower
select_indexto a face number visible in the preview, improve detection with a lower confidence threshold, or useface_pickto choose the intended person explicitly.
select_index=... was ignored: identity_reference decides the subject
- Explanation: A connected identity reference takes priority over ranking-based face selection, so
select_indexcannot choose the subject in this configuration. - Solution: Keep the reference and tune identity tracking if it identifies the correct person, or disconnect the reference and use
selectplusselect_indexfor ranking-based selection.
shot(s) ... hold a different face from the rest, so they were left out of the identity anchor.
- Explanation: The manually chosen face in one or more shots did not match the identity used by the majority of selected shots, so those shots were excluded from the shared identity anchor.
- Solution: Review the upstream face picks, choose the same person in every shot, use a clearer identity reference, or rely on continuity when the shots do not contain the same subject.
cut detection unavailable, treating the video as one shot: ...
- Explanation: PySceneDetect could not be loaded or failed during automatic cut analysis. The node safely continues without splitting the sequence.
- Solution: Install or repair the scene-detection dependency, set
cut_detection=noneintentionally, or provide shot boundaries throughface_pick. If the sequence contains hard cuts, inspect the preview for tracking across the joins.
shortest shot is ... frames, under the ...-frame smoothing window
- Explanation: A detected shot is shorter than the selected smoothing window, so it cannot receive as much smoothing as longer shots and may appear less stable.
- Solution: Lower
smooth_windowandsize_smooth_window, raisecut_thresholdif the split was incorrect, or review the detected shot boundaries.
absent_shots=by_identity needs a usable identity anchor; ignored
- Explanation: The node was asked to find absent shots, but no identity reference or usable clip-derived identity anchor was available.
- Solution: Connect a clear
identity_reference, enableidentity_track, select a working identity model, or leaveabsent_shotsset tooff.
The crop and AV latent would disagree
- Explanation: The actual canvas chosen by the node does not match the dimensions used by the downstream H3 latent or video settings.
- Solution: Connect
canvas_wandcanvas_hdirectly to the corresponding H3 width and height inputs and avoid manually replacing them when using an automatic canvas mode.
