Update README.md

033a34a verified 1 day ago

9.92 kB

license: mit
tags:
  - comfyui
  - custom-nodes
  - minimax-h3
  - video-generation
  - text-to-video
language:
  - en
pipeline_tag: text-to-video
base_model:
  - MiniMaxAI/MiniMax-H3

H3-LongVideos

One prompt in. A ~2-minute MiniMax-H3 video with audio out.

A ComfyUI node pack that turns a single written prompt into a long, continuous H3 video — automatically splitting it into shots, chaining them together, and keeping characters, wardrobe and audio consistent across the whole thing.

H3 caps a single generation at 362 frames (~15s). This node writes the shots for you, chains each one from the last frame of the previous, and hands back one images + audio pair for the finished video.

Why this exists

Chaining H3 shots by hand means solving the same problems over and over:

The model renders a character twice when the prompt names them more than once.
A character changes clothes between shots, or a removed jacket comes back.
Mouths move and produce gibberish on shots that have no dialogue.
Someone who walked out of frame reappears two shots later.
A 12-shot chain runs out of VRAM halfway through.

This pack fixes those in the prompt-assembly and memory layers, so the shots you write are the shots you get.

Install

Open the Files and versions tab above and download all the files.
Create a new folder called H3-LongVideos inside ComfyUI/custom_nodes/.
Drop the downloaded files into it, so you have:

ComfyUI/
└── custom_nodes/
    └── H3-LongVideos/
        ├── __init__.py
        ├── sampler.py
        ├── shot_length.py
        ├── inspector.py
        ├── test_prompt_logic.py
        └── README.md

Restart ComfyUI — a full server restart, not just a browser refresh.

Requires ComfyUI 0.30+ with native MiniMax-H3 support.

Dependencies

None. No pip install, no requirements.txt, no third-party node packs. Everything is Python's standard library plus ComfyUI core (nodes, comfy.utils, comfy.samplers, comfy.model_management, comfy.nested_tensor, node_helpers, folder_paths).

You do need the standard H3 model files, loaded with ComfyUI's own loaders:

File	Loader
H3 diffusion checkpoint	Load Diffusion Model
Qwen3-VL text encoder	CLIP Loader
`minimax_h3_video_vae`	VAE Loader → `vae`
`minimax_h3_audio_vae`	VAE Loader → `audio_vae`

Optional integrations

These are detected at runtime and never required — if a pack isn't installed, the node falls back cleanly and reports it in info. Nothing here can break a render by being absent.

Feature	Needs	Fallback if missing
`upscale: rtx`	Nvidia_RTX_Nodes_ComfyUI (RTX Video Super Resolution)	falls back to `model`, then `lanczos`
`upscale: model`	any upscale model in `models/upscale_models` (Real-ESRGAN, UltraSharp, …) — uses ComfyUI's built-in loader	falls back to `lanczos`
Live previews during sampling	a tiny H3 preview decoder (`taeh3`) in `models/vae_approx`	previews fall back to `latent2rgb`

Higher-quality upscaling (SeedVR2, LTX-2.3) runs as a separate pass on this node's images output — it is not wired into the node and needs no integration.

Nodes

Node	Purpose
H3 Long Videos V1	The main node. Prompt + length → chained video + audio.
H3 Shot Length	One shot length as both seconds and a valid 17k+5 frame count.
H3 Model Inspector	Reports checkpoint precision (BF16/FP8/INT8/NVFP4/MXFP8) and whether your card runs it natively.

Quick start

Wire model, clip, vae and audio_vae from the standard H3 loaders, then:

Prompt — first paragraph is the scene and style, each later paragraph is one shot:

A cinematic aircraft hangar and airfield, warm late-afternoon light.
Slow, smooth camera movement. Minimal motion blur.

Teresa walks in and crosses to the workbench.

Dan asks Teresa, "Did you bring the engine as requested?"

Teresa points at the crate in the corner.

character_memory — who is in the video, as attributes:

Teresa = she, mid-thirties, slim, blonde hair, biker t-shirt, leather pants
Dan = he, forties, brown hair, black t-shirt, jeans

That's it. Set resolution, steps and seed, and queue.

Set plan_only to preview the shot split — how many shots, how long each, total runtime — instantly, without rendering.

What it handles for you

Character and wardrobe state

Clothing lives in one mutable channel, so it can actually change:

Removals are read from your prose. "She takes off her jacket" drops the jacket, and it stays gone. Gated on items the character is actually wearing, so "the plane takes off" removes nothing.
Per-person. Teresa -= jacket doesn't touch Dan.
Framing-independent. A close-up that crops the trousers won't make the next shot reinvent them.
Exits stick. "He walks out of the hangar" removes him from every later shot — and a later pronoun can't summon him back.

Duplication control

The most common cause of a character rendering twice is the prompt introducing them twice. The node assembles each shot so that:

Each person is described once, bound inline at their first mention.
People named or described in the anchor are stripped from it (the anchor is stamped into every shot, so a name there is a second introduction).
Noun phrases become attributes — a woman with silver hair → silver hair — because She (a woman with…) reads as two subjects.
Generic camera-direction references (the camera follows **the subject**) are rewritten, so they don't summon an unnamed extra body.
An explicit subject count is added below native resolution or when a LoRA is applied.

Audio

Non-dialogue shots are silenced. Any beat without a quoted line gets an explicit lips-closed instruction, so mouths don't flap and vocalise gibberish.
mute_nonspeech_audio goes further and zeroes those shots' audio outright — deterministic rather than asking the model nicely.
Music is opt-in. A blank music field emits the schema's N/A token, so H3 doesn't improvise a score.
Dialogue-fit warnings flag lines too long for the shot they're in, before you render.

VRAM

Shot length is budgeted from card capacity minus measured weight size, scaled by resolution — so it adapts to any quant without special-casing.
Between shots: decoded frames move to system RAM, and the text encoder and VAEs are evicted before sampling (ComfyUI keeps them resident otherwise).
Checkpoint swaps are detected and flushed, so a stale model from a previous run doesn't poison the budget.
Optional temporal/spatial VAE decode tiling for the largest allocation in a run.
Reports free VRAM per shot in info so you can see whether a chain is stable.

Outputs

images · audio · info · script · frames_per_shot · total_frames · shots · video_seconds

script is the literal text sent to the model for every shot — the first place to look when a render doesn't match what you wrote.

Resolution

18 presets, all multiples of 32, in three short-edge tiers per aspect ratio:

native 768 — H3's trained size, best detail
balanced 640
fast 512 — renders faster, frees VRAM, allows longer shots

Lower tiers are for the generate-low-then-upscale workflow. H3 distorts faces on wide shots at any resolution, so keep faces reasonably large in frame.

Settings that matter

Setting	Base model	Low-step checkpoint (e.g. MXFP8)
`steps`	~20	8
`shift_video` / `shift_audio`	12 / 3	8 / 3
`sampler` / `scheduler`	`res_multistep` / `simple`	same
`cfg`	1.0 (H3 is CFG-free)	1.0

Low steps on a base checkpoint is the single most common cause of soft output.

Honest limitations

Things this node cannot fix, because they're the model or the hardware:

Distilled/turbo LoRAs override prompts. Compressing ~20 steps into 4–8 means composition, identity and age settle in the first step or two. Expect character drift, invented content and duplication that prompt engineering can't undo.
Multi-subject weaknesses. Identity binding, attribute cross-wiring and multi-speaker audio all degrade as you add people. Keep characters visually distinct and prefer one speaker per shot.
Rigid objects (chains, tools, thin metal) deform frame to frame. No prompt setting fixes it.
A checkpoint larger than your VRAM will stream, and some spill is structural before a single frame is allocated.
Audio can't cross a shot boundary. Each shot generates its own, so a line of dialogue spanning a cut won't be continuous. Lay a continuous ambience bed under the video in post.

Tested on

RTX 5060 Ti 16GB (Blackwell, sm_120), ComfyUI 0.31.1, CUDA 13.3.

Measured on that card, 1344×768, pruned NVFP4 (~~11.7GB resident): 243 frames (~~10s) per shot renders comfortably; 362 frames (~15s) overflows. Setting NVIDIA's CUDA – Sysmem Fallback Policy to Prefer No Sysmem Fallback freed roughly 800MB and was the single largest VRAM win found during development.

Testing

python3 test_prompt_logic.py

Runs the full prompt-assembly suite (duplication, wardrobe, exits, dialogue, audio, VRAM budget) against a 12-beat chain with no GPU and no ComfyUI required.

Licence

Node pack: MIT.

MiniMax H3 itself uses a custom territorial licence whose open-weight grant excludes the US, EU, UK and South Korea. This pack contains no model weights — check H3's own licence terms before using the model.