ComfyUI-Lightx2vWrapper

ComfyUI custom nodes for LightX2V. The wrapper exposes LightX2V's modular configuration and runner APIs, together with ComfyUI-friendly file inputs and output previews.

中文文档

Supported workflows

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

The examples are versioned with the wrapper and are the best reference for current node names and connections.

Installation

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.txt

For an existing checkout, update the submodule with:

git submodule update --init --recursive

Download the model files from LightX2V on Hugging Face and place them under ComfyUI/models/lightx2v/.

Node groups

• Configuration: LightX2VInferenceConfig, LightX2VTeaCache, LightX2VQuantization, and LightX2VMemoryOptimization.
• Composition: LightX2VConfigCombinerV2 and LightX2VConfigCombinerV3.
• Inference: LightX2VModularInferenceV2.
• Talk inputs: single-object, file-list, JSON, and multi-object talk combiners.
• Video inputs and restoration: LightX2VInputVideoPath, SeedVR2 and SwiftVR loaders/samplers, plus LightX2VOutputVideoPreview.
• 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 and SeedVR2/SwiftVR 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.

Model files

Place each model in its own directory under ComfyUI/models/lightx2v/. 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.

Development

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-files

See CONTRIBUTING.md for pull request and workflow validation guidelines.