AetherScale • Video Loader

Loading a video into ComfyUI normally means one thing: decode the whole file, convert every frame to float32, hold the lot in RAM as a single batch. For a 5-second clip at 512px that's fine. For the 15-second 2464×512@24 source in the pack's own worked example it's about 5 GiB - before upscaling, before frame interpolation, before you've loaded a model.

AetherScale • Video Loader gets in front of that. It decodes with FFmpeg in small chunks and writes each chunk straight into a file-backed tensor, so what's resident in RAM is a decode chunk, not a sequence. That same example lands at 2.54 GiB of backing storage in FP16 instead of 5.08 GiB of float32.

The author's framing is why it exists: nothing downstream can repair an upstream loader that already materialised the whole video. If RAM is your wall, this is the node you fix, not the ones after it.

How it works

FFprobe reads the metadata first (dimensions, frame rate, frame count, whether there's an audio stream), then the node runs a disk-space preflight against the AetherScale cache directory before touching anything - the expected error message tells you the size and points at AETHERSCALE_CACHE_DIR. Then FFmpeg decodes rgb24 raw frames into a pipe, decode_chunk_frames at a time, and each chunk is scaled to 0–1 and written sequentially into the backing file. No writable mmap during decode, which is deliberate: it's what stops Windows from accumulating tens of GiB of dirty mapped pages while frames are still arriving. Writes are flushed in bounded windows (128 MiB by default). Only after decoding finishes is the file mapped and handed to you as an IMAGE tensor.

precision = auto picks FP16 once the float32 estimate passes 768 MiB and float32 below that - small clips stay lossless-ish and simple, big ones get the savings without you thinking about it. The stream is video-only; audio is decoded separately, so your AUDIO output stays real audio rather than a re-encode of the picture pipeline.

Inputs that matter

video is a dropdown of files found under ComfyUI/input - it scans recursively for .mp4, .mov, .mkv, .webm, .avi, .m4v and even .gif. If your source lives anywhere else, or you'd rather not copy a 20 GB file into the input folder, use the optional path_override string with an absolute path.

force_rate - 0 keeps the source frame rate. Set it and FFmpeg resamples with the fps filter, which is how you get a 60 fps source down to 16 fps cheaply. frame_load_cap - 0 loads everything; set a number to load only the head of a long clip while you iterate. start_time skips in.

decode_chunk_frames (default 4) is the RAM/throughput dial: bigger chunks decode a bit faster, smaller ones keep the working set tighter. load_audio and clean_cache are on by default. clean_cache = true means the backing file is deleted once ComfyUI releases the tensor; false keeps a persistent .mmap in the pack's cache directory for debugging.

Outputs, and the VHS-shaped bit

Six outputs: images, frame_count, audio, video_info, frame_rate, and stats. The first four deliberately mirror the shape of the common VHS loader - video_info is a VHS_VIDEOINFO-compatible dictionary - so a workflow built around a VHS loader usually rewires with a couple of drags. frame_rate comes out as its own FLOAT, which is exactly what AetherScale • Video Combine's frame_rate input wants, so the pair wires up without you typing the number twice. stats is a JSON string with the storage dtype, chunking, count and timing.

Install

cd ComfyUI/custom_nodes
git clone https://github.com/vizart-vj/ComfyUI-AetherScale.git

or install from Manager by searching AetherScale, then restart. No pip dependencies.

Where people get burned

It needs ffprobe, not just ffmpeg. AetherScale finds FFmpeg via PATH or the VideoHelperSuite bundle, then looks for ffprobe beside it or in PATH. Missing ffprobe is a hard failure with a message telling you to enable VideoHelperSuite - if VHS is installed you already have both binaries and never see this.

Put the cache on an SSD with space, and set it before launching ComfyUI. The backing tensor lands in the AetherScale cache dir, which is what the preflight checks:

set AETHERSCALE_CACHE_DIR=D:\aetherscale_cache

The dropdown won't show files outside ComfyUI/input - that's the standard ComfyUI loader contract, and path_override is the escape hatch, so you can point at an absolute path on another drive without copying anything.

One behaviour worth understanding rather than fighting: IS_CHANGED keys on the file's path, size and mtime, so regenerating the source video reloads it and re-running with an unchanged file happily reuses the cached tensor. If you changed something outside ComfyUI and nothing seems to happen, that's why.