ComfyUI-MiniMaxH3-PerRowMasking

ComfyUI MiniMax H3 Per-Row Masking

[!IMPORTANT] This is a temporary compatibility shim, not a permanent replacement for ComfyUI core support. It exists only so the AbleJones per-row masking fix can be used while the corresponding core change is pending. Once ComfyUI provides native MiniMax H3 generation-mask support, remove this custom node and use the core implementation.

Temporary, experimental ComfyUI nodes implementing AbleJones's mixed-timestep generation-mask fix for MiniMax H3 without modifying ComfyUI core files.

The patch is scoped to the MODEL returned by the patch node. Protected video/audio rows remain near H3's conditioning timestep while generated rows follow the normal denoising schedule. Video masks are snapped to H3's 2x2 latent DiT patch grid (roughly 32x32 source pixels with the current VAE).

The algorithm and original implementation are credited to AbleJones. This compatibility node is based directly on AbleJones/drozbay's experimental core patch.

Nodes

MiniMax H3 Trim Source AV to 17k+5

Connect the source video frame batch and, optionally, its synchronized audio. The node drops only the trailing video frames so the returned length is the largest valid H3 17k+5 value that does not exceed the source. It never pads, resizes, or changes fps. Connected audio is trimmed to the returned frame duration at H3's fixed 24 fps.

Outputs:

• Trimmed source IMAGE frame batch
• Trimmed synchronized AUDIO (when supplied)
• Exact h3_length integer for the H3 conditioning node
• Human-readable trim report

Place this before the source frames split toward SAM3, mask preview, and H3 video VAE encoding. This keeps all three branches on the same valid temporal range. If the source audio is shorter than that range, the node leaves it short and reports the mismatch; it does not invent silence.

MiniMax H3 Per-Row Mask Patch (Experimental)

Input: MiniMax H3 MODEL

Output: patched MODEL

Connect the output to the guider used by the sampler. The input model is cloned; unrelated model connections are not changed.

MiniMax H3 Set Generation Mask

Inputs:

• Joint source video+audio LATENT
• Video-space MASK
• Mask meaning: white generates or white preserves
• Audio mode: generate audio or preserve the complete source audio

Output: joint AV latent with a nested H3 noise mask.

MiniMax H3 Mask Grid Preview & Snap

Connect a mask from SAM3 Detect, SAM3 Track to Mask, the mask editor, or any other standard ComfyUI mask node. The node displays the exact 32x32 H3 cells selected for generation and outputs the snapped mask.

Inputs:

• Exact resized H3 canvas IMAGE or video-frame batch
• Standard ComfyUI MASK
• Cell-selection mode
• Whole-cell grow/shrink adjustment
• Preview overlay controls

Outputs:

• Cell-snapped MASK for MiniMax H3 Set Generation Mask
• Preview IMAGE with orange selected cells, cyan grid lines, and an optional white outline of the original mask
• Grid summary text

The default runtime exact (latent max) mode reproduces the spatial mask resize and per-row decision used during H3 sampling. The alternative pixel-coverage modes are useful when you deliberately want a broader or more conservative selection.

In runtime-exact mode, the mask is first reduced to H3's 16x-downsampled video latent and then grouped into 2x2 latent rows. Consequently, an extremely small isolated SAM3 mark can disappear during mask reduction before cell selection. Use any pixel coverage when every marked source pixel must force its complete 32x32 cell on.

The preview image must already use the exact H3 canvas dimensions that will be VAE-encoded. Both dimensions must be divisible by 32; otherwise the preview intentionally stops with a clear alignment error.

Basic workflow

1. Pass the source frames and optional synchronized audio through MiniMax H3 Trim Source AV to 17k+5.
2. Resize/crop its trimmed frames to the exact H3 canvas and split that same batch toward SAM3, mask preview, and video encoding.
3. Encode the source video with the correct MiniMax H3 video VAE.
4. Encode or create the source audio latent.
5. Combine them using ComfyUI's Concat AV Latent node.
6. Connect a SAM3 or other mask and the resized source frames to MiniMax H3 Mask Grid Preview & Snap.
7. Connect its snapped-mask output and the joint latent to MiniMax H3 Set Generation Mask.
8. Pass the MiniMax H3 MODEL through MiniMax H3 Per-Row Mask Patch and connect its output to the guider.
9. Sample the masked joint latent normally.

By default, white mask pixels are regenerated and black pixels are preserved. A single mask frame is applied across time; a mask batch can follow motion across the source video.

The source video belongs in the main latent. Do not also pass it as an H3 <Video> reference merely to make masking work.

Example workflow

Load MiniMax H3 Per-Row Video Inpaint.json in ComfyUI for a complete source-video inpainting graph. It includes source AV extraction, automatic 17k+5 trimming, exact H3 canvas resizing, a replaceable static-mask input, 32x32 grid verification, source AV encoding, per-row masked sampling, and synchronized video/audio decoding.

The example expects a 24 fps source video with an audio track. Its Load Image (as Mask) node reads white from the selected image's red channel and broadcasts that mask across time; replace this connection with ComfyUI's SAM3 Track to Mask output for a moving temporal mask. Select your own source video and mask after loading the workflow.

Compatibility

• Supports both the earlier H3 audio-slope contract in ComfyUI 6f7cd7fceaaf60d2669b554936394a7412c6fde5 and the newer ModelSamplingAV contract used by v0.30.0 builds where time_shift_slope was removed.
• Preserves the block_loop hook used by lihaoyun6/ComfyUI-MiniMaxH3-Cache.
• Preserves per-block replacement hooks, including attention patches attached to H3 blocks.
• Intentionally fails with a clear error when the connected model is not MiniMax H3 or required H3 internals are missing.

This is an internal-model compatibility shim, not a stable API. Test a short generation after every ComfyUI update.

Installation

Clone into ComfyUI/custom_nodes and restart ComfyUI:

git clone https://github.com/ethanfel/ComfyUI-MiniMaxH3-PerRowMasking.git

No additional Python packages are required beyond ComfyUI.

Acknowledgements

• AbleJones/drozbay, author of the original per-row mixed-timestep implementation and the experimental patch this repository ports without on-disk core modifications.
• Kijai and the ComfyUI MiniMax H3 contributors for the H3 integration this temporary shim targets.

License

GPL-3.0-or-later. Portions are adapted from ComfyUI and the cited experimental patch.