MiniMax Ref Guide

If MiniMaxRefDirector is the script, MiniMaxRefGuide is the production crew. It sits inside a loop - the README's reference workflow uses Easy-Use's forLoop - and on each pass it pulls one segment out of the director's guide_data, builds the MiniMax H3 reference-to-video conditioning for that shot, and hands you a positive conditioning and a latent. You do the actual sampling yourself: KSampler → VAEDecode → VHS VideoCombine, with your own model, clip, and VAEs connected. The Guide is the brain; you're the hands.

Three inputs matter on first setup. guide_data is required, straight from the Director node. clip and video_vae are effectively required too - the code raises if either is missing, since encoding the positive and the latent is the node's whole job. audio_vae only becomes mandatory once a segment actually has reference audio. The rest are optional, and one of them you should deliberately not touch: guide_index. The tooltip makes the case bluntly - leave it disconnected and the node auto-advances through segments in order, because Easy-Use's loop expansion re-executes loop-body nodes and produces jumbled indices like 0,0,1. When in doubt, disconnect it.

Outputs are positive (CONDITIONING), latent (LATENT), plus trim_frames and frame_rate that you'd feed to your video-combine node so each clip comes out the right length. Model and seed are passed through and only recorded/logged, so reproducibility lives in your KSampler's seed, not here.

The clever part is how it ends a run. The Director wires segment_count + 1 as the loop total, so there's one extra iteration after the last real segment. On that pass the Guide doesn't fail - it returns a blocking output (ExecutionBlocker) that stops the sampler chain without an exception, after using the round to notify the Director's front-end that the previous clip is done. That's how generated videos automatically back-fill into the timeline's material track.

Which brings up motion context, the feature that makes this more than a for-loop wrapper. Pass the previous segment's saved video path into prev_tail and, on text segments that have motion context enabled (guideStrength > 0), the node decodes the tail frames of the prior clip and feeds them to H3's motion-context path so the next shot starts from where the last one ended - the cross-segment continuity trick that keeps a character and a scene feeling like one take. That integration expects ComfyUI-H3-Motion-Context to be installed (the README points at niuro3's repo); without it, that part of the chain will throw. context_length (default 22) controls how many tail frames are used as reference.

Installation is the shared pack story: ComfyUI Manager or git clone https://github.com/eaglering/MiniMaxRefDirector-ComfyUI into custom_nodes, pip install -r requirements.txt (only PyAV is extra), restart. Reminder that this is a young pack with no community trail yet - if a segment errors, check that every segment actually has a prompt and a valid durationFrames (a zero-length segment raises), and that your clip/VAE wiring is complete, before hunting bugs in the pack.