# ComfyUi-MpiNodes A ComfyUI custom node pack by [Mad Pony Interactive](https://github.com/MadPonyInteractive) with over 100 utilities for logic, math, prompt generation, image operations, model management, and workflow automation. [![Registry](https://img.shields.io/badge/Comfy%20Registry-mad--pony--interactive-blue)](https://registry.comfy.org/publishers/mad-pony-interactive/nodes/ComfyUi-MpiNodes) **These nodes power [Cubric Vision](https://github.com/MadPonyInteractive/Cubric-Studio)** — a free, open-source desktop app for AI image and video generation. Vision installs and manages ComfyUI, the models and this pack for you, and wraps them in a real editing UI: gallery, masking, inpainting, painting, cropping and project management. If you found this pack through one of our workflows, the app is where those workflows come from. --- ## Nodes ### Prompt Generation Build, process, randomize, and route prompts with fine-grained control. | Node | Description | |---|---| | **MpiPromptList** | Create a prompt list with options, probability, and blocking rules. Supports prefix/suffix, amount selection, specific item picking, probabilistic shuffling, and chaining. | | **MpiPromptProcessor** | Process prompt lists into positive and negative prompts by replacing `_title_` tokens with selected options. Handles multipliers (e.g. `_title_x2_`) and cleanup. | | **MpiPromptListSelector** | Probabilistically select between two prompt lists based on seed and probability. | | **MpiPromptChainSelector** | Select one list from a prompt chain using a seed. | | **MpiPromptListJoin** | Join two prompt lists or chains. | | **MpiPromptBridge** | Pass-through utility that forwards a prompt list and seed values. | | **MpiPromptOverride** | Override prompt list options with custom text and optional seed override. | | **MpiHasOptions** | Check if selected options contain any of the specified options. Returns a boolean. | | **MpiDisplayPrompt** | Display prompt list contents for debugging — outputs titles, blocklists, and processed prompts as strings. | | **MpiRandPromptGen** | Generate random prompts from preset lists with customizable sections (shot type, hair, clothes, pose, expression, location, lighting). Supports indoor/outdoor probability, pronoun selection, and bright/dark lighting. Leave `preset_folder` empty for the bundled preset; a custom preset folder must sit inside ComfyUI's `input/`, `output/` or `temp/` (relative paths resolve under `input/`). | | **MpiRandPromptGenOrder** | Set custom section order and transitions for random prompt generation. | | **MpiRandPromptGenOverrideSection** | Override specific section options and seed for random prompt generation. | | **MpiRandPromptGenOverrideList** | Override preset list options for random prompt generation. | | **MpiRandPromptGenSave** | Save a random prompt preset to `/` inside ComfyUI's `output/` folder and output that path, which MpiRandPromptGen's `preset_folder` accepts as-is. A destination outside `output/` raises. | --- ### Logic & Control Flow Primitive operations for comparisons, type conversions, rounding, and boolean logic. | Node | Description | |---|---| | **MpiCompare** | General logic operator comparing two values with `==`, `!=`, `>`, `<`, `>=`, `<=`. `b` can be wired or typed into the `b_value` widget. | | **MpiBooleanCompare** | Compare two booleans with modes: equal, not_equal, both_false, both_true, one_is_true, not_both_true, etc. | | **MpiBooleanInvert** | Invert a boolean — true in, false out. A pass-through NOT gate; wire-only input, no widget. | | **MpiConvert** | Convert any value to STRING, INT, FLOAT, and BOOLEAN outputs simultaneously. | | **MpiRoundToMultiple** | Round a single integer to the nearest multiple (up or down). | | **MpiRoundToMultipleRes** | Round width and height to the nearest multiple simultaneously. | | **MpiBoolean** | Pass through a boolean → outputs boolean, int, and float. | | **MpiSimpleBoolean** | Pass through a boolean value only. | | **MpiFloat / MpiInt / MpiString / MpiText** | Pass-through nodes for float, int, string (single-line), and text (multiline) values. | | **MpiListCount** | Count entries in a list of any type. Outputs `count` (INT) and `has_items` (BOOLEAN, true if non-empty). | | **MpiIsListEmpty** | Check whether a list of any type is empty. Outputs `is_empty` (BOOLEAN, true if zero items) and `count` (INT). Route `is_empty` into an if/else to skip nodes that would `IndexError` on an empty list. | | **MpiBlockIfEmptyList** | Pass a list through, but block downstream execution if it is empty. Place before nodes that index into a list so an empty list halts the branch instead of throwing `IndexError`. Unlike MpiAnyBlocker, it receives the whole list, so a truly empty list still reaches it. | | **MpiListRange** | Output a sub-range of any list using inclusive `start`/`end` indices. Negative indices count from the end. Outputs sliced list and its count. | | **MpiTextContains** | Check whether any of several words or phrases (multiline box, separated by commas or new lines) appears in an input text as a whole word. Case-insensitive and plural-aware, so `cat` matches `a CAT sits` and `two cats` but not `catalogue`. Multi-word entries ignore spacing, so `bird in a tree` still matches across a line break. Irregular plurals (`child`/`children`) need their own entry. Outputs a BOOLEAN — use as a whitelist/blacklist check on a prompt. | | **MpiReroute** | Pass any value through unchanged. Rename the node title for a labelled reroute. | | **MpiConditioningReroute** | Pass `positive` and `negative` conditioning through unchanged — a labelled conditioning reroute. | | **MpiAnyBlocker** | Pass any value through, but block downstream execution if it is empty (empty string/list/dict/None/zero-element tensor/empty audio). 0, 0.0 and False pass through. | | **MpiBlocker** | Manual gate: pass the input through when the switch is on (continue), block the branch when off (block). The input is **lazy**, so blocking also skips everything feeding this node — not just what comes after it. | | **MpiAnyChecker** | Pass any value through unchanged and output a `has_value` boolean — true if non-empty, false if empty. Same emptiness rules as MpiAnyBlocker. | | **MpiSeedPassthrough** | Pass any value through and emit a `seed`. Forces the workflow to re-run every time (via `IS_CHANGED`) so seed-less workflows don't get stuck on cached outputs. Leave `any` unconnected to use as a pure seed source. | | **MpiLogger** | End-of-chain logger with no output — prints when its input arrives. `mode="value"` logs the input value with a prefix; `mode="message"` logs only the message text, marking that the point was reached without dumping the input. | | **MpiExecLogger** | Pass any input through to its output while logging a message to the console — wire inline to print workflow progress. | --- ### If / Else Routing Conditional and probabilistic routing of values and inputs. | Node | Description | |---|---| | **MpiIfElse** | Output true or false value based on a boolean condition (lazy evaluation). | | **MpiIfElseInverted** | Route input to output A or output B based on a boolean condition. | | **MpiIfElseProbability** | Probabilistically choose between true and false using seed and probability. | | **MpiIfElseProbabilityInverted** | Probabilistically route input to true or false output. | --- ### Switches Route any type of input to a selected output by index. | Node | Description | |---|---| | **MpiAnySwitch** | Select one of up to 5 inputs of any type based on selection index. | | **MpiAnySwitch10** | Select one of up to 10 inputs of any type based on selection index. | | **MpiLoraSwitch** | Select one of up to 5 LoRA files by index. | | **MpiAnyInvSwitch** | Route an input of any type to one of up to 5 outputs (inverted switch). | | **MpiPacker** | Bundle up to 5 values of *any* type (image + float + int + boolean + …) into one `MPI_PACK` wire. Unconnected slots stay empty. A pack is just a list, so a pack can go into another packer's slot — 5 packers into a packer carries 25 values on one wire. | | **MpiUnpacker** | Unpack an `MPI_PACK` back into 5 outputs, in the same slot order they were packed. Slots that were empty block execution downstream, so nothing runs on a missing value. | | **MpiPacker10** | Same as MpiPacker with 10 slots instead of 5. | | **MpiUnpacker10** | Same as MpiUnpacker with 10 outputs instead of 5. Feeding a 10-slot pack into the 5-slot MpiUnpacker drops the tail and logs a warning. | | **MpiPacker2** | Same as MpiPacker with 2 slots instead of 5 — the pair case (width + height, image + mask) without three empty sockets. | | **MpiUnpacker2** | Same as MpiUnpacker with 2 outputs instead of 5. A longer pack drops its tail and logs a warning naming how many outputs are needed. | | **MpiComparePacks** | Compare two packs slot by slot. Outputs `equal` (true only if every slot matches) and `first_diff`, the 1-based slot of the first mismatch (0 when equal). Images and other tensors compare by content, and nested packs compare all the way down — this is the pack-safe alternative to MpiCompare, which raises on tensors. | | **MpiStringInvSwitch** | Route a string input to one of up to 5 outputs. | --- ### Image Operations Dimension math, aspect ratio, bounding box conversion, and grid tiling. | Node | Description | |---|---| | **MpiScaledDimensions** | Scale image dimensions proportionally to a target size (use_max or use_min side). Returns width, height, is_portrait boolean, and the image resized to those dimensions (upscale_method selects the interpolation). | | **MpiAspectRatio** | Calculate aspect ratio from width/height. Outputs `string` (1:1, 4:3, 3:2, 16:9, 9:16, 2:3, 3:4) and `pack`, a 2-slot `MPI_PACK` carrying width then height on one wire — MpiUnpacker2 gives them back in that order. | | **MpiGetImageAtIndex** | Return the image at a specified index from a batch. Supports negative indexing (-1 = last). | | **MpiBboxToMask** | Convert bounding boxes (xyxy or xywh format) to mask tensors. | | **MpiGridDimensions** | Calculate grid dimensions and corrected source size for perfect tiling — avoids repeated tiles when fed to UltimateSDUpscale. Has auto mode. | | **MpiUpscaleModelScale** | Takes a `Load Upscale Model` node (or any UPSCALE_MODEL input) and reads its native scale (1x/2x/4x/8x) from the model's descriptor metadata. Outputs INT and FLOAT. fallback_scale used only if metadata is absent. | | **MpiLoadImageFromPath** | Load an image from a file path with an in-graph preview. Outputs image, mask, width, height and `loaded`. A channel combo (alpha/red/green/blue) selects the mask source. Blocks downstream execution if the path is empty, unless block_if_empty is off (then outputs a blank 1x1 image so the graph continues). `loaded` is true only when a file was actually read and is never blocked, so it can gate other branches directly (no MpiAnyChecker needed). The path is resolved inside ComfyUI's `input/` folder (an absolute path must sit inside `input/`, `output/` or `temp/`); anything outside is treated as missing. | | **MpiLoadImage** | Load Image with the extras above: pick, drag-and-drop or paste an image (the ComfyUI frontend uploads it into `input/`, exactly like the built-in Load Image), preview it in-graph, and get image, mask, width, height and `loaded`. Same `channel` and `block_if_empty` as MpiLoadImageFromPath. The `string` widget takes a file name inside `input/`, with its subfolder if it has one (an absolute path inside `input/`, `output/` or `temp/` also works; png/jpg/jpeg/webp/bmp/gif/tif/tiff). `string` is tried first, so an app can inject the file there; if it is empty or does not load, the picked file is used. Nothing is loaded, and `loaded` is false, only when both fail (picker on **None**, the default). Workflows an app injects into should be saved with the picker on None. | | **MpiCrop** | Crop an image to width/height at a chosen anchor (center/left/right/top/bottom). width/height of 0 keep that dimension full; the crop is floored to a multiple of divisible_by. | | **MpiMaskSquareBbox** | Square bounding box around a mask, centered on the mask and clamped (shrunk if needed) to stay fully inside the image. Outputs a filled square MASK plus x, y, and side length. Optional padding around the tight box. On a batch — a video mask — the box is the **union of every frame** and the square is returned **for every frame**, so the region holds still for the whole clip instead of crawling, and a video consumer gets as many mask frames as it was given. | | **MpiMaskBbox** | Tight **rectangular** bounding box around a mask, as an `MPI_BOX` plus width and height — and the mask passed through **untouched**. That is the difference from **MpiMaskSquareBbox**, which squares the box and returns a filled block where the mask was: one wire here crops the plate by the box and composites back through the real mask shape. `padding` widens the tight box; `divisible_by` rounds width and height **up** to a multiple and re-centres, for a consumer that needs its dimensions on a grid. On a batch — a video mask — the box is the **union of every frame**, so the crop holds still for the whole clip instead of crawling. An empty mask gives a zero box rather than raising. | | **MpiMaskFillHoles** | Fill the enclosed holes in a mask — SAM3 routinely drops the lips and teeth out of a `face` or `head` mask, and a composite then paints straight through the gap. Only touches pixels the mask already surrounds, so unlike a grow/shrink close the outer silhouette is untouched and no gap gets welded shut. `max_hole_size` caps it by **area in pixels**; 0 fills every hole. A hole is not a bite — an open mouth reaching the jaw line breaks the silhouette rather than being enclosed, and no fill can reach it, so add `mouth` to the SAM3 vocabulary for that. | | **MpiBox** | Build an `MPI_BOX` rectangle from width/height/x/y, where x/y are the **top-left** corner. One wire carries a region into any box-aware node instead of four loose INT sockets. Consumers clamp the box to the image, so out-of-bounds values are safe — and x/y may be **negative**, so a box can start outside the image to sit tight on a subject at the frame edge. | | **MpiFromBox** | Unpack an `MPI_BOX` back into width, height, x, y integers — the escape hatch for feeding raw INTs to other nodes. | | **MpiBoxCrop** | Crop an image to an `MPI_BOX` region. Outputs the cropped image plus the clamped box actually used. A box fully outside the image passes the image through unchanged. `pad` (optional, off by default) pads an overhanging box back out to its requested size by replicating the edge pixels, so the crop keeps the aspect that was asked for — what a square reference crop needs. | | **MpiBoxMask** | Build a mask the size of the image — black with a white rectangle at the `MPI_BOX` region. Outputs the mask plus the clamped box actually drawn. | | **MpiInpaintHeal** | Heal an inpainted region against the real pixels around it — corrects colour drift and restores fine grain by matching a ring of untouched pixels hugging the mask. Unlike a colour-match on a rectangular crop, the ring never contains the removed object, so it cannot pull the fill toward it. Run after stitching. | | **MpiGradeMatch** | Composite a **re-render** over the original through a mask, **graded to match it** first. Outside the mask both show the same content, so the difference there is grading drift alone (a video model re-renders a crop a touch lighter or warmer); a per-channel gain + offset is fitted on those paired pixels, **per frame**, on a `band`-wide ring round the mask (0 = all of outside), refitted three times without the pixels that move through the ring, and applied to the source. The seam lines up and what the mask keeps keeps its **own** colours. Not **MpiInpaintHeal**, which moves a fill's colour toward its surroundings and would tint an added object: this one needs the original and the re-render of the same shot. A mask batch of 1 holds for every frame; a different-size source or mask is resampled; differing frame counts raise. | | **MpiMaskDebugInfo** | Print mask shape, dtype, and device info to the console for debugging. | | **MpiMaskPreview** | See where a `MASK` lands on an image, in one node — paints a flat `color` through the mask onto `destination` and previews it in-graph, instead of wiring `Empty Image` + `Image Composite Masked` + `Preview Image` every time. `invert_mask` swaps which side is painted; `alpha` fades the paint so you can see the plate under it, which is the whole point of looking. No `source`, no x/y and no `resize_source` — a debug view, not a compositor. `index` picks **one** frame out of a batch (negative counts from the end, out of range clamps), so a 124-frame clip does not render 124 thumbnails; a mask batch of 1 is treated as one mask for the whole clip. A mask at a different resolution is resampled **nearest**, so a blocky mask still looks blocky here rather than being smoothed into looking correct. | | **MpiAddImageToList** | Append an image to a list of images. | --- ### Math | Node | Description | |---|---| | **MpiMath** | Evaluate a Python expression on inputs `a`, `b`, `c` (b and c optional). All `math` module functions are in scope. | | **MpiExpoFloat** | Apply a power curve to a 0–1 float: `value ^ exponent`, clamped to [0, 1]. | | **MpiClamp** | Clamp an int or float between `min_value` and `max_value`. With min 200 / max 1000: `400` stays `400`, `2000` becomes `1000`, `100` becomes `200`. Preserves int inputs. | | **MpiNormalizeValue** | Normalize a value from an input range to an output range with optional transforms (linear, inverse, log, exp) and clamping. | --- ### LoRA & Checkpoint | Node | Description | |---|---| | **MpiLoraModel** | Apply a LoRA to a model only, with strength control. | | **MpiLoraModelClip** | Apply a LoRA to both model and clip with independent strength controls. | | **MpiDoubleLora** | Apply the same LoRA to two models and clips simultaneously with strength controls. | | **MpiStyleSelector** | Style router: one `selector` integer plus a list of trigger words, feeding a chain of MpiStyleLoras banks. Outputs an `MPI_STYLE` bundle. | | **MpiStyleLoras** | A bank of 5 LoRA slots for an MpiStyleSelector — applies only the LoRA matching the selector. Chainable (bank 1 = selector 1-5, bank 2 = 6-10, …), outputs model, clip and prompt. | | **MpiFromCheckpoint** | Extract model, clip, and VAE from a checkpoint. | | **MpiToCheckpoint** | Combine model, clip, and VAE into a checkpoint. | --- ### Conditioning | Node | Description | |---|---| | **MpiMultiTextX2 / X3 / X4 / X5** | Combine 2, 3, 4, or 5 text inputs into one. | --- ### Text & String Operations | Node | Description | |---|---| | **MpiBatchTextReplace** | Batch find and replace text in all `.txt` files within a folder. Handles UTF-8 and cp1252 encoding. `input_folder` resolves under ComfyUI's `input/` (or `output/`) folder and `output_folder` under `output/`; paths outside them are refused. | | **MpiTextListReplace** | Find and replace text in each item of a text list. | | **MpiTextListJoin** | Prepend or append text to each item in a text list. | --- ### Animation Timing (Wan) | Node | Description | |---|---| | **MpiWanFrames** | Calculate duration from frame count and FPS. Returns frames, seconds, and fps. | | **MpiWanSeconds** | Calculate frame count from duration (seconds) and FPS. Returns frames, seconds, and fps. | | **MpiWanMaskedVideo** | Wan 2.1 image-to-video conditioning from a WHOLE guide video plus one hole mask a frame (white = invent here): Wan keeps the known pixels and invents the holes. With the Matrix-3D 360 LoRA this renders a camera path through a 360 panorama and invents what the path walks into. Matrix-3D's masked-video latent concat, ported from ComfyUI-SplatKit (MIT, notice in `wan_masked.py`); identical output to its `WanI2VMaskedConditioning` with `invert_mask` on. | --- ### JSON | Node | Description | |---|---| | **MpiJsonLoad** | Load a JSON file and output it as a dictionary. `path` resolves inside ComfyUI's `input/` folder (an absolute path must sit inside `input/`, `output/` or `temp/`); leave it empty to use the `file` picker, which lists the `.json` files in `input/`. A path outside those folders loads as `{}`. | | **MpiJsonSave** | Save a dictionary to a JSON file inside ComfyUI's `output/` folder (relative path, missing subfolders created) and output the written path. A path outside `output/` raises. | --- ### Utilities | Node | Description | |---|---| | **MpiClearVram** | Offload all models from VRAM to RAM, clear GPU cache, and run garbage collection. Passes through a value to chain in workflows. | | **MpiClearVramEnd** | The same clear, as a **terminal** node with no output. Clearing VRAM properly needs one per terminal branch, because the node only runs on branches that actually execute — a single clear hung off the preview branch leaves the models resident for every other branch, and nothing reports it; the symptom is an OOM later in the graph with `0 models unloaded` in the log. The pass-through version has to be spliced *into* a branch, which means moving an existing link, so covering three sinks (a latent, a decoded image, a decoded audio) means three rewires. This one hangs off the **end** of a branch and changes nothing downstream, because there is no downstream. The `trigger` input is required and exists only to place the node in execution order — an unconnected sink would run at an arbitrary point, which is the one thing a VRAM clear must not do. | | **MpiAudioRange** | Cut a soundtrack to a **frame** range, using the same inclusive `start`/`end` that `MpiListRange` takes — so one pair of numbers windows the picture and the sound together. Exists for windowed work on an audio-video model: cutting the frames and leaving the audio whole hands the model a soundtrack that does not line up with the picture, and nothing downstream can notice — every tensor is valid, the result is just conditioned on the wrong moment. Wire the loader's own `fps`; a guessed rate slides the audio rather than failing. Negative indices count back from the **last sample**, not from a frame count rounded off the track (a real soundtrack is almost never whole frames), so `-1` is the true end; to trim a padded track to its picture, pass the video's frame count - 1 as `end`. | | **MpiImageSplice** | Write a run of frames back into a longer clip at a given frame — the return leg of windowed work: cut a window out, run the expensive thing on it alone, splice the result back. Pairs with `MpiH3DecodeAV`, whose output outside the mask is already the original pixel, so the window boundary is exact and needs no blending. A mismatched canvas, or a patch running past the end, raises — either one otherwise lands as a clip that plays but is wrong. | | **MpiAudioSplice** | Write a run of audio back into a longer soundtrack at a **frame** offset — the sound half of what `MpiImageSplice` does for picture, and the inverse `MpiAudioRange` shipped without. Takes the same inclusive `start`, so the number that cut a window writes it back. Windowed work on an audio-video model cuts both streams and has to splice both back; without this the regenerated soundtrack stays window-length while the picture comes back full-length, which reads as a video whose sound stops early rather than as a wiring mistake — VHS writes the short track without complaint. The crossfade is `MpiH3DecodeAV`'s own `splice_audio`, so there is one implementation of the equal-power fade rather than two that can drift. A patch running past the end raises and says by how many samples, naming the two things that actually cause it: a start that names a different window, or a patch from a different clip. An overhang of 1 ms or less is dropped instead: two frame offsets rounded to samples separately can disagree by a sample. A mono patch is expanded to a stereo track instead of broadcasting into a crash, and a cut spliced straight back is a bit-exact no-op. | | **MpiHasAudio** | Check if a video file (by path) contains an audio stream via ffmpeg. Outputs a boolean to gate an audio wire into CreateVideo. The path resolves inside ComfyUI's `input/` folder (`name [output]` reads `output/`; an absolute path must sit inside `input/`, `output/` or `temp/`); anything else reads as no audio. | | **MpiH3Length** | Convert a wanted duration into a valid MiniMax H3 frame count. H3 only generates `n % 17 == 5` frames at 24 fps, so whole seconds are mostly unreachable — asking for 2 s gives 2.33 s, and 8 s is the shortest exact one. Snaps to the **nearest** valid count (core snaps up, which is never closer), and outputs the true `seconds` plus `in_trained_range` (false outside 124–362 frames, where the model runs but was not trained). | | **MpiH3ImageToVideo** | MiniMax H3 image-to-video conditioning that tolerates EMPTY frame inputs, so one graph covers t2va, first-frame, last-frame and first+last instead of a pre-authored branch per combination. Core's `MiniMaxH3ImageToVideo` already skips a keyframe that arrives as `None`, but a graph cannot send `None` down a connected link, so a host app compiling a saved workflow had to carry four copies of the node behind a lattice of booleans. Empty means nothing connected **or** an Mpi loader with `block_if_empty` off (a 1×1 image) — a genuinely black first frame reports its true size and passes through untouched. The conditioning and the AV latent are built by core's own node, so the tensor maths cannot drift. Both frames are cover-cropped to the canvas first, because core is asymmetric about it — it stretches `first_frame` (`crop='disabled'`) and cover-crops `last_frame` (`'center'`), so an off-aspect source came back squashed and the two keyframes disagreed with each other. Crop, never pad: letterbox bars baked into frame 0 get animated as scenery. Also what makes a SECOND conditioning at upscaled dimensions practical, which is what an H3 latent-upscale refine pass needs: the keyframe latent is encoded at the first stage's width/height and core sizes its cond rows off the target grid, so an upscaled latent otherwise raises a shape mismatch in `SamplerCustomAdvanced`. | | **MpiH3References** | MiniMax H3 reference conditioning with every slot exposed at once — 9 images, 3 videos with paired soundtracks, 3 standalone audio. Core's node grows its slots one at a time, so a host app compiling a saved workflow would need a pre-authored branch per combination (2¹⁸ of them); this one takes them all and drops the empty ones itself, renumbering the survivors so core's index-based soundtrack pairing still lines up. Empty means nothing connected **or** an Mpi loader with `block_if_empty` off (a 1×1 image / 1-sample waveform) — real black images and real silence pass through. Conditioning is built by core's own `MiniMaxH3ReferenceToVideo`, so it cannot drift. Write the prompt against **slot** numbers — `

Name	Type	Default	Description
image	IMAGE		A wrap-padded image, resized or not since.
reference	IMAGE		The image as it was BEFORE Mpi Wrap Pad.
pad	INT	320–2048	Mpi Wrap Pad's pad.

Mpi Wrap Crop

Inputs (3)

Outputs (1)