FlashVSR One-Step Sampler

The one-step sampler you can't swap for a KSampler

By Pizzawookiee·Created about a month ago·Updated 7 days ago· 2

runtime

SAMPLER
SIGMAS

◄sampling_modefull_video_dense►

◄sparse_ratio2.0►

◄local_range11►

◄query_block_chunk1►

◄new_latent_frames2►

◄profile_cuda_eventsfalse►

◄qkv_projectionstock►

◄cache_formatint8►

◄cache_residency_backendcpu►

This is the node that does the actual FlashVSR work, and it's where the pack's whole personality lives. FlashVSR is a one-step streaming video super-resolution model - it produces the upscaled clip in a single denoising step instead of twenty - and that logic is not something a stock KSampler can reproduce. The README is unambiguous: "the provided sampler owns the one-step streaming logic; a regular stock sampler cannot replace it." So if you've got this far and the graph won't run, the fix is never "swap in a KSampler," it's "use this node properly."

How it works

You wire it into the standard ComfyUI sampling shell: BasicGuider gets the patched model and the FlashVSR prompt conditioning, this node supplies the SAMPLER and SIGMAS, and SamplerCustomAdvanced drives it. The SIGMAS output is just [1.0, 0.0] - one step, start to finish. The faithful modes need the CFG=1 single-pass optimization that BasicGuider gives you; run through anything else and they misbehave.

The interesting part is sampling_mode, the one input that shapes everything downstream:

streaming (not the default) - evaluates six latent frames first, then each continuation recomputes two overlap frames and appends two or four new ones. No DiT KV cache at all, which is why it drops memory the hardest. The README calls it the proven compatibility mode and generally the fastest.
streaming_faithful_full - the paper's layout: six-frame prefill, exactly two new frames per call, and a six-frame sliding K/V history kept in every Wan block. Closest to official FlashVSR, but the highest RAM and transfer cost. This is the mode to use when comparing against the paper or the official repo.
streaming_faithful_lowvram - same two-frame continuation layout, but each block only retains the nearest two historical frames. Roughly a third of the full cache, and the README's stated starting point on a 6 GB card. It exists because the earlier low-VRAM attempt only cached the last ten blocks and got boundary blur; this version caches two frames in every block so early blocks keep some temporal context.
full_video_dense (the dropdown default) - processes the whole clip in one dense-attention call. Do not read "default" as "recommended": the official project warns that replacing LCSA with dense attention can cut quality at high resolution, and this mode's VRAM grows sharply with clip length. The README frames it as a reference/control path, not the quality pick.

If I had one recommendation: on a 6–8 GB card start with streaming_faithful_lowvram; on a 24 GB card with plenty of system RAM, streaming_faithful_full; and keep streaming in your back pocket for when either faithful mode OOMs. The full_video_dense default is the pack being conservative with a diagnostic mode, not telling you what to run.

Inputs that matter

runtime (required) - the FLASHVSR_RUNTIME from Configure FlashVSR Upscaling. Nothing works without it.
sparse_ratio (default 2.0) - the LCSA top-k block budget. Not a percentage. Higher keeps more attention connections and usually stabilizes motion; lower can look sharper but flicker. With the dense-mask backend it's mostly a quality dial, not a speed dial. Keep the default.
local_range (default 11) - how far, in 8×8 Wan-token windows, attention may search spatially. Larger handles fast motion, smaller stays sharp. Keep the default.
query_block_chunk (default 1) - how many 128-query windows go to the backend at once; 0 auto-picks from free VRAM. Ignored if you're using the optional Sparge path.

The advanced options are worth one sentence each: new_latent_frames must stay at 2 for both faithful modes; cache_format (int8 default, hybrid, float) sets how the faithful K/V cache is stored - int8 is smallest, float the quality format; cache_residency_backend is cpu (reliable) or aimdo_experimental (an evictable GPU mirror, needs ComfyUI AIMDO); qkv_projection stays on stock; and profile_cuda_events prints a wall of CUDA timings - leave it off unless you're benchmarking.

Installing and troubleshooting

Same pack as the rest - ComfyUI Manager (search ComfyUI FlashVSR Stock Wan) or:

cd ComfyUI/custom_nodes
git clone https://github.com/Pizzawookiee/ComfyUI-FlashVSR-Stock.git
cd ComfyUI-FlashVSR-Stock
python -m pip install -r requirements.txt

Then restart, and download the weights into ComfyUI/models/flashvsr/ from pizzawookiee/FlashVSR-1.1 on Hugging Face.

Where people actually get burned: OOM - fix it with streaming or streaming_faithful_lowvram, new_latent_frames=2, and a shorter clip; the streaming modes bound the model's temporal working set, but the prepared input and decoded output still grow with duration, so a long clip can exhaust system RAM even when attention is bounded. Attention backend rejects the mask - streaming needs a backend that accepts an arbitrary per-head mask; switch ModelAttentionBackend to a compatible mode or install the optional Sparge patch. First run is slow - CUDA/Triton kernels compile on first call; judge speed only after one successful run.

CategoryFlashVSR/sampling

Inputs (10)

Name	Type	Default	Description
runtime	FLASHVSR_RUNTIME		—
sampling_mode	COMBO	full_video_dense	full_video_dense processes the complete clip in one dense-attention model call: useful as a reference but VRAM grows sharply with resolution and duration; the LCSA controls below are ignored. streaming processes bounded overlapping segments and applies FlashVSR LCSA without a DiT KV cache. streaming_faithful_full uses the paper layout: six-frame prefill, two new frames per continuation, and a six-frame sliding KV cache in every Wan block. Cache precision and CPU/GPU residency are configured independently below. streaming_faithful_lowvram uses the same temporal layout but retains only the nearest two historical frames in every Wan block. This avoids the boundary blur caused by giving early blocks no temporal history while using roughly one third of the full cache. Streaming modes use the model's selected mask-capable attention backend. The optional FlashVSR Sparge Attention additionally skips rejected key blocks with SpargeAttn instead of applying the sparse topology through a dense masked kernel.
sparse_ratio	FLOAT	2.01–4	Raw FlashVSR v1.1 LCSA sparse ratio. Before routing it is normalized like the official pipeline: effective_ratio = sparse_ratio * 768 * 1280 / (prepared_width * prepared_height). Higher values retain more attention connections and usually improve motion/detail stability; lower values are more aggressive and may look sharper but can flicker or lose structure. 2.0 is the stable released default at the 768x1280 reference size. With the current dense mask backend this is mainly a quality control, not a major speed or VRAM control.
local_range	INT	113–15	Streaming-only spatial search neighborhood measured in 8x8 Wan-token windows (about 128 output pixels per window). Larger values better accommodate fast or large motion; smaller values keep attention more local and may look sharper but can destabilize moving objects. 11 is the stable default.
query_block_chunk	INT	10–32	Number of 128-query LCSA windows sent to the selected backend at once. 0 selects a conservative value from currently free VRAM; 1 minimizes mask VRAM; larger manual values are faster but use more VRAM. This control is ignored by FlashVSR Sparge Attention, which processes the complete compact block mask in one sparse call.
new_latent_framesopt	INT	22–4	New latent frames appended per continuation. 2 matches the FlashVSR paper and is mandatory in both faithful cache modes. Legacy streaming may use 4 to reduce model calls, but this is less faithful to the trained temporal layout.
profile_cuda_eventsopt	BOOLEAN	false	Print synchronized CUDA-event timings after sampling for LQ transfers, pixel unshuffle, Conv3d, norm/SiLU, cache updates and linear projection; asynchronous cache write enqueue/D2H/waits; shared ConvRot quantization, Q/K/V GEMMs, Q/K norm/RoPE; complete Wan calls; compact-cache transfer, K-summary build/transfer, direct HND dequantization, current HND layout, and native Sparge block-INT8 K/transposed-FP8 V preparation; LCSA routing; Sparge input cast, K smoothing, Q/K quantization, LUT creation, V transpose/FP8 quantization, CUDA attention, and restore; and result assembly. It also prints LQ weight residency and verifies BasicGuider/CFG=1 pass count. Off adds no CUDA events; on is intended for benchmarking.
qkv_projectionopt	COMBO	stock	stock uses ComfyUI's proven Wan Q/K/V Linear calls and still uses an INT8 ConvRot checkpoint normally. shared_int8_experimental reuses one ConvRot activation quantization across Q/K/V; it is capability-guarded but remains experimental. It does not control cache size.
cache_formatopt	COMBO	int8	Faithful modes only. int8 stores post-RoPE K and V as independent per-token/per-head INT8 carriers (smallest). With FlashVSR Sparge Attention, v0.33 routes from cached K summaries and expands carriers directly into final HND layout, avoiding full FP16 staging tensors. hybrid keeps K in model precision and stores V as INT8 to protect attention scores. float keeps both in model precision (largest). This is independent of QKV projection and checkpoint dtype.
cache_residency_backendopt	COMBO	cpu	Faithful modes only. cpu always stages the authoritative cache from system RAM and is the reliable fallback. aimdo_experimental keeps the same authoritative CPU cache while exposing a dedicated low-priority AIMDO VBAR as an evictable GPU mirror. Resident pages avoid CPU transfers; evicted, stale, or unavailable pages are repopulated from CPU per access. Requires ComfyUI AIMDO.

Outputs (2)

Name	Type	Description
SAMPLER	SAMPLER	—
SIGMAS	SIGMAS	—