ComfyUI custom nodes for LightX2V. The wrapper exposes LightX2V's modular configuration and runner APIs, together with ComfyUI-friendly file inputs and output previews.
The repository includes runnable workflow examples under
example_workflows/:
- Wan 2.2 text/image-to-video
- SekoTalk and static SekoTalk
- Multi-person SekoTalk
- SeedVR2 video restoration
- SwiftVR image and SwiftVR video restoration
- DA3 MONO image and DA3 MONO video relative depth
The examples are versioned with the wrapper and are the best reference for current node names and connections.
Clone the repository with its LightX2V submodule into ComfyUI's
custom_nodes directory:
cd ComfyUI/custom_nodes
git clone --recursive https://github.com/ModelTC/ComfyUI-Lightx2vWrapper.git
cd ComfyUI-Lightx2vWrapper
python -m pip install -r lightx2v/requirements.txt
python -m pip install -r requirements.txtFor an existing checkout, update the submodule with:
git submodule update --init --recursiveDownload the model files from LightX2V on Hugging Face
and place them under ComfyUI/models/lightx2v/.
- Configuration:
LightX2VInferenceConfig,LightX2VTeaCache,LightX2VQuantization, andLightX2VMemoryOptimization. - Composition:
LightX2VConfigCombinerV2andLightX2VConfigCombinerV3. - Inference:
LightX2VModularInferenceV2. - Talk inputs: single-object, file-list, JSON, and multi-object talk combiners.
- Video inputs and restoration:
LightX2VInputVideoPath, SeedVR2 and SwiftVR loaders/samplers, plusLightX2VOutputVideoPreview. - Depth Anything 3 MONO:
LightX2VDA3MonoLoader, image sampler returning a depthIMAGEand skyMASK, and streaming video sampler returning an MP4 path forLightX2VOutputVideoPreview. - LoRA:
LightX2VLoRALoader.
The inference node currently accepts the model classes exposed by
model_utils.support_model_cls_list: Wan 2.1/2.2 variants, SekoTalk,
Qwen Image, and SeedVR2. The retired *_distill values remain selectable as
compatibility aliases for saved ComfyUI workflows and are normalized before
LightX2V's runner is built.
The wrapper keeps one LightX2V GPU runner resident across these node groups. Switching between Wan/SekoTalk, SeedVR2/SwiftVR, and DA3 MONO releases the previous runner before loading the next one. Cached restoration loader outputs remain usable; their runner is rebuilt when selected again.
When LightX2V loads a runner, it asks ComfyUI to unload its resident models
first. When ComfyUI next frees GPU memory for one of its own models, the wrapper
evicts the resident LightX2V runner. This also applies to cached restoration
loader outputs; they rebuild their runner on the next sampler call. An active
LightX2V request is protected from eviction until it finishes. Switching
models can therefore incur a reload, but resident model allocations do not
accumulate across the two model managers. This hook uses ComfyUI's
model_management.free_memory entry point; changes to that internal API
require revalidation.
Place each model in its own directory under ComfyUI/models/lightx2v/. DA3 MONO
uses ComfyUI/models/geometry_estimation/depth_anything_3_mono_large.safetensors;
the official checkpoint is also accepted as
ComfyUI/models/geometry_estimation/DA3MONO-LARGE/model.safetensors. The DA3
loader exposes internal resolution, longest/shortest-side resize or crop,
attention backend, backbone dtype, norm backend, and CUDA Graph controls. The
image sampler returns a preview at the input resolution; the video sampler
streams frames to MP4 and preserves source audio. Numeric NPY/NPZ output is
optional and disabled by default. LoRA
files can be placed in either ComfyUI/models/lightx2v/loras/ or
ComfyUI/models/loras/.
ComfyUI/models/lightx2v/
├── Wan2.2-I2V-A14B-distill-fp8/
├── seedvr2_ema_3b_fp8/
└── loras/
The exact directory names depend on the downloaded checkpoint. The model picker only lists directories that exist on the local ComfyUI installation.
Install the development hook and run the same checks used by CI:
python -m pip install pre-commit
pre-commit install
pre-commit run --all-filesSee CONTRIBUTING.md for pull request and workflow
validation guidelines.