CoachBate H3 Subject Track + Crop:
CoachBateH3SubjectTrack follows a selected face through a sequence of video frames and creates a smoothly moving crop around it. As the face appears larger or smaller in the source, the crop can change size so the subject occupies a more consistent portion of the image. The node then resizes every crop to one canvas size for H3 processing and records how each crop relates to its original frame, allowing a downstream workflow to place the refined result back where it belongs. It can separate hard-cut shots, smooth tracking without blending movement across cuts, and reduce the effect of frames where the face was not reliably found.
CoachBate H3 Subject Track + Crop Input Parameters:
images
The source video frames as an IMAGE batch. The node detects faces in these frames, tracks the chosen subject, and makes one crop for each frame it retains. Frame positions used by the selection controls refer to this incoming batch, not necessarily to the original video file if an upstream loader skipped frames. There is no numeric default or range.
detector
The face-detection model used to find candidate faces in the frames. Choose from the models listed in the detector menu; the available names depend on the models installed in your setup. The list falls back to face_yolov8m.pt if no registered model names are found, but that file must still exist when the node tries to load it. A suitable face detector is essential: tracking and crop placement depend on its boxes. There is no fixed numeric range.
confidence
The minimum detector confidence accepted for a face: default 0.35, minimum 0.05, maximum 0.95, in steps of 0.05. Lowering it can recover small or difficult faces, but may admit false detections; raising it rejects uncertain boxes, but can create more gaps in the track. If no faces are found, try lowering this value.
crop_factor
Sets crop size as a multiple of the detected face-box measurement chosen by crop_size_from: default 2.5, minimum 1.2, maximum 8.0, in steps of 0.1. At 2.5, the measured subject dimension occupies roughly 40% of the crop before limits imposed by the source frame. A larger value includes more hair and background but makes the face smaller on the H3 canvas; a smaller value magnifies the face while leaving less surrounding context. The node’s guidance identifies roughly 2.0–3.0 as a useful range.
canvas_width
The crop batch’s output width in pixels when canvas_mode is manual: default 768, minimum 128, maximum 1344, in steps of 32. A wider canvas can retain more output resolution but increases processing cost. In either automatic canvas mode, this setting is replaced by a square size calculated from the crops; connect the resulting canvas_w output to the downstream H3 width setting rather than assuming the value entered here will be used.
canvas_height
The crop batch’s output height in pixels when canvas_mode is manual: default 768, minimum 128, maximum 1344, in steps of 32. Along with canvas_width, it determines the canvas shape and therefore the crop’s aspect ratio. Automatic modes replace both dimensions with the calculated square size. Connect canvas_h to the downstream H3 height setting so its canvas matches these crops.
canvas_mode
Controls how the fixed output canvas is sized; options are manual (default), auto_no_downscale, and auto_capped_768. manual uses canvas_width and canvas_height exactly as entered. Both automatic modes size a square canvas from the largest crop, round it to a multiple of 32, and keep it between 512 and 1344 pixels; auto_capped_768 additionally caps it at 768. auto_no_downscale is intended to avoid shrinking source crops before H3, but may be expensive when a clip includes close-ups. The capped mode limits that cost, though large crops can then be downscaled.
smooth_window
The smoothing window for crop position, measured in frames: default 21, minimum 1, maximum 201, in steps of 2. Increase it if the crop centre visibly shakes from frame to frame; decrease it if the crop is slow to follow rapid movement. Smoothing is performed separately for each detected shot, so a shot shorter than the window receives less smoothing.
size_smooth_window
The smoothing window for crop size, measured in frames: default 51, minimum 1, maximum 201, in steps of 2. Size changes can look like the image is repeatedly zooming in and out, so this defaults to a longer window than position smoothing. Increase it to calm size jitter, or reduce it if genuine changes in subject scale are being followed too slowly. Like position smoothing, it does not smooth across detected shot boundaries.
smooth_method
The method used to smooth crop position and size; options are gaussian (default), savgol, and moving_average. gaussian is the recommended starting point for rejecting detection jitter. savgol can better preserve the shape of an intentional push-in with a large window. moving_average is a simpler boxcar approach that may leave more visible jitter.
size_mode
Controls whether crop size changes with the subject; options are per_frame (default) and max_of_clip. per_frame uses the smoothed face size in each frame so the subject stays at a more consistent fraction of the crop, including during push-ins. max_of_clip applies one size across the entire clip, which is mainly useful for a genuinely static shot; if the face changes scale, it will no longer fill the crops consistently.
select
The rule for choosing a subject when tracking locks on. The default is largest; supported modes described by the node are largest, smallest, left_most, right_most, top_most, bottom_most, centre_most, closest_to_xy, and detector_score. Size modes rank face-box height; directional modes use box centre; centre_most uses distance from frame centre; closest_to_xy uses your specified point; and detector_score uses detection confidence. The chosen rank is not recalculated to switch subjects every frame: tracking follows the selected face by position continuity. With cut detection on, each shot can choose again; with it off, the whole clip is treated as one shot.
cut_detection
Controls automatic hard-cut handling; options are none (default) and auto. Use none for a single continuous shot. auto attempts to find cuts and keeps tracking resets, smoothing, interpolation, and composite-weight fades within each shot rather than carrying them across an edit. Automatic cut detection uses PySceneDetect when available; if it is unavailable, the node reports that it is treating the video as one shot.
cut_threshold
The sensitivity of automatic cut detection: default 3.0, minimum 0.5, maximum 20.0, in steps of 0.25. It is used only when cut_detection is on. Lower values catch more potential cuts but can split continuous motion into short shots; higher values accept only more distinct changes. Check the report’s cut count and locations when adjusting it.
select_index
Which face to take from the ranking specified by select: default 0, minimum 0, maximum 63. 0 selects the first ranked face, 1 the second, and so forth. The node waits for a frame containing enough detected faces to make that rank available, then follows its choice; earlier unresolved frames are interpolated and given reduced composite weight. If the clip never contains that many faces at once, the index is clamped and the report warns you.
crop_size_from
Selects the face-box dimension on which crop_factor is based; options are height and longest_side (default). height is appropriate for a roughly upright, square face and avoids changes in face width as the head turns. longest_side uses whichever smoothed box dimension is larger, helping keep a sideways subject within the crop.
select_override
An optional text replacement for select; default is an empty string. When it contains non-whitespace text, the node uses that text as the selection mode instead of the select menu choice. This allows an upstream loop to drive subject choice each round. Leave it blank for normal menu-based selection, and use a supported selection-mode name when setting it.
X
The horizontal coordinate, in pixels of the incoming source frame, used only with select=closest_to_xy: default 0, minimum 0, maximum 16384. It is measured from the left edge; for example, 480 is the horizontal midpoint of a 960-pixel-wide frame. The nearest detected face-box centre is chosen even if the point is not directly on a face. Other selection modes ignore this value.
Y
The vertical coordinate, in pixels of the incoming source frame, used only with select=closest_to_xy: default 0, minimum 0, maximum 16384. It is measured downward from the top edge; for example, 272 is the vertical midpoint of a 544-pixel-high frame. Set it together with X to identify a subject at a particular moment. Other selection modes ignore it.
frame_index
The frame on which X and Y are intended to identify the subject, counting the first incoming frame as 0: default 0, minimum 0, maximum 999999. It is used only with select=closest_to_xy. Choose a frame where the desired face is clearly detectable; if the requested frame has no suitable detection, the node searches for a usable lock-on frame. The report states both the requested frame and the frame actually used.
CoachBate H3 Subject Track + Crop Output Parameters:
crops
An IMAGE batch of tracked-subject crops, all resized to the same canvas dimensions for H3. Crop position and source area can vary by frame while the output image size remains fixed. Usually there is one crop per source frame, but the node can omit frames marked as absent in its internal processing; use frame_count and transform rather than assuming the batch always has the incoming length.
transform
An H3FACEXFORM record describing how the crops relate to the original frames. It includes their source-frame positions, crop boxes, canvas and source dimensions, shot segments, and per-frame information such as detection status and composite weights. Pass it to the compatible downstream stitching workflow so a refined crop can be placed back on the correct frame and its effect can be reduced where the face was not reliably detected.
preview
An IMAGE batch showing crop rectangles over the original frames so you can inspect what the tracker followed. Green rectangles indicate a resolved face detection; red rectangles indicate an interpolated crop without a resolved face. When closest_to_xy is used, a crosshair also shows the chosen point. This is a tracking check, not the resized crop batch or the finished composite.
report
A STRING summary of the run. It identifies the selection and lock-on frame, counts detected and interpolated frames, reports cuts and dropouts, and shows crop size, magnification, and before-and-after jitter measurements. Read its warnings when a subject looks wrong: it can flag an out-of-range select_index, short shots, long detection gaps, off-grid H3 frame counts, or crops downscaled into the canvas. The same report is printed to the console.
canvas_w
The actual output canvas width as an INT. In manual mode it matches canvas_width; in an automatic mode it is the width calculated by the node. Wire it to the downstream H3 width setting so the generation canvas agrees with crops.
canvas_h
The actual output canvas height as an INT. In manual mode it matches canvas_height; in an automatic mode it is the height calculated by the node. Wire it to the downstream H3 height setting so the generation canvas agrees with crops.
frame_count
The INT number of frames in crops. It may be smaller than the incoming IMAGE batch if absent frames were dropped during processing. Use this rendered-frame count where a downstream node needs the crop sequence length; the transform retains the mapping to source frames.
CoachBate H3 Subject Track + Crop Usage Tips:
- Start with
crop_factor=2.5,size_mode=per_frame, and the default smoothing windows. Inspectpreviewto confirm the rectangle stays on your intended face before running a longer H3 refinement. - If the wrong person is chosen in a group, change
selectandselect_indexto identify them at lock-on. For a subject who is easiest to identify later in the clip, useclosest_to_xywithX,Y, andframe_indexset on a clearly visible frame. - Use
cut_detection=autofor edited footage with hard cuts, then check the reported cuts. If it splits continuous action, raisecut_threshold; if it misses an obvious cut, lower it. Keepnonefor a single continuous shot. - If the crop shakes, raise
smooth_window; if its scale appears to pulse, raisesize_smooth_window. If tracking trails fast movement, shorten the position window. Very short shots cannot benefit fully from long smoothing windows. - Compare the report’s magnification values before refining. If it warns that crops are downscaled, raise the manual canvas size, try
auto_no_downscaleif resources allow, or lowercrop_factor. Always connectcanvas_wandcanvas_hto the downstream H3 dimensions, especially in an automatic mode. - If sideways poses are clipped, retain
crop_size_from=longest_sideor increasecrop_factorfor more room. Check the preview afterward: a larger crop also makes the face smaller on the output canvas.
CoachBate H3 Subject Track + Crop Common Errors and Solutions:
Detector '…' not found in ultralytics_bbox / ultralytics model folders.
- Explanation: The selected detector weight file could not be located. A name appearing as a fallback in the menu does not guarantee that its file is installed.
- Solution: Install a compatible face-detector model in a folder searched by the node, or choose an installed detector from the menu, then rerun.
No subject detected in any frame. Lower confidence, or this video has no usable subject and should be skipped.
- Explanation: The node found no face boxes, or could not resolve a subject from the available detections.
- Solution: Lower
confidenceand check that the chosen detector is suitable for the footage. Use a clip where the subject’s face is visible enough to detect; skip footage with no usable subject.
cut detection unavailable, treating the video as one shot: …
- Explanation: Automatic cut detection could not start, so the node continues as though the clip were one continuous shot. Tracking and smoothing may therefore carry across a real edit.
- Solution: Check that PySceneDetect is installed and working if you need automatic cuts. For genuinely single-shot footage, set
cut_detection=none.
select_index=… is out of range: at most … subject(s) were ever detected in a single frame, so index … was used instead.
- Explanation: No frame contained enough detected faces to supply the requested ranking position. The node clamped the index rather than stopping.
- Solution: Lower
select_index, lowerconfidenceif faces are being missed, or inspect the preview to verify which detected person the clamped index selected.
… frames before the lock-on contain fewer than … subjects, so they are interpolated from frame … and faded out of the composite.
- Explanation: The requested
select_indexwas unavailable near the start of the clip. The node could not confidently assign those earlier faces to your chosen subject. - Solution: Choose a lower index if the early frames matter, or check that the later lock-on identifies the right person and accept the reduced refinement before it.
… rendered frame(s) is off H3's 17k+5 grid.
- Explanation: The crop count does not match H3’s frame-length grid. The report says how many extra frames H3 will pad with reference content; those extra results are discarded during stitching.
- Solution: Use
frame_countwhen configuring downstream processing and review the reported padding. If you control the source clip length, prepare a length that fits the stated grid to avoid unnecessary processing.
… frames (…) have magnification < 1.0x - their crops are DOWNSCALED into the canvas, losing real detail.
- Explanation: Some source crops are larger than the chosen canvas, so they lose detail before refinement.
- Solution: Raise the manual canvas dimensions toward the size suggested in the report, try
auto_no_downscaleif your resources permit, or reducecrop_factor. For a close-up throughout, consider whether cropping provides a benefit.
longest dropout is … frames … The crop box is linearly interpolated across it, so it may drift …
- Explanation: The selected face was unresolved for an extended stretch. The crop position is estimated through the gap, while the composite weight fades down to favor the original frames.
- Solution: Examine that stretch in
preview. If the face is visible but missed, try loweringconfidenceor using a more suitable detector; otherwise, expect limited refinement while the face is hidden.
shortest shot is … frames, under the …-frame smoothing window …
- Explanation: At least one detected shot is too short to receive the full requested smoothing, so its crop may shake.
- Solution: Shorten
smooth_windowandsize_smooth_windowfor this clip. If the split is incorrect, raisecut_thresholdand check the reported cuts again.
lost: … frame(s) held subjects but none within reach of the subject (…) - left unresolved
- Explanation: Faces were detected in those frames, but none was close enough to the tracked subject’s previous position to be accepted as the same person.
- Solution: Inspect the listed frames in
previewfor a fast move, occlusion, missed detection, or wrong initial selection. Adjust your subject choice or detector settings as appropriate; the node leaves these frames unresolved rather than confidently switching to another face.
