📍AGSoft Add Guide for MiniMax H3

MiniMax H3 generates video with sound baked into the same pass, and it lets you pin an image - or a short clip, or a snatch of audio - to a specific frame of the output. That pinning is the whole trick behind "start here, land there" video. ComfyUI core ships a node for it, MiniMaxH3AddGuide, and that node anchors exactly one guide per node. Want an opening frame, a mid-way beat and a final frame? You chain three nodes and count frames by hand.

AGSoft's node is the same idea with the bookkeeping done for you: up to sixteen guide slots on one node, positions in seconds or frames, and a JSON readout of where everything actually landed.

How it works

Guides don't go in as a separate sampler input. They get written into the conditioning itself, under a key called minimax_keyframes, as a list of {"resolved_frame_index": n, "latent": ..., "audio_latent": ...} entries. H3's sampler reads that list and anchors those latents at those frames. This node does the same thing core does - it reads whatever minimax_keyframes list is already on the positive conditioning and appends to it - which means the two interoperate. You can chain the core node into this one, or two of these into each other, and the guides stack instead of overwriting.

Two details explain most of the weird errors. First, the node derives pixel size from the AV latent (grid times 16) and encodes your guides with the video VAE at that resolution, center-cropped - a 16:9 guide dropped onto a 9:16 latent loses its sides. Second, guide images aren't always one frame: a batch of 5+ frames is treated as a clip and trimmed down to H3's valid clip lengths, 5, 22, 39 and onward in steps of 17 (17k+5). Batches under 5 frames use the first image only.

The inputs that actually matter

positive and latent are what you'd expect: the conditioning you're already feeding the sampler, and the AV latent from EmptyMiniMaxH3LatentAV or one of the H3 conditioning nodes. vae is the video VAE for encoding the guides.

number_of_guides (1–16) is the slot count. It does not hide the slots - it decides how many the node looks at. If you set it to 1, slots 2 through 16 are ignored even if you've wired them up. Bump it before you start wiring, not after.

position_mode flips between Seconds and Frames, and fps (default 24, which is H3's native rate) is what converts one to the other. Both seconds_N and frames_N widgets exist on every slot regardless of the mode; only the matching one is read. Either accepts -1 for the last frame, which is the sane way to nail a closing frame without computing the length yourself.

Each slot then takes image_N, optionally audio_N, and its position. Audio inputs only show up once you've wired audio_vae - that's a frontend trick from the pack's JS, not a version limit.

Two outputs. positive goes straight into your sampler where you'd otherwise be plugging the conditioning. guides_info is a JSON string listing each guide's slot, mode, value, resolved frame_idx and clip length - wire it into a Show Text or Show Any node and read it when a guide lands somewhere you didn't expect.

Install

ComfyUI Manager, search comfyui-AGSoft and install, then restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/Art-xmaster/comfyui-AGSoft
# restart ComfyUI

The pack's requirements.txt pulls numpy, opencv-python and translators. You don't need translators for this node - it's for the Translate nodes - but it installs anyway. The node lives under Add Node → AGSoft/MiniMaxH3.

Troubleshooting

"AGSoft Add Guide needs core MiniMaxH3AddGuide (ComfyUI >= 0.34.0)". This node is a wrapper, not a reimplementation: it locates the core MiniMaxH3AddGuide at import and borrows its internals. On older ComfyUI that lookup fails and the node can't run. Update ComfyUI. The flip side is that it reaches into core's private helpers, so a future core refactor can break it in a way an ordinary node wouldn't.

"latent must be a MiniMax H3 AV latent". You're feeding a plain image or video latent. H3's is a nested pair of tensors with a 24-channel video half, and only the H3 conditioning nodes produce one.

"guide #N: frame X + Y frames outside Z". Deliberately loud. Out-of-range guides error out rather than being quietly clamped to the last frame, so a guide that looks like it did nothing usually means the node threw and the graph stopped. Check the resolved index against guides_info.

Nothing happened, no error. If a slot has neither image nor audio connected, it's skipped silently - and if no slot has anything connected, the node just logs a warning and passes your conditioning through unchanged. Guides that don't appear are almost always unwired slots or a number_of_guides set lower than the slot you filled.