kubakub mask animate

What it's for

This is the node that makes a static building move. It outputs one mask per frame - a whole clip's worth - so a wipe travels across the facade, a band runs along a wall, an iris opens on a window, or the mask itself drifts, turns, scales or strobes.

Its natural partner is kubakub mask field, which supplies the grey ramp the move travels along. Mask field decides where; mask animate decides when and how. Chain two of them (masks output into the next node's mask input) and you get two moves at once - a wipe and a scale, a band and a strobe.

And it doesn't need a diffusion model to be useful: feed the masks into MaskToImage → Create Video and you've generated a projection-mapped animation with no AI in the loop at all. For a working VJ that's arguably the most valuable thing in the pack.

How it works

Two dropdowns do everything, and separating them is the whole design.

effect is what moves. Along the field: reveal (black to white), hide, band (a stripe travelling through), rings (stripes that keep coming). The mask itself: move x, move y (in picture widths/heights), rotate (in turns), scale (1 = as-is), opacity (0 to 1).

curve is how the value runs over time. ramp runs once and stays. saw runs again and again. triangle goes there and back. sine is the soft version of that. square is on/off - with opacity that's a strobe, with duty controlling how long the on part lasts. random picks a new value every cycle, noise wanders. Then the sound curves: sound level follows loudness, and beats / bars / low / mid / high hits each start a fresh ramp when one lands.

That last group is the party trick. Sound curves work with no audio connected - they fall back to a built-in 120 bpm beat - and with audio you get tempo detection, nth to use only every second or fourth hit, threshold and gap for detecting actual hits rather than rumble, and listen to pick which frequency band counts (kick, hats). steps is the one worth playing with: at 1, every beat replays the same move; at more than 1, each beat advances by that many steps, which is how you get one more region lighting up per beat when the field is a region order ramp.

The curve is literally drawn on the node - buttons set the type, dragging left/right on the curve changes the speed. Small thing, but it means you can dial a tempo without staring at numbers.

Inputs and outputs

Set these first: effect, curve, cycle (seconds per cycle - or for beats and hits, seconds the ramp takes after each one), value_from / value_to (the bottom and top of the curve, in whatever units the effect uses), easing, and width/rings/soft for the band and ring effects.

Then the ones you'll come back to: trail (seconds a place keeps glowing after the mask has moved past - 0 by default, and it's the difference between a wipe and a comet), fps, seconds (0 means take the length from the sound, else the mask batch, else 4 seconds), and scale (0.05 to 1, mask resolution relative to the input - at 250 masks of 3840×2160 a full-size batch is around 8 GB of RAM, so scale down while you're iterating).

Optional inputs: mask (what's being animated - for the field effects it limits the result), field (the ramp; empty means a plain left-to-right ramp over the mask), audio, plus phase, duty, seed, listen, gain, release, nth, steps, threshold, gap, bpm, start, pivot and wrap for the specific curve and effect you picked.

Outputs: masks (one per frame), fps, audio (the sound, cut to the frames - silence if none, so it's always safe to wire into Create Video), frame_count, and report (frames, size, the curve's range, and whatever tempo or hits it found). That fps/audio pair is what makes the output directly video-ready.

Install

Manager → search kubakub nodes → install → restart. Or:

cd ComfyUI/custom_nodes
git clone https://github.com/kubakubkub/ComfyUI_KubaNodes
python -m pip install -r ComfyUI_KubaNodes/requirements.txt

ComfyUI 0.37.0+; opencv-python-headless is the only added package (keep an existing OpenCV build). Both mask nodes landed in 0.3.0 and added no new dependencies. There's a model-free example workflow - example_workflows/mask_animate.json - that runs with nothing connected.

Common issues

• RAM explosion. 250 frames of 4K float masks is about 8 GB. Drop scale to 0.5 while you tune, and set seconds to something honest.
• The sound curves do nothing useful. Check bpm (0 = detect, and detection is only as good as the track), threshold for hits, and listen so your kick isn't being masked by hi-hats.
• Nothing connected, still got masks. By design - it runs a sample. Great for learning, confusing the first time.
• Two moves at once. Chain two nodes: the first node's masks into the second's mask. It's the documented approach, not a hack.