Nodes/FunUI/FunUI Decode
ComfyUI Node

FunUI Decode

The VAE decode that knows some latents have two parts

By digital-garbage·Created about a year ago·Updated about 14 hours ago· 21
FunUI Decode
  • samples
  • vae
  • model
  • audio_vae
  • images
  • audio
  • status
◄tile_size0►

Core's VAE Decode assumes your latent is one tensor. For most of ComfyUI's history that was a safe assumption. It isn't any more: MiniMax H3's latent carries a video branch and an audio branch, they need two different VAEs, and how they're arranged is the model's business, not ComfyUI's. Feed a latent like that into the stock node and you get either a shape error or - worse - a decode that technically succeeds and produces a picture that is not the picture you sampled.

FunUI Decode is the version that asks the model what it is before decoding.

How it works

The node walks a registry of model modules looking for one that will claim the decode. That's why model is an input: a provider can then answer "is this mine" by identity rather than by shape. The author's reasoning is spelled out in the source and it's a good one - without the model, the H3 module would claim any latent that happened to have two parts, which is correct today (H3 is the only thing producing one) and silently wrong the day a second audio-video model shows up. Deciding from shape is how a model mismatch becomes a mystery fault instead of an error message.

If a provider does claim the latent and then throws, the node raises instead of quietly falling back to a plain decode. That's the important half: falling back would decode a nested latent as if it were one tensor, and you'd get the wrong picture with no error at all.

If nothing claims it and the latent is nested, you get a flat refusal - "This latent has more than one part and no installed module knows how to decode it" - with a pointed extra line if you left the model input unwired. Otherwise you're on the ordinary path: a tiled VAE decode with your tile_size, and a 5D batch reshaped into a strip of frames.

The inputs that matter

  • samples - the LATENT out of the sampler.
  • vae - the picture VAE.
  • model (optional, wire it anyway) - this is the one people skip, and it's the one that lets the node recognise a model with a custom decode. It costs nothing to connect.
  • audio_vae (optional) - only for models that generate sound with the picture.
  • tile_size - 0 means the model's own way. For H3 that's ComfyUI's 256px tiles, which is the size its decoder was trained at, so bigger tiles give you a visible grid. An X2 Detail VAE is always tiled, 256 minimum, whatever you put here.

Out comes images, audio (nothing for a silent model - that's not a bug), and a status string that says which path ran: a module decoded it, or it was decoded as a single latent.

What it doesn't do

It doesn't save anything. Decode gives you frames and sound; writing a file is a save node's job. In FunUI's own pipeline that's its Save Video node, which is core's SaveVideo on a single CPU thread. You don't need VideoHelperSuite in the middle, and adding it buys you nothing here.

Installing it

cd ComfyUI/custom_nodes
git clone https://github.com/digital-garbage/FunUI
pip install -r requirements.txt

Manager search works too - the pack title is FunUI, and comfy node install FunUI pulls it from Comfy Registry. Restart, and note that FunUI's nodes only appear if their module is switched on (Settings ▸ Modules) and loaded; a module that fails to load is left out and the run carries on, which is by design but does mean a missing node isn't always a missing install.

The heavy bits are comfy-kitchen>=0.2.32 (compiled against torch, needed for the H3 sparse-attention path, not for decode) and gguf. If pip offers to upgrade torch or numpy, don't let it - the pack is written to install only what's missing, and you should follow the same rule by hand.

Where people get burned

Grey, washed-out or black frames. That's a VAE problem, not a decode-node problem, and it's the oldest one in the book: the VAE doesn't match the model. Check models/vae before you start editing the graph.

The nested-latent error with a model you're sure is supported. Almost always the model input is empty, so no module could recognise the latent. Wire it.

Tiles for VRAM, then surprise grid lines. Tiling is a memory trade, and on H3 the training size is 256. Go up and you'll see the seams; go down and you'll see them too, in the form of softness. The default is the default for a reason.

CategoryFunUI/Output

Inputs (5)

NameTypeDefaultDescription
samplesLATENT—
vaeVAEThe picture VAE.
modeloptMODELThe model this latent came from. Needed only when a model has its own way of being decoded.
audio_vaeoptVAEOnly for models that generate sound alongside the video.
tile_sizeoptINT00–4096Decode in tiles of this many pixels, to fit less VRAM. 0 = the model's own way. MiniMax H3: 0 is ComfyUI's 256px tiles, the size its decoder was trained on; bigger tiles show a grid. An X2 Detail VAE is always tiled (256 at least).

Outputs (3)

NameTypeDescription
imagesIMAGE—
audioAUDIO—
statusSTRING—