ComfyUI custom nodes that prevent video VAEs from dropping the final frames. The input is padded to a valid temporal length, processed by the workflow, and cropped after VAE Decode to restore the exact source frame count.

207 frames → pad to 209 → model / VAE → crop to 207 frames

207 is only an example. The actual length is read from images.shape[0], so any non-empty IMAGE batch is supported.

Why frames disappear

Many causal video VAEs accept only lengths matching factor × n + offset. Frame Keeper calculates the nearest valid length upward:

valid = ceil((frames - offset) / factor) × factor + offset

Model family	temporal_factor	alignment_offset	Valid lengths
LTX-Video, LTX-2.x / 2.3	8	1	1, 9, 17, …
Wan 2.1 / 2.2	4	1	1, 5, 9, …
HunyuanVideo	4	1	1, 5, 9, …
Mochi	6	1	1, 7, 13, …
CogVideoX / CogVideoX-1.5	8 / 16	1	checkpoint-dependent

The package and example workflow are tested with LTX / IC-LoRA. The alignment math is configurable for other model families, but their padded batch and valid_frame_count must be connected to the corresponding model and latent nodes. Always follow the stricter rule of the selected checkpoint.

Installation

Clone the repository into ComfyUI/custom_nodes, then restart ComfyUI:

cd ComfyUI/custom_nodes
git clone https://github.com/ScryptHunter/ComfyUI-Video-FrameKeeper.git

No extra dependencies are required; the nodes use the PyTorch installation provided by ComfyUI. The code contains no platform-specific paths and supports Windows and Linux.

Workflow

Load Video
    │
    ▼
Video Pad Image Batch To Valid Length ── valid_frame_count ──► latent length
    │ padded_images
    ▼
preprocess → IC-LoRA / model → sampler → VAE Decode
                                            │
                                            ▼
                    Video Crop Image Batch To Original Length
                                            │
                                            ▼
                                      Video Combine

Important:

1. Send padded_images to every video-conditioning branch.
2. Connect valid_frame_count to the video latent and audio latent lengths.
3. Place the crop node after VAE Decode and before Video Combine.

Example: examples/ltx_ic_lora_keep_original_length.json.

Nodes and parameters

Node	Purpose
Calculate Valid Frame Count	Calculates valid_frame_count and the required padding.
Pad Image Batch To Valid Length	Pads the input IMAGE batch.
Crop Image Batch To Original Length	Removes temporary frames after decoding.
Frame Count Inspector	Reports the rule, current length, and required padding.
Validate Frame Keeper Pipeline	Checks source, latent, and decoded lengths for mismatches.

Parameter	Description
temporal_factor	Temporal VAE factor, such as 8 for LTX or 4 for Wan.
alignment_offset	Alignment-rule offset; use 1 for the listed models.
padding_mode	Strategy used to create temporary frames.
preserve_dtype	Preserves the input tensor dtype; true is recommended.
crop_from	Removes frames from end or start; normally end.

Padding modes

Mode	Added frames
repeat_last	Repeats the final frame; recommended for IC-LoRA.
reflect	Uses preceding frames in reverse order.
interpolate_last	Blends the final two frames.
repeat_sequence	Repeats the source sequence from the beginning.
first_frame	Repeats the first frame.
black	Creates black frames with the same size, dtype, and device.

The nodes do not modify FPS or audio. After cropping, video duration is original_frame_count / fps. In Video Combine, disable trim_to_audio when shorter audio should not truncate the video.

Tests

python -m pytest

Tests cover frame math, padding, cropping, dtype/device preservation, error handling, and node registration. The CUDA test is skipped when no GPU is available.

References

Temporal-alignment references: LTX-2 Core, Wan2.1, Wan2.2, HunyuanVideo-1.5, Mochi, and CogVideo.

License

MIT