MiniMax H3 Finite Segment 桥接器

What it is

MiniMax H3 makes 4–15 second clips. Anything longer on open weights is segment stitching, and stitching is where video workflows usually fall apart - hard cuts, drifting characters, audio that restarts every clip. Songssx's TimelineDirector pack ships a MiniMax H3 Finite Segment Sampling node that handles continuation properly (direct-latent continuation, adaptive masking, native audio-video path) and is, by the pack author's own recommendation, substantially faster than the classic Director sampler at the same model, resolution and duration.

That node doesn't take a prompt - it takes a finite_plan, a structured dict of segments, resolutions, frame counts and second-pass settings. This bridge builds it from the optimizer's prompt and media bundle, so your alternative isn't a different node, it's hand-authoring JSON.

How it works

Single-segment mode is the default: leave segments_json empty, set duration_sec, width and height, and the bridge emits a minimax_h3_finite_segment_plan (version 4, mode: single_segment) wrapping one timeline plan. Everything you care about is inside that inner plan - a timeline dict at 24 fps with your prompt as globalPrompt, the reference images and audios, an empty videoClips list, and a selection window of start frame plus duration.

Multi-segment mode is the interesting one. Feed segments_json (the optimizer generates it for you when you build a multi-segment prompt; empty means single-segment) and you get version 3, mode: timeline_segments, with one plan per segment. Two details are worth understanding before you touch the numbers:

Frame counts snap to H3's ladder. Valid H3 lengths are 5 + 17n frames at 24 fps, so the bridge rounds every requested duration to the nearest legal count. Ask for 1 second and you get 22 frames (0.92s), not 24.

Overlap is how the joins stay smooth. Each segment starts at the previous one's end frame minus its overlap, 24 frames (one second) by default, and total output frames is the sum of segment lengths minus every overlap. Per-join overlap is drag-adjustable in the node UI; it rides in on a hidden bridge_overlaps widget holding an array like [0,24,24], the first entry being the first segment, which has nothing to overlap.

Second-pass (SelfLift two-stage) is passed straight through as second_pass, second_pass_model and second_pass_high_steps (default 2) - hidden widgets managed by the node UI, so toggle it there rather than editing JSON. On gets you the fast 75% low-res pass plus a 25% high-res pass; off is quicker and softer.

Inputs and outputs that matter

Both media inputs are optional and both come from the optimizer: media_bundle, and prompt - typed GH_PROMPT_STR, so use the optimizer's prompt_finite output. Plugging the plain prompt output in won't connect, deliberately: the wrapper type stops the two bridge nodes being wired to the wrong strings.

Then duration_sec (0.2–150, default 5, ignored in multi-segment mode because segments_json overrides it), width and height (864×480 by default), and audio_mode:

• 参考音色 (reference timbre) - regenerates the dialogue in the timbre of the audio you uploaded.
• 强制使用音频1 (forced audio 1) - passes your first audio clip through raw, original sound. Only the first one is taken.

Outputs are finite_plan, which goes to the Finite Segment Sampler's finite_plan input, and summary - a plain string with the segment table, frame counts, overlap total and final duration. Wire it into a text preview node; reading it before you queue is the difference between spotting a 3-frame segment and discovering it twenty minutes into sampling.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/aihaipan/ComfyUI-Universal_Prompt_Optimizer.git

Restart afterwards, or find ComfyUI Universal Prompt Optimizer in ComfyUI Manager. The pack's only Python dependency is aiohttp, already in ComfyUI - no model files, no build step. But this node needs two other things to be useful: the TimelineDirector pack, which provides both the Finite Segment Sampling node and the MINIMAX_H3_FINITE_SEGMENT_PLAN type, and this pack's own optimizer node if you want the UI that generates segments_json. The repo's workflows/ folder ships a ready-made two-stage unlimited-length example - fastest way to see the wiring.

Where people get burned

Segments are longer than you think. A "1 second" entry becomes 22 frames (0.92s) and a "5 second" entry becomes 124 (5.17s); the snap is silent except in summary. Read the frame column, not the seconds column, when you're aiming for a specific total.

Multi-segment input wants one of three formats, and mixing them is the usual error. Empty means single-segment. A JSON object needs a non-empty segments list. Or use the mini line format the author documents - one line per segment, <seconds> | <prompt> | images=1,3, with images= optional and 1-based indices, and # for comments. Malformed lines raise a message naming the line number and what it expected, which is about as friendly as this gets.

Overlap eats duration. If your total target was 30 seconds and you set 24 frames of overlap on five joins, the plan delivers 30 seconds minus 120 frames - five seconds of video gone. That's correct behaviour, not a bug; it's the price of a smooth transition. Drop the overlap if you'd rather have the frames.

Empty bundle, no references. Neither bridge type decodes uploaded video, and audio containers pyav rejects get skipped, so a bundle that looks full in the editor can arrive thinner than you think. Watch the console the first time you run a reference-heavy plan.