| --- |
| 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. |
