ComfyUI MiniMax H3 Director: multi-segment audio-video control for the official MiniMax-H3 nodes

The problem MiniMaxH3Director solves: one node instead of a hand-wired graph

The official MiniMax-H3 nodes generate a clip. They do not plan a sequence of clips, keep a shared set of reference images across shots, or carry motion from the end of one shot into the start of the next. Doing that by hand in ComfyUI means duplicating the conditioning, sampling and decode chain once per segment and reconnecting everything whenever the shot count changes.

MiniMaxH3Director is a single node that holds the segment plan. The README describes it as a director console that integrates segment planning, conditioning encoding, sampling, decoding and export. Underneath it still runs the official path: MiniMaxH3ImageToVideo or MiniMaxH3ReferenceToVideo, then MiniMaxH3SigmaShift, then KSampler, then separated audio and video decode. The node does not replace the official pipeline, it wraps it.

The audience is narrow and specific. You need ComfyUI v0.30.0 or newer with the official MiniMax H3 nodes already present, both UNET variants downloaded, and enough VRAM for a 32B text encoder. If you are generating one five-second clip at a time, this node adds UI you will never open.

How the director node drives the MiniMax-H3 sampling chain

The node takes model, video_vae, audio_vae and clip as required inputs. The clip loader type must be set to minimax, which the README identifies as Qwen3-VL. Task type decides which UNET you must load: t2v, i2v and fl2v use the fl2va UNET, while r2v, v2v and rv2v use ref2va. That split is not a suggestion; the two UNET files are listed separately in the recommended model table.

Outputs are images, audio, fps, frame_count, source_images, report and images_pre_refine. Audio is generated in the same sampling pass as the picture and is stereo. The report output carries the segment plan and a per-segment task summary, which matters when a decode fails: the README states that a failed decode is named in the report and produces a grey placeholder rather than passing something off as generated footage.

Two optional inputs extend the graph. i2v_groups and r2v_groups accept external group nodes (Director Group (Image to Video) or (Reference to Video), combined with Groups Combine); when connected, the README says external material overrides the UI material. A refine input accepts the separate MiniMax H3 Director Refine node. With nothing connected to refine, sampling happens once. With it, refine means same-resolution re-sampling, upscale enlarges to the target canvas before a second pass driven by SIGMAS, and latent_upscale enlarges only the H3 latent without a second pass. The passes setting allows repeated refinement, though upscale only enlarges once.

Segment-to-segment guidance is off by default. When enabled on multi-segment runs, the tail motion (and generated audio) of the previous segment is pinned into the next segment's sampling and the prefix is trimmed away. Context frame counts are 5, 22, 39 or 56, with 22 given as the default recommendation. The README credits ComfyUI-H3-Motion-Context for the implementation idea.

Installing MiniMaxH3Director and running the t2v example

The prerequisite is a ComfyUI build at v0.30.0 or above that already loads the official MiniMax H3 nodes. Upgrade ComfyUI first; the custom node will not bring those with it.

Manual install clones into custom_nodes and installs the Python dependencies:

cd ComfyUI/custom_nodes
git clone https://github.com/AIMixer/ComfyUI_MiniMaxH3_Director.git
pip install -r ComfyUI_MiniMaxH3_Director/requirements.txt

Restart ComfyUI afterwards. The alternative route is ComfyUI Manager, choosing Install via Git URL and entering the same repository URL, then restarting.

Dependencies are modest and mostly optional in practice. requirements.txt pins opencv-python-headless for v2v source decode, imageio-ffmpeg for source-audio extraction and incremental segment mp4 encoding, and scenedetect between 0.6.4 and 0.8 for smart shot splitting. The NVIDIA VSR upscale path is deliberately not a hard dependency; the file comments that adding it would break AMD, cloud and no-VSR installs, and points to pip install nvidia-vfx --extra-index-url https://pypi.nvidia.com.

For a first real run, load one of the bundled workflows from example_workflows/ rather than building the graph. minimax_h3_director_t2v.json uses task_type t2v and the fl2va UNET. Connect the model, video_vae, audio_vae and clip inputs, set the CLIP type to minimax, edit the timeline and prompts inside the node UI, then queue. The README's default sampling parameters are a 0.4MP 16:9 canvas (864x480), 5 seconds or 124 frames at 24 fps, 25 steps with res_multistep and simple, CFG 1.0, and sigma shift 12 for video against 3 for audio.

Where the design gets awkward: packs, UNET pairing and the fl2v empty-group rule

The director pack format is the clearest example of a trade-off. Export writes a .mmxpack.zip containing timeline.json, pack.json, shared_params/ and asset_groups/01/ and so on, with slot filenames like Picture1.png, Video1.mp4 and Audio1.wav. The README is explicit that paths are ASCII and match the English UI regardless of the language you are using, which avoids path encoding problems but means a Chinese-language user sees English folder names in the archive. Slot numbering also follows the UI: if shared params occupy Picture 1 to 3, group folders continue from Picture4, and renaming the first group image to Picture1 breaks the mapping. Packs do not contain UNET, CLIP or VAE weights, so a pack is portable only to a machine that already has the models.

The UNET pairing is a second constraint. A project that mixes r2v or v2v shots with t2v or fl2v shots in one timeline needs both minimax_h3_fl2va_pruned_int8_convrot.safetensors and minimax_h3_ref2va_pruned_int8_convrot.safetensors in models/diffusion_models/. If you only downloaded one, half the task types are unavailable.

Segment-to-segment guidance has its own failure mode. It is off by default, and the README frames it as usable only on multi-segment runs. The mechanism pins the previous segment's tail frames into the next segment and trims the prefix afterwards. That is a real cost per segment, and the choice of context frame count (5, 22, 39, 56) is left to you with 22 as the stated recommendation. There is no documented automatic selection, and the README does not document what happens when a segment is shorter than the pinned context.

MiniMaxH3Director against wiring the official nodes by hand

The honest alternative is the official MiniMax-H3 nodes used directly, with one conditioning and sampling chain per shot, stitched in whatever video compositor you already use. That approach has no extra dependency, no pack format to learn, and no custom node to keep in step with ComfyUI releases. It also has no shared reference pool: if the same character has to appear in eight shots, you re-upload the reference image eight times and hope the conditioning is consistent.

The difference in approach is where the state lives. Hand-wiring keeps state in the graph, so the shot plan is visible as nodes and wires and can be edited with standard ComfyUI tooling. MiniMaxH3Director keeps state inside the node UI and serialises it to timeline.json inside a pack. That makes a twenty-shot plan editable in one place and portable as a zip, but it also means the plan is opaque to anything that reads the graph rather than the node's own interface. External group nodes (i2v_groups, r2v_groups) are the middle path: they let other parts of the graph feed material in while the director node still owns the timeline, and the README notes external material takes priority over what is set in the UI.

Maintenance, licence and what an upgrade actually costs you

The repository is not archived and the last push was on 2026-09-16. There are no retrieved releases, so version 1.0.0 in pyproject.toml is the only version marker visible. Installation is from Git, which means upgrading is a git pull in custom_nodes/ComfyUI_MiniMaxH3_Director followed by re-running pip install -r requirements.txt if the dependency file changed.

The upgrade cost is dominated by the ComfyUI floor, not by this node. pyproject.toml declares requires-comfyui = ">=0.30.0", and the README ties that floor to the official MiniMax H3 nodes landing in ComfyUI. A ComfyUI upgrade that changes the official node signatures or the MiniMax H3 model layout is the realistic breakage path here, because the director node sits on top of those nodes rather than reimplementing them. The README does not document a rollback procedure for a pack import that overwrites the current timeline, though it does state that import asks for confirmation first.

Licensing is Apache-2.0 per the repository, with the licence text in LICENSE and referenced from pyproject.toml. That covers this plugin. It says nothing about the MiniMax H3 model weights, which are downloaded separately from the sources the README lists, and those carry their own terms. Check the model licence before any commercial use; nothing here is legal advice.

Editorial conclusion

Adopt it if you already run the official MiniMax-H3 nodes and your bottleneck is shot planning rather than sampling. Skip it if you are on ComfyUI below v0.30.0, or if you want a single-shot generator with no timeline. Verify first that you have both UNET variants, the CLIP type set to minimax, and that your ComfyUI build actually exposes MiniMaxH3ImageToVideo and MiniMaxH3ReferenceToVideo.

Frequently asked questions

Official sources

1. AIMixer/ComfyUI_MiniMaxH3_Director on GitHub
2. Issues
3. License: Apache-2.0
4. README