--- 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 1. Open the **Files and versions** tab above and download all the files. 2. Create a new folder called **`H3-LongVideos`** inside `ComfyUI/custom_nodes/`. 3. 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 ``` 4. 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](https://github.com/Comfy-Org/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 ```bash 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.