🎬 Video Frame Loader

Every eye-tracking video workflow needs frames before it can track anything, and that's this node's whole job. It's the least glamorous node in the kanibus/kanibus pack and also one of the most reliable - unlike several of its siblings, VideoFrameLoader genuinely does what it says. It's a solid OpenCV-backed video loader with real caching, and it's the front door for the pack's KanibusMaster and per-node tracking pipeline.

The pack is a mixed bag (some nodes are real, some are placeholder stubs), but this one is the boring, useful kind. If you're trying to run the pack's example workflows, this is where they start: point it at a file, get frames out.

How it works

It opens the file with cv2.VideoCapture and extracts real metadata - resolution, FPS, frame count, duration, fourcc codec, file size - then reads frames in the range you ask for. The clever bits:

• Caching is real. It hashes the file path + size + mtime and keeps a memory/disk cache (cache/video_frames under the repo), so re-running the same workflow on the same video doesn't re-decode. Cache hits are what make iterative eye-tracking work tolerable.
• Frame stepping and trimming. start_frame, frame_count (-1 = all frames), and step let you sample every Nth frame - the classic way to keep long videos manageable for tracking.
• FPS and resize control. target_fps (-1 = original) re-times the output; resize_width/resize_height (-1 = keep) scale frames with interpolation quality tied to the quality setting.
• Color space conversion. color_space (RGB, BGR, GRAY, HSV, LAB) does the conversion for you - useful because MediaPipe-based tracking in this pack assumes BGR under the hood.

One thing to note: the frames output is a list of IMAGE tensors (OUTPUT_IS_LIST is set for it), while metadata, total_frames and actual_fps come out alongside. That list output is what KanibusMaster's video_frames input expects.

Inputs you'll actually touch

• video_path - the path to your file. The only input that must be right.
• frame_count - the "why is it taking forever" control. Set it to a real number unless you genuinely want every frame of a long clip.
• step - the other "make it fast" control. Step 2 halves the work.
• quality - original/high/medium/low; affects decode interpolation and cache compression. high is a good default.
• batch_size / preload_frames - prefetch tuning; defaults of 8/32 are fine.

Installing

cd ComfyUI/custom_nodes
git clone https://github.com/kanibus/kanibus
cd kanibus    # lowercase - README's "cd Kanibus" fails on Linux/Mac
pip install -r requirements.txt   # requirements_minimal.txt if the full set clashes
python install.py

Restart ComfyUI, look under Kanibus/Input. No model downloads needed - this node is pure OpenCV. (Ignore the README's "you MUST download 5.6GB of ControlNet models" - no node in the pack actually loads those.)

Gotchas

• Path errors. A wrong video_path raises a FileNotFoundError / "Could not open video file" - check your path, and note it's a filesystem path, not a ComfyUI input-relative path.
• Absolute paths only, effectively. There's no browse button here, which is a real usability gap compared to other video loaders.
• Stateful capture pool. It keeps VideoCapture objects cached per filepath; changing files can leave stale handles until restart. Restarting ComfyUI is the reliable reset.
• frame_count = -1 means everything. If you pass a 10-minute 4K file with no limit, you asked for that decode time. Use start_frame/frame_count/step deliberately.

If you just want frames out of a video to feed the pack's real tracking nodes, this is the node to reach for. If you'd rather not install a pack that's half placeholders, any solid video-frame loader (there are several standalone ones) does the same job - but this one works, caches well, and plugs straight into the pack's VIDEO_METADATA plumbing.