kubakub director

What it's for

ComfyUI is a graph engine pretending to be a compositor, and it isn't a very good compositor. Placing five images on a facade, deciding what's in front, masking one layer with another, painting over a bit, grading the lot and keyframing a movement across a timeline - that's After Effects work, and doing it with Load Image → ImageCompositeMasked chains is how you spend a weekend on something a compositor does before lunch.

kubakub director is a compositing window inside ComfyUI built for exactly the facade case. You open it, you compose layers over the matrix, you clip layers to regions ("only the floor-1 windows"), you give them behaviours and a timeline, and you press Apply. The node then renders that composition at full size in the graph - and, crucially, hands downstream nodes what they need to re-diffuse the parts you changed. That last part is the reason this isn't "After Effects with extra steps": the composition isn't a dead-end render, it's a set of instructions the pack can turn back into region prompts.

How it works

One input is required: image, the base - your matrix, a render, or a photo of the building. Everything else is optional and everything else is a layer source:

• layers - images to place; a batch is several layers, all one size. Different sizes get imported in the window instead.
• layer_masks - masks for those layers (1 = keep). A mask with no image becomes a white layer you can use as a mask for other layers, which is the cheap way to build mattes in-graph.
• invert_masks - turn it on for Load Image masks, which are 1 where the picture is transparent. This one bites people.
• regions - the facade partition, to pick from, clip layers to, and cut holes with. Placed layers get added as new regions.
• scene - a kubakub scene, so you get clay, depth and ID views in the window.
• layer_names, seam_px - naming, and the width of the edge band in the changed mask.
• audio - a sound from the graph; after a run the window shows its waveform, tempo and beats, the sound behaviours follow it, and it goes back out on audio.

Then the input that confuses everyone the first time: flow. On hold until apply (the default), the director shows only its preview until you open the window and apply a composition - and the nodes after it wait. Nothing downstream runs on an empty composition, which is deliberate: you don't want a latent video model firing on a composition that doesn't exist yet. always lets the base pass straight through.

render_sequence, skip_h3_frames and sequence_scale are marked old in the schema; the modern path is kubakub director sequence. export and its friends write a delivery file straight from here (PNG 8/16, ProRes 4444/422 HQ, H.264/H.265, preview) to output/kubakub_director/<name>_<time>/. Light layers need Blender 4.x - those render in Cycles per frame.

Inputs and outputs

The outputs are the interesting half, because they're what makes this node more than a display:

• image - the composition at full size.
• changed - the re-diffused layers plus their edge bands. This is the mask you hand to the region sampler or seam pass to say "repaint here, leave the building alone".
• layer_masks - per placed layer, where the audience actually sees it.
• regions and plan_rules - the input regions with every placed layer added as a new region, plus rules in the region plan's syntax (actions, prompts, denoise) for the next diffusion pass. Compose visually, diffuse from the result.
• document - the composition JSON. Pass it to director sequence and keyframe clips (h3).
• director - the composition plus its sources.
• frames, fps, audio - the timeline's frames, rate and sound (silence if you connected none).
• projection_mask - the building's silhouette, 1 where building (all ones if the slot is off). Handy for export alpha.
• report - size, layers, what was placed, and waiting for apply while the flow holds.

Install

Manager → 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 or newer is a hard requirement - the pack is built on the newer node API and advanced inputs, and modules fail to load one by one without it (the console names them). The only package added is opencv-python-headless; keep an OpenCV build you already have. Blender 4.x for light layers, ffmpeg (via imageio-ffmpeg or PATH) for video layers and any export with sound. If the node menu gets overwhelming, copy kubakub.ini.example to kubakub.ini and switch groups off - remembering that a switched-off group makes its nodes show as missing in workflows that use them.

Common issues

• Nothing downstream runs. flow is on hold until apply and you haven't applied a composition. This is the single most common "the director is broken" and it isn't broken.
• Masks are inverted. That's invert_masks for Load Image masks. One toggle, endless confusion.
• Export refused. Asking for alpha in a format that can't carry it is rejected before anything renders (0.3.0 behaviour; older versions wrote the layers without the base, which looked like a bug, because it was one).
• Blender not found - 3D and light layers need 4.x, found in Program Files or on PATH, else set blender = ... in kubakub.ini.