(deforum) Load Video

Every vid2vid Deforum workflow starts here. This node pulls frames out of a video file and hands them to the animation loop - as init images for hybrid mode, as reference frames for Hybrid Motion, or as the input to your own img2img chain. It's the "input" half of the pack's video story, and it's the node you reach for the moment you want an animation that follows something real instead of inventing its own camera.

It reads video files straight from ComfyUI's input directory - no extra upload step, no path typing. Drop an mp4, webm, mkv, or gif into ComfyUI/input and it shows up in the dropdown.

Inputs

• video - dropdown of video files found in your input folder. This is the one you'll actually touch.
• reset - force the node to reopen the file from the start on the next call. Handy when you swap files mid-session and the node is holding a stale handle.
• iterative - on by default. In iterative mode the node walks forward through the video frame by frame, which is what you want for animation (the loop reads "the next frame, please"). Turn it off and it will jump straight to start_frame instead.
• start_frame - where to begin (ignored in iterative mode, used when iterative is off).
• return_frames - how many frames to read per call (default 1). Bump it if your graph processes a batch at a time.

Outputs

• IMAGE - the frame(s) read from the video, converted to a ComfyUI image tensor.
• FRAME_IDX - which frame you're on, so your graph can keep count.
• MAX_FRAMES - the total frame count of the video, so schedules that use max_f resolve correctly against a real clip.

Watch the ordering: with return_frames > 1 and iterative mode, it reads forward that many frames per call, wrapping to the start of the file when it runs out.

How it works

Under the hood it's cv2.VideoCapture, which is why the README's backend install pulls in opencv-contrib. The node keeps a persistent capture handle and only reopens the file when the path changes, the capture runs past the end, or you flip reset. That persistence is the gotcha: after you replace a video file, the dropdown changes but the open handle can linger - flip reset once and it will reopen cleanly.

Installation

Part of Deforum Nodes:

cd ComfyUI/custom_nodes
git clone https://github.com/XmYx/deforum-comfy-nodes.git

Restart, or install "Deforum Nodes" by XmYx via ComfyUI Manager. It needs the full backend (opencv-contrib, deforum[comfy], Python 3.10 per the README) to actually decode video.

Common issues

• File doesn't appear in the dropdown - it must be in ComfyUI/input and use a supported extension. Check the folder, then restart; the file list is built at node creation.
• Video decodes weirdly after swapping files - stale capture handle. Toggle reset.
• Frame index feels off - if you're not in iterative mode, start_frame controls the jump and FRAME_IDX counts from there. Keep iterative on unless you specifically need random access.