CoachBate Load H3 Video Path

H3 reference videos, driven from the shotlist

MiniMax H3 can take video references, and the one place that gets awkward is a per-shot pipeline: each shot's reference is a different file with different clip settings, and you can't re-point a file-picker widget from JSON on every run. CoachBate Load H3 Video Path solves it by making the path and the settings inputs - two strings, video_path and settings_json - and returning frames, audio and frame_count.

It's the decode half of the pack's dynamic-reference design: the shot loader emits h3_ref_video_1…h3_ref_video_3 as path strings plus a matching settings JSON string per slot, and you pair each one with a node of this type and wire its frames into the corresponding H3 reference video slot. Blank path, no decode, no frames - that's the contract, and it's why a shotlist where only shot 7 uses a reference video doesn't have to do anything special for the other thirty-nine.

It really is Video Helper Suite underneath

This is not a reimplementation. The node resolves your path, then calls VideoHelperSuite's VHS_LoadVideoPath with your settings merged over its defaults, so frame rates, format handling and the decoded timeline behave exactly as they do in a VHS node - which matters a lot, because everything downstream (latent frame counts, audio grid alignment, the 24fps assumptions in the shot pipeline) depends on the decoder agreeing with itself.

The settings are validated strictly, and settings_json rejects keys it doesn't know. What it accepts:

{
  "force_rate": 24,
  "custom_width": 640,
  "custom_height": 0,
  "skip_first_frames": 48,
  "frame_load_cap": 107,
  "select_every_nth": 1,
  "format": "None",
  "include_audio": false
}

Same meaning as VHS: force_rate is the resampled FPS (0 keeps source FPS), skip_first_frames skips at that rate, select_every_nth is the stride, frame_load_cap limits the decoded selection (0 = no cap), zero width/height keeps source dimensions, and format has to name a format your VHS install actually has - None avoids format-specific frame constraints. Source audio is disconnected unless include_audio is true. That default is deliberate: a reference video's audio is usually not the reference audio you want the model matching.

frame_count is handy for the arithmetic the shot pipeline is full of - how many frames you just handed a model that generates in 17k+5 chunks.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/CoachBate/ComfyUI-CoachBate.git

ComfyUI Manager users: search "CoachBate", install, restart. Category is CoachBate / H3. You need ComfyUI-VideoHelperSuite installed - this node calls into it and raises "H3 video references require VideoHelperSuite" if it's missing. The pack declares no pip dependencies of its own; ultralytics and Impact-Subpack matter for the tracking nodes, not this one.

Where people get burned

• "Unknown video reference settings: […]" - a typo'd or extra key in settings_json. It's an allow-list, not a merge-anything object.
• "Unknown installed VHS format: …" - format names something VHS doesn't have on your machine. Use "None" unless you specifically need a format constraint.
• "No reference frames decoded from selected clip" - your skip_first_frames plus frame_load_cap combination landed past the end of the file, so VHS returned nothing. This is the single most common mistake when copying a settings block from another shot.
• The path isn't found. Relative paths resolve under ComfyUI's output folder; absolute paths are accepted, and surrounding quotes are stripped. Relative is the one that surprises people.