A professional, streamlined ComfyUI extension pack for MiniMax H3, enabling seamless continuous video and phase-locked audio extension with built-in concat merging, anti-stutter optical flow smoothing, color correction, and automatic Turbo LoRA hot-patching.

🎬 Video Extension Demos

Below are real generation examples demonstrating seamless extension from a single 4.5-second clip (107 frames) to an 8.0-second video (192 frames) with continuous camera dynamics, subject motion, and soundtrack continuity:

📊 Side-by-Side Vertical Comparisons (Top: Original Clip vs Bottom: Seamless Extension)

| Example 1: Action & Continuous Motion | Example 2: Scene & Atmospheric Continuation | | :---: | :---: | | <img src="assets/1_compare_stack_preview.webp" width="100%" alt="Example 1 Comparison"> 🎬 Download Stacked Comparison MP4 (with audio) 📁 Original Clip (4.5s) • 📁 Extended Video (8.0s) | <img src="assets/2_compare_stack_preview.webp" width="100%" alt="Example 2 Comparison"> 🎬 Download Stacked Comparison MP4 (with audio) 📁 Original Clip (4.5s) • 📁 Extended Video (8.0s) |

🌟 Key Features

Seamless Video Extension (MiniMaxH3VideoExtender): Carry over motion and temporal context from previously generated clips into the new clip with frame-accurate continuity.
Phase-Locked Audio Continuation: Pins timeline audio from the previous clip's latent space or decoded waveform, preventing audio sync drift across iterations.
Anti-Stutter Motion Smoothing (seam_smooth): Computes Farneback Optical Flow across the seam boundary to compensate for diffusion motion hesitation and acceleration spikes without losing any frames.
Flicker-Free Color Alignment (color_match = "seam_fade"): Matches luminance and chrominance directly at the seam boundary, smoothly cosine-fading back to native colors over 24 frames to completely eliminate 1-frame brightness pops.
Smart Automatic Passthrough: Works in standard single-clip workflows: if no previous video or latent is connected, it passes through transparently to generate a fresh new clip.
Lossless Clip Concatenation (MiniMaxH3VideoMerge): Concat video frames and audio seamlessly. Automatically aligns resolutions and resamples mismatched audio sample rates.
Accurate Overlap Trimming (MiniMaxH3LoopTrim): Drops pinned context frames from both video and audio tracks concurrently to maintain 100% audio-video synchronization.
Turbo LoRA Hot-Patch (_patch_h3_turbo_lora): Automatically intercepts AdaLN tensor operations in ComfyUI-MiniMax-H3-Turbo to prevent shape mismatch crashes when using multimodal references and audio.

🚀 Example Workflows

Two ready-to-use workflows are bundled in the example_workflows/ directory:

| Workflow File | Mode | Description | | :--- | :--- | :--- | | video_minimax_h3_r2v_extend_pre_latent.json | Pure Latent (Recommended) | Uses MiniMax H3 Load AV Latent to reload the exact sampled .safetensors latent. Bypasses lossy VAE decode/encode roundtrips for maximum fidelity, lossless motion guidance, and perfectly phase-locked sound. | | video_minimax_h3_r2v_extend_video.json | External Video (MP4) | Uses VHS_LoadVideoFFmpeg to load any external MP4 video file, passing decoded frames into Video Extender and merging the extended result. Ideal for continuing existing videos or videos from outside ComfyUI. |

Typical Wiring Architecture:

Option A: Pure Latent Continuation (Recommended)

[MiniMax H3 Load AV Latent]
   ├── (latent) ──────────────────────────► (prev_latent) [MiniMax H3 Video Extender]
   ├── (images) ──────────────────────────► (images_a)    [MiniMax H3 Video Merge]
   └── (audio)  ──────────────────────────► (audio_a)             ▲
                                                                  │
[MiniMax H3 Conditioning] ──► [Video Extender] ──► [KSampler] ──► [VAEDecode / AudioDecode]
                                      │ (trim_frames)                     │ (images & audio)
                                      └────────────────────────► [Loop Trim]
                                                                     ├── (images) ──► (images_b)
                                                                     └── (audio)  ──► (audio_b)

Option B: External Video File (MP4)

[Load Video (MP4)]
   ├── (IMAGE) ───────────────────────────► (prev_frames) [MiniMax H3 Video Extender]
   ├── (IMAGE) ───────────────────────────► (images_a)    [MiniMax H3 Video Merge]
   └── (AUDIO) ───────────────────────────► (audio_a)             ▲
                                                                  │
[MiniMax H3 Conditioning] ──► [Video Extender] ──► [KSampler] ──► [VAEDecode / AudioDecode]
                                      │ (trim_frames)                     │ (images & audio)
                                      └────────────────────────► [Loop Trim]
                                                                     ├── (images) ──► (images_b)
                                                                     └── (audio)  ──► (audio_b)

📦 Nodes Overview

1. `MiniMax H3 Video Extender` (`MiniMaxH3VideoExtender`)

Drop-in conditioning adapter wired right before the sampler.

Inputs:
- conditioning (CONDITIONING): Base conditioning (from MiniMaxH3ReferenceToVideo, MiniMaxH3ImageToVideo, or MiniMaxH3TextToVideo).
- latent (LATENT): Target latent for the new clip.
- vae (VAE): MiniMax H3 Video VAE.
- mode:
  - auto: Automatically extends if prev_frames or prev_latent is connected; otherwise behaves as a normal passthrough for generating new videos.
  - always_extend: Enforces extension (raises an error if neither prev_frames nor prev_latent is connected).
  - disabled: Bypasses context extension completely.
- context_length (INT, default 22): Number of previous frames to pin (typically 22 or 5).
- prev_latent (LATENT, Optional): Previous clip's latent (e.g. from MiniMax H3 Load AV Latent). Enables direct latent motion guide & phase-locked audio without quality loss.
- prev_frames (IMAGE, Optional): Decoded frames of previous clip. (If omitted but prev_latent is connected, it auto-decodes from latent).
- prev_audio (AUDIO, Optional): Decoded audio of previous clip.
- audio_vae (VAE, Optional): Required when encoding decoded audio.
Outputs:
- conditioning: Modified conditioning injected with motion context.
- trim_frames: Integer frame count to trim from the decoded output using MiniMax H3 Extension Trim.

2. `MiniMax H3 Video Merge (Concat)` (`MiniMaxH3VideoMerge`)

Combines consecutive clips and audio tracks into a single continuous stream with color correction and seam smoothing.

Inputs:
- images_b (IMAGE): Current newly rendered clip frames (from Loop Trim).
- images_a (IMAGE, Optional): Previous clip frames (from Load Video or Load AV Latent's images output).
- audio_b (AUDIO, Optional): Current clip audio (from Loop Trim).
- audio_a (AUDIO, Optional): Previous clip audio (from Load Video or Load AV Latent's audio output).
- seam_smooth (INT, Optional, default 1): Optical-flow motion smoothing across the seam boundary (0 = off, 1 = smooth seam frames, 2-3 = smooth transition window). Eliminates frame jitter and motion hesitation without dropping frames.
- color_match (["seam_fade", "match_mean_std", "disabled"], Optional, default "seam_fade"): Color & luminance correction for images_b to match images_a. "seam_fade" completely eliminates brightness pop/flash at the seam and smoothly blends back to native colors over 24 frames.
- blend_frames (INT, Optional, default 0): Optional crossfade transition frames. (Keep at 0 when seam_smooth >= 1 to preserve full frame timeline without time loss).
- fps (FLOAT, Optional, default 24.0): Video frame rate for computing audio crossfade when blend_frames > 0.
Outputs:
- images: Unified frame sequence with seamless transitions.
- audio: Unified audio track with automatic resampling and crossfade.

3. `MiniMax H3 Extension Trim` (`MiniMaxH3LoopTrim`)

Trims pinned leading overlap frames from both decoded images and waveform audio simultaneously.

Inputs:
- images (IMAGE): Decoded frames of the current clip.
- trim_frames (INT): Overlap frame count connected from MiniMaxH3VideoExtender.
- audio (AUDIO, Optional): Decoded audio for the current clip.
- match_tail (BOOLEAN): Zero-pads or trims minor 40 Hz audio latent rounding differences (preventing drift across multi-step extensions).
Outputs:
- images: Trimmed frames ready for merging or preview.
- audio: Time-aligned trimmed audio.

4. `MiniMax H3 Save AV Latent` (`MiniMaxH3SaveLatent`)

Saves the sampler's exact H3 AV latent (NestedTensor: video + audio) directly to disk in .safetensors format.

Inputs:
- latent (LATENT): Sampler output latent.
- filename_prefix (STRING, default "h3_context/clip"): Folder & prefix in ComfyUI output/.
- clip_index (INT, default 0): Numbered slot for this clip (e.g. clip 1 = 1). If 0, auto-increments with run number.
Outputs:
- latent: Passthrough of the latent so it can be wired directly in-line between KSampler and VAEDecode.
- latent_path: Absolute filepath of the saved checkpoint.

5. `MiniMax H3 Load AV Latent` (`MiniMaxH3LoadLatent`)

Loads a saved H3 AV latent from a previous run to connect into MiniMaxH3VideoExtender and MiniMaxH3VideoMerge.

Inputs:
- latent_path (STRING, default "h3_context"): Path or folder to load from.
- clip_index (INT, default 0): Clip index to continue from (0 = newest saved latent in folder).
- vae (VAE, Optional): Connect Video VAE to automatically decode previous clip frames.
- audio_vae (VAE, Optional): Connect Audio VAE to automatically decode previous clip soundtrack.
Outputs:
- latent: The preserved AV latent, ready to plug into MiniMaxH3VideoExtender's prev_latent.
- images: Decoded previous clip frames (when vae is connected). Wire to MiniMaxH3VideoMerge (images_a).
- audio: Decoded previous clip soundtrack (when audio_vae is connected). Wire to MiniMaxH3VideoMerge (audio_a).

6. `MiniMax H3 Motion Context (Manual)` (`MiniMaxH3MotionContext`)

Low-level manual motion context node for fine-grained control over latent slices, anchor modes (head vs before), and encoding modes (video vs frames).

🔧 Automatic Runtime Patches

When loaded, this custom node automatically provides essential hot-patches:

Layout Patch: Unlocks flexible anchor positioning so pinned motion can reside on negative coordinates or customized timeline positions without ComfyUI rejecting the graph.
Payload Patch: Prevents MiniMax reference blocks (Ref2VA) from overwriting motion context latents.
Turbo LoRA Patch: Hot-patches _make_adaln_forward in ComfyUI-MiniMax-H3-Turbo so temporal embeddings cleanly broadcast/pad when audio or reference tokens are present.

💻 Installation

Method 1: ComfyUI Manager (Recommended 1-Click Install)

Open ComfyUI Manager inside your ComfyUI interface.
Search for MiniMax H3 Extender or comfyui-minimax-h3-extender.
Click Install, then restart ComfyUI.

Method 2: Comfy CLI

comfy node install comfyui-minimax-h3-extender

Method 3: Manual Git Clone

Clone this repository into your ComfyUI custom_nodes folder:

cd ComfyUI/custom_nodes
git clone https://github.com/pmhaidn/ComfyUI-Minimax-H3-Extender.git

Install dependencies if needed:

pip install -r requirements.txt

📜 Credits & License

Developed and rewritten by pmhaidn (@pmhaidn).
Algorithm and motion context foundation inspired by NikoDemon80/ComfyUI-H3-Motion-Context.
License: GNU General Public License v3 (GPLv3).