MiniMax H3 Audio Timeline Planner

MiniMax H3 renders four to fifteen seconds per pass, and it renders on a fixed grid: 124, 141, 158, 175 … 362 frames. That's 17k+5 at 24 fps - the model's lengths are quantised, you don't get to ask for 200. So the moment you want a real soundtrack instead of H3's own generated audio, you're doing maths - and somebody has to do it. This node does it.

What it hands you

The MiniMax H3 Audio Timeline Planner takes your master audio and your reference images and produces a version-4 MINIMAX_H3_AUDIO_PLAN - a task list. It's the planning half of a two-node pair; nothing renders here and nothing gets cropped here. The plan output feeds MiniMax H3 Audio Plan Step, which resolves one task at a time inside your sampling loop.

That split is the point: planning happens once, up front, so you can inspect it before burning an hour of GPU time. Resolution happens per iteration and validates against what the previous task actually produced - a crop mistake shows up as an error at task 7, not as desync at mux time.

How the tiling works

total_frames is derived from the master audio at a fixed 24 fps. From there the planner has to fit that many retained frames into tasks that are each no longer than max_render_frames and always a legal 17k+5 count. It picks the shortest valid length per task and balances retained frames across the minimum number of tasks rather than filling task one to the brim - short tails are what make the last task illegal.

Ordinary consecutive tasks overlap by 22 frames on purpose: the previous task's final generated frames get re-fed as a continuity clip so motion carries across the seam. Same chunking problem Wan has with its native 81-frame context, except here the overlap is exact and enforced instead of vibes.

The inputs you'll actually set

• audio - the master. It's authoritative for timeline duration and for the final mux; H3's own generated audio gets thrown away.
• image_batch - reference stills in timeline order. Image 1 owns frame 0. Each later image takes over at its planned transition, even when its exact anchor ends up cropped.
• manual_transition_times - "7, 13.5, 20", one comma-separated time per image after the first. Blank means evenly spaced. The parser is strict: same count as image_count - 1, strictly increasing, inside the audio, and no two times landing on the same frame.
• transition_mode - first_last_bridge guides motion into the next image; boundary_switch makes an honest hard cut. bridge_span (short_window or full_interval) and bridge_window_seconds decide the visible bridge before the switch; set the window to zero and you've built boundary_switch the long way round.
• max_render_frames - 362 by default. Lower it and each task gets cheaper in VRAM but you get more tasks: more seams, more total time. On a 3060 this is the dial that decides whether you finish.
• Activity alignment - align_to_activity_gap, transition_edge, search_window_seconds, min_gap_duration, resume_hold_duration. With several images this nudges each target into a detected gap in the audio; with one image it puts continuation seams at sentence gaps. activity_resume cuts when sound returns after a pause, silence_start when the pause begins. No qualifying gap means your original target survives.

Optional: conditioning_audio (a raw Demucs vocal stem, at its own sample rate; it may differ from the master by at most one frame at 24 fps) and audio_encoder_output, the Wav2Vec features from ComfyUI's core AudioEncoderEncode. Those features only ever locate gaps - they never replace either audio input.

Read the report before you render

Outputs are plan, extension_task_count, total_frames, base_keep_frames, and report. extension_task_count is your loop iteration count - task 0 is the base render, the rest are extensions. report summarises image ownership, transition frames, hidden-anchor handoffs, activity alignment and task ranges in plain English. Drop a Show Text on it before you render anything.

Install

ComfyUI Manager → search ComfyUI_Eclipse. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/r-vage/ComfyUI_Eclipse

Then restart. requirements.txt is light - torch, numpy, Pillow, opencv-python, pilgram, safetensors, torchvision, PyYAML, aiohttp - and ComfyUI already covers most of it; opencv and pilgram are the usual additions on a clean install. No model download for these nodes.

Two things people trip on. Eclipse's diffusion loaders now live in the separate ComfyUI_SmartModelLoader pack, so installing this alone gets you a plan and no model. And if your workflow came from the old RvTools_v2 days it won't load - v4.0.0 deleted every legacy node, and Manager can't resolve the dead repo's node types. Run the pack's Workflow Migration Tool node, or from the repo:

python tools/migrate_workflow.py /path/to/your_workflow.json

It backs up before it rewrites.

One non-technical note: H3's weights ship under the MiniMax H3 Community License, whose grant is void in the US, EU, UK and South Korea - outputs included. That's a licensing question, not a technical one.