TS Video Loader:
TS_VideoLoader brings a video file into a ComfyUI workflow so you can work with its visual frames and accompanying sound. It lets you select a portion of a clip on the node’s timeline, change the pace at which frames are sampled, and resize frames as they are decoded. This helps you prepare footage for image or video workflows without first making a separate edited copy. The node also keeps information about the original file and the loaded clip, making it easier to check what your workflow received.
TS Video Loader Input Parameters:
source_path
The video file to load. You can pick or drop a file in the node’s interface, or provide a path to a file on the machine running ComfyUI. The default is an empty string, so you must select a file unless you supply the optional path input. The file must exist, but the node does not reject it based solely on its filename extension; the decoder determines whether it can read the file. A connected, nonempty path takes precedence over source_path.
start_seconds
The beginning of the selected clip, measured in seconds from the start of the video. Its default is 0.0, its minimum is 0.0, and its maximum is 1,000,000.0; the control moves in 0.001-second steps. You can set it with the left timeline handle. Increasing it skips the beginning of the file. When a nonempty path is connected, this timeline setting is ignored and the file loads from its beginning.
end_seconds
The end of the selected clip, measured in seconds from the start of the video. Its default is -1.0, meaning continue to the end of the file; otherwise, it must be greater than start_seconds. The control’s minimum is -1.0, maximum is 1,000,000.0, and step is 0.001 seconds. You can set it with the right timeline handle. When a nonempty path is connected, this timeline setting is ignored and the whole file is selected.
frame_rate
The requested frame rate for the loaded frames. The default and minimum are 0.0, which keeps the source rate; the maximum is 240.0, with 0.001-frame-per-second steps. Fractional values such as 23.976 are allowed. Changing this setting affects the frames produced by the node and is applied before frame_step and max_frames. It does not change the source-file reference provided by the video output.
max_frames
A hard limit on how many frames the node loads. The default and minimum are 0, meaning no cap; the maximum is 1,000,000. The cap applies after the timeline selection, frame-rate stage, and frame_step, removing frames from the end of that resulting sequence when necessary. Use it to keep a long clip from producing more frames than your workflow needs. The node’s status line shows the frame count actually produced.
longer_side
The requested length, in pixels, of the longer side of each loaded frame, regardless of whether the video is landscape or portrait. The default and minimum are 0, the maximum is 16,384, and the control moves in steps of 2. A value of 0 lets the size be derived from shorter_side while keeping the aspect ratio. Resizing takes place during decoding, so this setting affects the images output rather than rewriting the source file.
shorter_side
The requested length, in pixels, of the shorter side of each loaded frame, whether that side is the width or the height. The default and minimum are 0, the maximum is 16,384, and the control moves in steps of 2. A value of 0 lets the size be derived from longer_side. This orientation-independent sizing is useful when the same workflow must accept both portrait and landscape footage.
divisible_by
Rounds the loaded frame dimensions down to multiples of the chosen value. The default and minimum are 1, which imposes no additional multiple; the maximum is 64. This can help you prepare dimensions for video models that require multiples such as 8, 16, or 32. Because it rounds down, the final dimensions may be smaller than the side lengths you requested.
frame_step
Keeps every Nth frame after the frame-rate stage. The default and minimum are 1, which keeps every frame; the maximum is 1,000. For example, 2 keeps every second frame from the sequence produced at the selected frame_rate. Increasing it reduces the number of loaded images; max_frames is applied afterward.
resize_filter
Chooses the method used to scale loaded frames. The options are bicubic, bilinear, lanczos, area, and neighbor; the default is area. The node describes area as suitable for strong downscaling, lanczos as a choice for keeping edges sharp, and neighbor as a choice for pixel art. This setting matters when you resize footage and affects the appearance of the decoded images, not the original file.
when_too_large
Controls what happens when the decoded frames are expected to exceed the node’s memory ceiling. This optional setting offers stop and use disk; the default is stop. With stop, the node refuses the load and reports the required size. With use disk, it places frames in a memory-mapped file in the ComfyUI temporary folder while still returning an ordinary IMAGE tensor. Disk use needs enough temporary-drive space and can be slower; memory use can still rise during decoding. The stated ceiling is 60% of machine memory, with a minimum of 8 GB, unless TS_VIDEO_MAX_BYTES sets another value.
path
An optional file path supplied through a wire, typically from TS Batch Source in its “Files in folder” mode. Its default is an empty string, and the source specifies no numeric range or fixed options. A nonempty connected value replaces the file selected through source_path. Because the timeline handles may have been set for a different file, the node then loads the connected file whole: start_seconds and end_seconds do not apply, while frame_rate, max_frames, and resizing still do. This input is a connection rather than a regular on-node widget.
TS Video Loader Output Parameters:
images
The decoded video frames, ready for nodes that accept IMAGE data. The output is a batch shaped [B,H,W,C]: frames, height, width, and color channels. Its values are floating-point numbers in the 0..1 range. The timeline selection, frame-rate setting, frame step, frame cap, and resizing settings determine which frames appear and their loaded dimensions.
audio
Audio from the same selected time range as the loaded clip. This lets you pass the clip’s sound into an audio-capable part of your workflow. If the source file has no audio track, the node returns no audio rather than generating silence, so an absent track is not mistaken for sound you intended to use.
video_info
A TS_VIDEO_INFO metadata bundle describing both the source media and what the node loaded. It includes source details such as frame rate, frame count, duration, dimensions, format information, and whether audio is present, alongside loaded details such as frame rate, frame count, dimensions, selected times, and whether max_frames truncated the result. Connect it to TS Video Info when you want to read those values individually.
video
A reference to the selected portion of the source file for nodes that accept the VIDEO type. Unlike images, it does not incorporate the node’s resizing or frame-rate changes; it represents the trimmed source file. Creating this reference does not itself decode the video. If the installed ComfyUI core does not provide the video type needed for this reference, this output can be empty while the other outputs continue to work.
TS Video Loader Usage Tips:
- Pick a file in the node, then use the timeline handles to isolate the moment you need. Leave
end_secondsat-1.0when you want the clip to continue through the file’s end. - Start with
frame_rate=0.0andframe_step=1to keep the source frame rate and every frame. For a lighter sequence, adjust the frame rate or increaseframe_step, then check the node’s displayed frame count. - Set
max_frameswhen you only need the beginning of the selected sequence. Remember that the limit applies after frame-rate sampling and frame stepping, so it may cover a different amount of time when those settings change. - Size mixed portrait and landscape footage with
longer_sideandshorter_sideinstead of assuming a fixed width and height. Setdivisible_byto the multiple required by your downstream model, and check the resulting dimensions invideo_info. - Use the default
areafilter for strong downscaling. Trylanczoswhen preserving sharp edges is more important, orneighborfor pixel-art footage. - Leave
when_too_largeatstopwhen you want an oversized load to fail visibly. Chooseuse diskonly when you have sufficient space on the ComfyUI temporary drive and can allow for slower decoding. - For a wired batch of different files, connect their paths to
pathand set shared frame-rate, frame-cap, and resize settings. The timeline trim is intentionally ignored for each connected file, so use another approach if every file needs a particular cut.
TS Video Loader Common Errors and Solutions:
Pick a video file first.
- Explanation: No usable file was provided through
source_pathduring input validation. - Solution: Pick or drop a video in the node, or connect a file path to
path.
[LOG_PREFIX] No video file selected.
- Explanation: At execution time, the selected source path was empty or did not point to an existing file.
[LOG_PREFIX]represents the node’s log prefix. - Solution: Select an existing file on the machine running ComfyUI and run the workflow again. If the file was moved, select its new location.
File not found: [path]
- Explanation: A provided file path does not point to an existing file. The message can occur during validation for either a selected file or a nonempty wired
path; execution can also report it for a wired file with the node’s log prefix. - Solution: Check the path on the ComfyUI machine, not just on the computer displaying its interface. Confirm the file still exists and, for a batch, check the particular path supplied to the failing job.
start_seconds cannot be negative.
- Explanation: The clip start was set below zero.
- Solution: Set
start_secondsto0.0or a later point in the video.
end_seconds must be greater than start_seconds (or -1 for the whole file).
- Explanation: The chosen end is at or before the chosen start, and it is not the special
-1.0value. - Solution: Move the right timeline handle later than the left one, or set
end_secondsto-1.0to continue to the file’s end.
Oversized-frame refusal showing the required size
- Explanation: With
when_too_largeset tostop, the node refuses a load whose frames exceed its memory ceiling. The exact error wording comes from the decoder and is not shown in the provided node source. - Solution: Select a shorter clip, reduce the loaded dimensions, lower the number of frames with
frame_stepormax_frames, or chooseuse diskif the ComfyUI temporary drive has enough room.
File cannot be decoded
- Explanation: A file can exist but still fail when the decoder attempts to read it. The provided node source does not specify an exact error message for this case; it also does not use the filename extension alone to decide whether a file is valid video.
- Solution: Check that the file opens as a video and is not incomplete or damaged. If needed, try a working copy of the file and read the decoder’s reported error for the specific cause.
