MiniMax Ref Combine

MiniMax Ref Combine is the unglamorous end of the MiniMaxRefDirector pipeline: it's the node that turns a finished H3 generation into a real video file on disk. In a multi-shot "director" workflow it does one more job that's easy to miss - it hands the file path to the next segment so the shots can keep continuity. Not a show-off node. The one you can't skip.

What it actually does

The pack builds H3 reference-to-video clips shot by shot, and Combine is the output stage. Feed it either decoded frames or the raw H3 latent, and it saves the result and returns a single Filename string - that output wires straight into MiniMaxRefGuide's prev_tail input, which is how the workflow implements motion context (the tail of one clip becoming the reference for the next). If you've ever been confused about how those shots chain together, this is the hinge: Combine produces the file, Guide eats the path.

Pixel path vs latent path

The node has two modes and picks one based on what you feed it:

• Pixel path - wire images (the [B,H,W,C] frame tensor, usually straight from VAEDecode) plus an optional audio track. It muxes them into a video file. This is the classic VHS-style combine.
• Latent path - wire the joint H3 latent (video + audio packed as a NestedTensor) instead. Now it saves the latent as image_latent safetensors plus a sidecar meta and a clip_audio wav. That's the "lossless merge" material: keeping the latent instead of a re-encoded MP4 means the final assembly (the material strip's merge, crossfading in latent pixel domain and concatenating audio) doesn't pay a second generation-quality tax. Hook up video_vae and it decodes frames and encodes a video anyway; no clip audio? audio_vae decodes the latent audio stream as the fallback.

If latent is provided, latent path wins. Otherwise pixel path.

The inputs that matter

You won't set most of these by hand - the ones that matter connect from MiniMaxRefGuide automatically:

• images or latent - pick your lane.
• audio - the clip's audio track, preferred as the muxed audio.
• frame_rate (default 24) and format (default video/h264-mp4) - what your output file is.
• trim_frames (default 0) - how many motion-context guide frames to cut off the decoded frame head. It synchronously trims the audio head too so A/V stays aligned.
• context_frames (default 39) - the segment's context guide frames, H3's run grid (5/22/39/56…; AV-aligned suggests 39/90/141). Written into the meta for lossless merge, so let it auto-populate from Guide.
• filename_prefix, save_output, pingpong, loop_count - self-explanatory plumbing. Leave them.

Install

It ships inside MiniMaxRefDirector, so install the pack:

cd ComfyUI/custom_nodes
git clone https://github.com/eaglering/MiniMaxRefDirector-ComfyUI
cd MiniMaxRefDirector-ComfyUI
pip install -r requirements.txt   # just `av`

Restart ComfyUI. ComfyUI Manager can also find it by searching "MiniMaxRefDirector". Two extra pieces matter for this node specifically: VideoHelperSuite is a soft dependency - installed, you get audio tracks and every container format; missing, Combine falls back to plain ffmpeg without audio. And the pack (since v3.1.1) expects the ComfyUI-H3-Motion-Context-MultiRef companion for the cross-shot chaining, so grab that too. One legit catch before you run anything: H3's community license geofences the weights out of the US, EU, UK and South Korea - this node is just the workflow glue, but the model underneath isn't licensed everywhere.

Troubleshooting

• Output has no audio. First suspect: VHS isn't installed, so you're on the ffmpeg fallback. Install VideoHelperSuite and re-check.
• Long segments choke. VHS' GPU encode OOMs easily on long clips, so the pack skips straight to local ffmpeg once a segment exceeds roughly 96 frames. If your output suddenly loses audio on a long shot, that's why.
• trim_frames warnings. If trim is bigger than the available frame count the node just skips the trim and logs a warning - annoying mid-batch, harmless.
• Motion context TypeError: apply() got an unexpected keyword argument 'encode_mode'. You've still got the old ComfyUI-H3-Motion-Context installed; remove it or rename it .disable. The pack now only talks to the MultiRef variant.

It's not glamorous, but it's the node that turns all that H3 generation into files you can actually keep - and the thing keeping your shots from jumping like a bad cut.