ComfyUI-MiniMaxH3-Director

The H3 Director plans a video of any length shot by shot and renders it with MiniMax H3 as render parts that continue into each other in picture and sound — a minute-long music video, a story with recurring characters and their voices, shots that start on your own pictures.

Coming from 0.3.x? Your workflows keep working: the timeline Director is still there as MiniMax H3 Director (Legacy). The new H3 Director sits next to it under MiniMax H3 → NG.

Highlights

• Studio in the node: prompt, look, shots on a timeline, audio lanes, a control lane, every setting under the gear.
• Cards for pictures, videos, sounds and notes; characters stay recognizable (References), voices and locked songs.
• Pictures output, Storyboard node with Qwen Image 2.1 drawing, Control videos (pose, canny, depth, inpaint).
• Nine example workflows in ComfyUI's Templates (search "H3 Director"), each with its example files and its chapter of the guide.
• H3 Guide node and GUIDE.md; SKILL.md so an AI agent can install the pack and help when something goes wrong.
• Technical report on planning, continuation and the measurements behind it: docs/paper.

The example videos

The wfN_*.mp4 files below are what each example workflow made when it was opened from Templates and run through the interface, unchanged except for choosing the local model files. The guide was followed step by step, and what went wrong on the way was fixed before this release (see CHANGELOG).

Install

ComfyUI Manager: search "MiniMax H3 Director". Or download Source code (zip) below, unpack it into ComfyUI/custom_nodes/, run python -m pip install -r requirements.txt with ComfyUI's Python and restart ComfyUI. Needs ComfyUI ≥ 0.37.0. Models: see the README; ComfyUI offers missing files when a workflow opens.

Known limits

• Tested on one machine (RTX 5060 Ti 16 GB, Windows, ComfyUI 0.42); other GPUs and Linux/macOS are untested.
• Generated sound loses some brightness over many render parts; a locked song does not.
• A control video steers the movement, but the shot text wins where they disagree (in workflows 7 and 8 the figure keeps walking away when the person in the source turns back).
• Most measurements are single-seed.

Please report problems as issues with the console traceback and the workflow JSON.

v1.0.0-beta.1 — H3 Director: videos of any length (pre-release)

This is a pre-release for testing. ComfyUI Manager and the Registry still install 0.3.2 (the Legacy timeline Director) until 1.0.0 is final.

The H3 Director plans a video of any length shot by shot and renders it with MiniMax H3 as render parts that continue into each other in picture and sound — a minute-long music video, a story with recurring characters and their voices, shots that start on your own pictures.

Highlights

• Studio in the node: prompt, look, shots on a timeline, audio lanes, a control lane, every setting under the gear.
• Cards for pictures, videos, sounds and notes; characters stay recognizable (References), voices and locked songs.
• Pictures output, Storyboard node with Qwen Image 2.1 drawing, Control videos (pose, canny, depth, inpaint).
• Nine example workflows in ComfyUI's Templates, each with its example files and its chapter of the guide.
• H3 Guide node and GUIDE.md; SKILL.md so an AI agent can install the pack and help.
• Technical report on planning, continuation and the measurements behind it: docs/paper.

The example videos

The wfN_*.mp4 files below are what each example workflow made when it was opened from Templates and run through the interface, unchanged except for choosing the local model files. They are the test of this release: the guide was followed step by step, and what went wrong on the way was fixed (see CHANGELOG).

Install

Download Source code (zip) below, unpack it into ComfyUI/custom_nodes/, run python -m pip install -r requirements.txt with ComfyUI's Python, restart ComfyUI. Needs ComfyUI ≥ 0.37.0. Models: see the README; ComfyUI offers missing files when a workflow opens.

Known limits

• Tested on one machine (RTX 5060 Ti 16 GB, Windows, ComfyUI 0.42); other GPUs and Linux/macOS are untested.
• Generated sound loses some brightness over many render parts; a locked song does not.
• A control video steers the movement, but the shot text wins where they disagree (in workflows 7 and 8 the figure keeps walking away when the person in the source turns back).
• Most measurements are single-seed.

Please report problems as issues with the console traceback and the workflow JSON.

A voice on the subject, not on the timeline (issue #10). Every subject slot has an Add voice button (Refs ON), or drop an audio file on the slot. That clip is sent to the model as an <Audio N> reference tied to that subject:

<Audio 1> is the voice-timbre reference for <Subject 1> (S1).
<Audio 2> is the voice-timbre reference for <Subject 2> (S2).

It is not on the timeline, so it is not bounded by the render window and takes no output time — two voice references and a background track no longer compete for one lane, and the render stays as short as you made it. It does not depend on the audio-track switch either: a voice on a subject is as deliberate as the subject's image. Voices go first in <Audio N> order (slot order), then whatever sits on the timeline, inside H3's cap of three audio clips; a clip that does not fit is named. The timeline's audio clips and their Voice of menu work as before. A slot with no reference image cannot be a <Subject N>, so its voice goes out as a plain voice reference, which the tooltip says. Override Audio together with a reference video still wins (a reference video's soundtrack is numbered first), and it names the voice it set aside. The log warns when a voice file is under the 2 s the model card asks for.

@Brioch's pull request #18, carried over by hand: it had stopped merging after 0.2.3–0.3.0 touched the same planner and docs, so its behaviour was re-implemented on the current code and its tests re-written against it. Every idea below is theirs.

• A reference no longer spends output time. A reference is an input to the model, not content in the video — <Video k> and <Audio j> are never composited — but a clip had to overlap the render window to be sent at all, and adding one stretched the window to cover it. The model card wants each reference audio clip 10–15 s long, so three of them grew the output to 45 s: three times the longest video H3 can make. Neither reference track touches the output length now, and a clip is sent from wherever it sits; it lands after the last one, which for anything longer than the window is out in the shaded area, where a reference belongs. A 5 s render sends all three. Position still decides one thing, for audio only: whether the clip is also part of the muxed soundtrack — inside the window it is both, past it a reference only, which the clip's info panel says. A parked reference video is sent whole on its own trim instead of losing its head to a window start it has nothing to do with. A retake keeps the old rule. (lock clips are not references and still have to be in the window: a lock is a position in time.)
• Every audio clip on the track plays its own file again. With two clips loaded both showed up in the prompt and both drew their waveform, but only one could be heard: the editor stamped the decoded buffer onto every clip that matched it, and a standalone clip has no blob URL to match on, so the test was undefined === undefined for the whole track. Only the preview was affected; what was sent to the model was always right.
• A reference clip that cannot be read says which one. A missing file or a trim past the end of the audio was dropped in silence — and because <Audio N> is numbered before any file is opened, that label and every one after it then named a reference the model never got. The log now names the clip and its label.
• Both per-type caps (3 audio, 3 video) name the clip they drop, like every other limit.
• Override Audio wins over the audio track outside the editor too: sent together, every <Audio N> label would be one off (a reference video's soundtrack is numbered first). The clips set aside are named, and Override Audio warns when the video it wants the soundtrack from is parked past the window.