Bokeh Level

Bokeh Level is the control panel for the whole Bokeh Diffusion pack - the node that answers "how blurry is this image supposed to be?" It's a pure parameter node: no model, no download, no network. You dial in a number and it hands the sampler a BOKEH_CONTROL object that tells it how much defocus to apply while it denoises.

It sits between the model plumbing (Apply Bokeh Adapter) and the sampler (Bokeh KSampler), and the output - bokeh_control - feeds the sampler's bokeh_control input. That's the only connection it makes.

The inputs

• bokeh_level - the one you'll actually touch. A float from 0 (sharp) to 30 (maximum blur), defaulting to 15. Internally the node normalizes it to 0–1 and stuffs it into the attention path, but for you it's just a dial. Start around 8–12 and nudge up until the background actually looks like a lens did it; 30 is full abstract-blob territory.
• bokeh_pivot - the anchor level for "grounded generation," the pack's name for scene-consistent blur. Optional, defaults to 15.
• num_grounding_steps - how many early sampling steps stay pinned to the pivot level before transitioning to your target. 0 disables grounding entirely; the tooltip recommends 18–24 if you use it.

The two modes

In its default state (just bokeh_level, grounding disabled) the node produces a single target and the whole image is generated at that blur level. That's "unbounded generation" in the README's words - simple, and enough for most use.

Grounded generation is the interesting one. When you set a bokeh_pivot and a nonzero num_grounding_steps, the sampler keeps the scene anchored at the pivot blur for the first N steps, then transitions to your target for the rest. The mechanism in the source is a batch swap: the attention processors duplicate and swap query/key rows between the pivot and target embeddings during those early steps, which is how the scene stays consistent instead of re-solving itself at a different blur. The practical payoff is smooth, believable defocus transitions - the kind of thing that makes a portrait read as shot on an actual fast prime rather than pasted on a blurry background. The cost is a chunk of extra compute on the early steps, so only turn it on when consistency actually matters.

Installing the pack

This node ships in the same pack as the rest: ComfyUI Manager, search BokehDiffusionComfyUI, or:

cd ComfyUI/custom_nodes
git clone https://github.com/jrabek/BokehDiffusionComfyUI

Restart ComfyUI, and confirm the pack's real dependencies are installed (diffusers, transformers, huggingface_hub, opencv-python) - the README's quick install list omits OpenCV, but requirements.txt doesn't, and it won't hurt to have it.

Gotchas

Since this node only packs floats into a dict, it basically can't fail on its own. The things to remember: if num_grounding_steps is 0 (or no pivot is set), grounding silently does nothing - it's not a bug, that's the off switch. And don't expect it to do anything by itself; without the adapter applied upstream and Bokeh KSampler downstream, the BOKEH_CONTROL you generate just goes nowhere.