MiniMax H3 Loop:
MiniMaxH3Loop prepares a MiniMax H3 model to generate repeating video and audio by treating the sequence as a continuous loop rather than a clip with separate beginning and end points. During sampling, it extends the sequence with wrapped context: material from the end is placed before the beginning, and material from the beginning is placed after the end. This gives the model context across the join and helps it generate a smoother transition when playback repeats. It also supports an additional sampling view that shifts the loop by half its length to improve audio around the loop boundary. The node patches the model’s sampling behavior rather than generating or decoding media itself, and it is designed to work with the companion MiniMax H3 Loop Decode node.
MiniMax H3 Loop Input Parameters:
model
Required input of type MODEL. This is the MiniMax H3 model whose sampling behavior you want to adapt for loop generation. The node clones the supplied model and adds loop-specific sampling modifications to the clone, allowing the resulting model connection to carry the loop behavior into subsequent sampling steps. Use a compatible MiniMax H3 model rather than an unrelated image or video model. If you also use Apply MiniMax H3 Fun ControlNet, this loop patch must come first in the model chain; applying it after the Fun ControlNet patch causes an explicit error. This connection has no numeric minimum, maximum, or default value.
pad_clips
Required integer input with a default of 1, a minimum of 1, and a maximum of 8. This controls how many 17-frame clips of wrapped context are added on each side of the loop during sampling. For example, a value of 1 adds one clip of context before the loop and one after it, helping the model account for what happens across the playback boundary. Larger values provide a wider context around that boundary but increase sampling time because more material must be processed. This padding is working context, not extra content intended to extend the final loop. Start with 1 and increase it cautiously when testing whether additional context improves your result; the provided implementation does not establish that higher values always produce better loops.
views
Optional integer input with a default of 2, a minimum of 1, and a maximum of 2; the available settings are 1 and 2. At 1, sampling runs without the additional half-rotated view. At 2, the node also samples the loop shifted by half its length and uses audio around the original loop point from that additional view, helping address garbled audio where the loop repeats. The source tooltip estimates approximately 1.8 times the sampling time for this setting. Choose 2 when audio continuity at the join matters and you are not using Fun ControlNet; choose 1 for faster sampling or when using Fun ControlNet, because the two-view mode is explicitly documented as incompatible with it.
MiniMax H3 Loop Output Parameters:
model
Output of type MODEL. This is the cloned model with loop-aware sampling modifications attached and the selected padding and view settings stored in its model options. Connect it to the model input of your subsequent sampling workflow, or first pass it through Apply MiniMax H3 Fun ControlNet if your workflow requires that patch. The output is a configured model, not a video, audio waveform, or latent sequence; sampling must still produce the latent result, and MiniMax H3 Loop Decode should then convert that result into one loop of video frames and audio.
MiniMax H3 Loop Usage Tips:
- Set your latent video length to
17k + 5frames, wherekis a positive integer. The resulting decoded loop contains17kframes; the additional five frames provide a tail that wraps back to the beginning rather than extending the finished loop. - Use the documented length examples when setting up a workflow: 107 input frames produce a 102-frame loop, 158 produce 153, 209 produce 204, 260 produce 255, 311 produce 306, and 362 produce 357. The minimum supported length indicated by the helper code is 22 frames, consisting of one 17-frame clip plus the five-frame tail.
- Start with
pad_clips = 1to limit sampling overhead. Test larger values only when you need more wrapped context, and compare the actual playback boundary rather than assuming that more padding guarantees a better result. - Use
views = 2when you want the additional audio-boundary treatment and can accept approximately 1.8 times the sampling time. Switch toviews = 1for faster tests or when using Fun ControlNet. - When using Fun ControlNet, follow this model connection order:
model → MiniMaxH3Loop → Apply MiniMax H3 Fun ControlNet → sampler. The Fun ControlNet patch must be applied after the loop patch so that its control-latent sizing occurs in the correct place relative to loop padding. - Decode sampled loop latents with MiniMax H3 Loop Decode and supply the appropriate video and audio VAEs. The companion decoder adds wrapped context during decoding and trims it away afterward so that it returns exactly one loop.
- Keep the loop patch’s
pad_clipssetting and the decoder’spad_clipssetting conceptually separate: one controls context during sampling, while the other controls context during decoding. Both default to 1, but the supplied code does not require their values to match.
MiniMax H3 Loop Common Errors and Solutions:
Apply MiniMax H3 Loop before Apply MiniMax H3 Fun ControlNet: chain model -> MiniMax H3 Loop -> Apply MiniMax H3 Fun ControlNet.
- Explanation: This is the explicit error raised when the incoming model already has the recognized Fun ControlNet patch applied. Fun ControlNet sizes its control latent from the input it receives, so the loop patch must be installed earlier in the chain.
- Solution: Reconnect the model so that MiniMaxH3Loop comes before Apply MiniMax H3 Fun ControlNet, then send the resulting model to your sampler. Also set
viewsto 1 for Fun ControlNet compatibility.
MiniMax H3 Loop needs a length of at least 22 frames (one 17-frame clip plus the 5-frame tail)
- Explanation: This exact error comes from the shared wrapping helper when it receives an empty sequence to extend. In a loop workflow, a sequence that is too short can leave no complete loop clip after the required tail is removed.
- Solution: Use a latent video length of at least 22 frames and follow the
17k + 5length rule. Check the latent creation settings and confirm that a valid, nonempty sequence reaches sampling and decoding.
Fun ControlNet does not work correctly with views set to 2
- Explanation: This is a documented compatibility problem, not an exact exception string provided in the source. The
viewstooltip explicitly states that the two-view mode is not usable with Fun ControlNet. - Solution: Set
viewsto 1 whenever Fun ControlNet is part of your workflow, and ensure that the loop patch is applied before the Fun ControlNet patch.
Unexpected loop length or problems with a latent length outside the 17k + 5 pattern
- Explanation: This is a workflow symptom rather than a quoted error message. The loop format uses groups of five video latent frames representing 17-frame clips, followed by a two-latent tail representing five video frames. The companion decoder calculates the number of complete clips using integer division, so unsupported lengths should not be expected to produce the intended duration.
- Solution: Set the latent video length to
17k + 5with a positive integerk, such as 107, 158, or 209 frames. Calculate the intended finished loop length as the configured frame count minus five.
Visible or audible discontinuity after decoding
- Explanation: This is a possible output-quality issue rather than an exception shown in the code. The loop workflow depends on wrapped context during both sampling and decoding; using a different decoder may omit the companion decoder’s boundary handling and trimming. The loop patch also does not guarantee that every generated motion or sound will repeat perfectly.
- Solution: Confirm that your sampler receives the patched model and decode its result with MiniMax H3 Loop Decode using compatible VAEs. Verify the latent length, try
views = 2for audio-boundary problems when Fun ControlNet is absent, and compare a modest increase inpad_clipsif the join still needs improvement.
Sampling takes substantially longer than expected
- Explanation: This is expected performance overhead rather than a specific error. Each additional padding clip increases the amount of context processed on both sides, and
views = 2adds a second, half-rotated sampling view with an estimated sampling-time multiplier of about 1.8. - Solution: Use
pad_clips = 1andviews = 1for initial tests. Enable the second view or increase padding only after confirming that the basic workflow works and that the extra processing benefits your result.
