comfyui-sampler-peek

comfyui-sampler-peek

Peek into ComfyUI sampling loops. Decode intermediate latents using a VAE during SamplerCustomAdvanced execution, controlled by math expressions.

Overview

Ever wanted to see what your image looks like during the sampling process? This extension lets you do exactly that — and more.

It replaces SamplerCustomAdvanced with SamplerPeekAdvanced, which wraps the same sampling loop but adds a step-by-step callback. At steps matching a configurable math expression, the current latent (x₀ prediction) is decoded through a VAE and collected into an image batch. Step indices are recorded alongside the images.

Nodes

SamplerPeekAdvanced (sampling/peek)

A drop-in replacement for SamplerCustomAdvanced. It accepts all the same inputs, plus a VAE and decode configuration.

| Input | Type | Description | |----------------|----------|-----------------------------------------------| | noise | NOISE | Noise source | | guider | GUIDER | Guider (e.g., CFGGuider) | | sampler | SAMPLER | Sampler to use | | sigmas | SIGMAS | Sigmas schedule | | latent_image | LATENT | Latent image to sample from | | vae | VAE | VAE model for decoding intermediate latents | | decode_expr | STRING | Expression for when to decode (see below) | | start_step | INT | Only decode at ≥ this step (1-based) | | end_step | INT | Only decode at ≤ this step (0 = no limit) | | max_previews | INT | Max previews to store in RAM (0 = unlimited) | | cfg_expr | STRING | (optional) Step-dependent CFG expression. e.g., clamp(1 + step / n * 7, 1, 8) for a linear ramp from 1 to 8 |

| Output | Type | Description | |------------------|--------|------------------------------------------------| | output | LATENT | Final sampled latent | | denoised_output | LATENT | Final x₀ prediction | | preview_images | IMAGE | Batch of decoded preview images | | step_indices | INT | Step indices (1-based) for each preview image |

StepExpression (sampling/peek)

Evaluate a math expression with step context. Returns both the float value and boolean truth.

| Input | Type | Description | |-------------|----------|--------------------------------------| | step_index | INT | Current step index (1-based) | | total_steps | INT | Total number of steps | | expression | STRING | Math expression to evaluate |

PeekStepIndex (sampling/peek)

Extracts a scalar step index from the tensor output of SamplerPeekAdvanced.

PeekConditionGate (sampling/peek)

A conditional multiplexer: passes true_value when condition is True, false_value otherwise.

Expression Syntax

The decode_expr and StepExpression nodes use a safe math expression evaluator. Available variables and functions:

| Variable | Description | |-------------|-----------------------| | step | Current step (1..n) | | n | Total steps | | total_steps | Total steps (alias) |

| Function | Description | |-------------|------------------------| | sin, cos, tan | Trig functions | | sqrt, log, exp | Math functions | | ceil, floor | Rounding | | clamp(x, lo, hi) | Clamp value | | lerp(a, b, t) | Linear interpolate |

Examples:

• step % 5 == 0 — decode every 5th step
• step >= 10 and step <= 20 — decode steps 10–20
• step == 1 or step == n — decode first and last step
• sin(step / n * pi) — sine ramp for dynamic schedules
• step % 2 == 0 — decode even-numbered steps

Dynamic CFG

Optionally provide a cfg_expr to modulate CFG at each sampling step:

• clamp(1 + step / n * 7, 1, 8) — linear ramp from 1 to 8
• step < n / 2 ? 1 : 5 — use Python: 5 if step > n/2 else 1
• 1 + sin(step / n * pi) * 4 — sinusoidal CFG swing

Installation

1. Clone into ComfyUI's custom_nodes directory:

   cd ComfyUI/custom_nodes
   git clone https://github.com/aria4comfyui/comfyui-sampler-peek.git
   

2. Restart ComfyUI.

No additional dependencies required — it uses only ComfyUI's built-in libraries (PyTorch, etc.).

Usage

1. Replace SamplerCustomAdvanced with SamplerPeekAdvanced in your workflow.
2. Connect a VAE to the vae input.
3. Set decode_expr to control which steps produce previews.
4. (Optional) Set cfg_expr for step-dependent CFG modulation.
5. Connect preview_images to a SaveImage or PreviewImage node.
6. Queue and watch the sampling process unfold!

License

MIT