H3 Video Fit (source clip -> 17k+5 frames) [alpha]

H3 Video Fit is the doorway for footage you already have, and it exists because MiniMax-H3 runs on a weird ruler. The model works in 17-frame chunks, so legal clip lengths are 5, 22, 39, 56… - anything of the form 17k+5. A normal MP4 lands between those marks. And here's the kicker the README hammers home: nothing errors if you feed it an illegal length. The H3 VAE silently pads a short final chunk by repeating the last frame. Your 312-frame clip becomes 323 encoded frames, the last 11 of them frozen, the final tokens read as calm, and the jerk oracle under-dilates the end of your clip. The failure is invisible and it ruins the retiming where it matters most.

What it does

Feed it source frames (images - e.g. LoadVideo → GetVideoComponents), pick a mode, and it trims or pads the batch to the nearest legal 17k+5 count, cuts the source audio by the same amount, and outputs length - which you wire into H3 Jerk Oracle instead of typing a number.

The modes matter:

• trim tail (default) - never invents content, cuts at most 16 frames (0.67 s at 24 fps), keeps frame 0, which is the anchor every keyframe/FLF path and the audio clock reference.
• trim head - for when the action you care about is at the end.
• pad tail (freeze last frame) - makes the encoder's hidden padding explicit and visible. Prefer it only when you cannot lose the tail.
• nearest - trim or pad, whichever is closer.

max_frames (default 0 = whole clip) is the cost lever, and it's the cheapest knob in the graph: per-step time scales roughly as tokens^1.7, so capping a long source before fitting buys you a lot. fps (default 24) feeds the audio cut and the 24 fps warning - H3 has one frame rate, so a 30 fps source plays back 1.25× slower and the report output tells you so, along with the full receipt: frames in, frames out, which end lost them, token count.

Install

Ships in matlowai/ComfyUI-MAINodes:

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

Restart, under image/minimax/motion. No extra Python deps; you need MiniMax-H3 weights and ComfyUI's H3 support (check the licence's US/EU/UK/Korea carve-outs before committing). The example graphs also expect ComfyUI-KJNodes.

Where people get burned: skipping it and wiring the raw LoadVideo frames straight into the pipeline because "it runs anyway." It runs, sure - that's the trap. The silent tail freeze reads as calm to the oracle, so the end of your clip doesn't get dilated, so the smearing at the end comes back, and you spend an hour wondering why the fix worked everywhere except the last half-second. Fit the clip first.