UniVidX • Sample

---

This is the node that actually does the work. UniVidXSampler takes the loaded model, the task mode, your prompt, and up to seven optional IMAGE conditions, runs UniVidX's full diffusion pipeline, and hands the result to a decoder over a pink UNIVIDX_RESULT socket. It's the middle of the five-node graph, and it's where your wall-clock time disappears: a single 21-frame clip at 480×640 takes roughly nine minutes on an RTX 5090. This is not real-time, and nothing about the node is hiding that fact from you.

How it works

Under the hood it runs UniVidX's own pipe() inside a chdir() into the vendored repo - the pack deliberately keeps UniVidX an opaque black box rather than reimplementing its sampler. Before sampling it does two validation passes: the task mode's family must match the loaded model variant (intrinsic vs alpha), and every modality the mode requires as a condition must actually be wired in. Get either wrong and it raises before wasting your GPU minutes. It converts your IMAGE batches to BF16 video tensors (conditioning is always BF16, even when the DiT is FP8-quantized), tiles the VAE work at tile_size [30, 52] with tile_stride [15, 26] from the upstream scripts, and passes the whole batch to pipe() under torch.no_grad(). Any optional input the active mode doesn't need is silently ignored - wire everything, it'll use what it uses.

The inputs that matter

• prompt / negative_prompt - the negative defaults to the Chinese prompt from UniVidX's own inference scripts, not a mistake in your install. Leave it alone until you have a reason to touch it.
• num_inference_steps - 20 is what UniVidX was trained at and the production default. 50+ rarely helps and usually hurts here. With the step-distill LoRA on the loader, drop to 4.
• cfg_scale - 5.0 production; 1.0 alongside step-distill. Distilled models have guidance baked in, so stacking CFG on top double-corrects and oversaturates - that's the standard distillation rule of thumb, and it applies here.
• num_frames - 21 is the training sweet spot (21 contiguous frames ≈ 0.87 s at 24 fps). The widget allows up to 81, but longer clips should be run through the pack's chunked sampler script instead.
• height / width - 480×640 default; production resolutions live in the 256–1024 / 256–1280 range.
• seed - anything; it's passed straight to the pipeline.
• The seven optional IMAGE sockets - rgb, albedo, irradiance, normal, pha, fgr, bgr. Only the ones your task mode names as conditions do anything.

The single output is result, an opaque UNIVIDX_RESULT that only the two decoder nodes know how to unpack.

Two ways to run it

The pack's own recommendations, straight from the README:

Production finals - loader default, 20 steps, cfg 5.0. ~9.4 min per 21-frame chunk on a 5090, PSNR ≥ 30 dB per modality. Ship these.

Fast iteration - dit_weight_mode=fp8_prequantized + step_distill_lora=lightx2v + 4 steps + cfg 1.0. ~4.6 min per chunk, roughly 3× faster, visibly rougher output. Fine for previews and long-clip processing; the README is explicit that Normal and Alpha outputs are the highest-risk modalities under distillation because LightX2V was trained on natural images, not decomposition targets. Don't ship distilled normals or mattes without eyeballing them.

Install

cd ComfyUI/custom_nodes
git clone --recurse-submodules https://github.com/dreamrec/UniVidX_ComfyUI.git
cd UniVidX_ComfyUI
python -m pip install -r requirements.txt
python install.py

To condition on your own MP4s, the example workflows load frames via VHS_LoadVideoPath, so you'll also want ComfyUI-VideoHelperSuite installed. And if you want the fast preview preset, grab the LightX2V LoRA:

hf download lightx2v/Wan2.1-T2V-14B-StepDistill-CfgDistill-Lightx2v \
    loras/Wan21_T2V_14B_lightx2v_cfg_step_distill_lora_rank64.safetensors \
    --local-dir ComfyUI/models/loras/lightx2v

Common issues

• Family-mismatch ValueError - your task mode is intrinsic but the loader loaded alpha (or vice versa). Fix the loader's variant.
• Missing required input - the sampler tells you exactly which modality the mode needs that you didn't wire. Wire it.
• Per-step time over a minute on a 32 GB+ card - VRAM management didn't activate. The pack's check: GPU temp under 60°C with 99% util means you're memory-bound, and vram_buffer_gb on the loader is the lever.
• Stalled or absurdly slow cold-load - you're on a legacy FP8 runtime-quantize path. Use dit_weight_mode=fp8_prequantized.

One more expectation-setting note: this is a small pack with zero community verification behind its benchmarks, so treat the advertised times as optimistic. On an RTX 4090 expect roughly 10–15% slower; on anything under 24 GB, don't install at all.