Keyframe Video:
Keyframe Video builds a control sequence for an IC-LoRA that interprets painted keyframes, such as AInVFX’s ainvfx-fluid. It places your painted reference images at selected moments in an otherwise black sequence, giving a compatible model visual guidance at those moments. This is useful when you want to establish the appearance or arrangement of a fluid shot using flat-colour paintings rather than a fully animated reference. The node prepares this guidance; it does not generate motion, blend between paintings, or fill the gaps with interpolated images. Reference images are converted to RGB and, when necessary, resized using nearest-neighbour sampling, which avoids introducing blended colours along the boundaries of your painted regions.
Keyframe Video Input Parameters:
width
An INT that sets the width of every frame in pixels. The default is 960, the minimum is 64, and the maximum is 8192. Each keyframe image is resized to this width and the specified height if its original dimensions differ from the requested dimensions. Resizing uses nearest-neighbour sampling to preserve discrete painted colours rather than creating smooth colour transitions. The image is stretched to fit the requested dimensions, not cropped or padded to preserve its original proportions, so matching the aspect ratio of your paintings to the intended sequence helps prevent distortion. Increasing the width increases memory use across the entire sequence, including its black frames.
height
An INT that sets the height of every frame in pixels. The default is 512, the minimum is 64, and the maximum is 8192. Together with width, it determines the frame dimensions of the control sequence and the dimensions to which keyframe images are resized. Choose dimensions appropriate for the downstream workflow and, where possible, prepare your paintings at those dimensions to avoid changes to their shapes during resizing. Larger heights increase memory use and the amount of image data that must be prepared.
frames
An INT that determines the total number of frames in the sequence. The default is 121, the minimum is 1, and the maximum is 4096. Frame numbering starts at 0, so a sequence of 121 frames runs from frame 0 through frame 120. The node initially makes every frame black, then replaces the selected frames with your paintings. Frame positions below 0 are moved to frame 0, and positions beyond the sequence are moved to its last frame. This parameter sets the sequence length, not its playback rate; the node does not assign an FPS value. Memory use increases directly with the number of frames, even if you supply only a few paintings.
keys
A required multiline STRING containing a JSON list that describes which image belongs at each keyframe position. The default is [], meaning no keyframes and therefore an entirely black sequence; no numerical minimum, maximum, or predefined options apply. Each entry must contain a frame value and an image path, for example [`{"frame": 0, "image": "fluid/start.png"}`, `{"frame": 120, "image": "fluid/end.png"}`]. Image paths refer to files in ComfyUI’s input folder, including its subfolders. Frame values are converted to integers and clamped to the available frame range. Entries are processed in list order, so if several entries resolve to the same frame, the last one replaces the earlier ones. Images are opened as RGB, so transparency is not retained as a separate channel. Use valid JSON with double-quoted property names and image paths; the node does not provide its own recovery for malformed JSON, missing fields, or unreadable images.
Keyframe Video Output Parameters:
images
An IMAGE containing the complete control sequence as a batch of RGB frames in chronological order. Its dimensions are frames × height × width × 3, with the final dimension representing red, green, and blue. Unassigned frames contain black values of 0, while assigned frames contain the corresponding resized paintings, converted from RGB pixel values to floating-point values on a 0–1 scale. The batch is transferred to ComfyUI’s intermediate device and data type before being returned. This output is intended for a compatible control-video workflow; it is not a saved video file and does not include audio, playback-rate metadata, or motion generated between the paintings. A mostly black preview is therefore expected when only a few keyframes are defined.
Keyframe Video Usage Tips:
- Match width, height, and frames to the sequence expected by your downstream control workflow. For a 121-frame sequence, use positions 0 through 120 when placing your paintings.
- For ainvfx-fluid, the supplied implementation notes identify the first frame, the last frame, and intermediate positions following the pattern 8k + 1 as the painted-keyframe locations it reads. Intermediate positions therefore include 1, 9, 17, and 25; keep them within the sequence and follow the requirements of the particular model workflow you are using.
- Prepare paintings at the intended frame dimensions when possible. Nearest-neighbour resizing keeps colour regions discrete, but resizing to a different aspect ratio still stretches their shapes.
- Place images in a clear subfolder inside ComfyUI’s input folder and use paths such as
fluid/start.png. Forward slashes also avoid the need to escape Windows-style backslashes inside JSON strings. - Start with a small test containing a beginning and ending painting, such as
[`{"frame": 0, "image": "fluid/start.png"}`, `{"frame": 120, "image": "fluid/end.png"}`]for 121 frames. Inspect the assigned frames before connecting the sequence to a longer generation workflow. - Keep frame positions unique unless you intentionally want a later entry to replace an earlier one. Remember that out-of-range positions can also collide after being moved to the first or last frame.
- Use moderate dimensions and sequence lengths while testing. At the default 960 × 512 × 121 settings, the initial float32 sequence alone occupies approximately 681 MiB, before accounting for image loading, conversion, or other workflow data.
- If you replace a painting without changing its filename, the node includes that file’s modification time in its cache fingerprint so the changed file can trigger execution again.
Keyframe Video Common Errors and Solutions:
JSONDecodeError: Expecting property name enclosed in double quotes
- Explanation: The keys text is not valid JSON. Common causes include single quotes, missing quotation marks, or a trailing comma. JSON parsing can fail during cache checking as well as execution.
- Solution: Use double quotes and remove trailing commas. A valid example is
[`{"frame": 0, "image": "fluid/start.png"}`].
JSONDecodeError: Expecting value
- Explanation: The keys text contains something that cannot be read as a JSON value, such as an incomplete entry or whitespace without an actual list. The exact error location depends on the text.
- Solution: Enter a complete JSON list. Use
[]when you want no keyframes, or supply properly formed entries with bothframeandimage.
KeyError: 'frame' or KeyError: 'image'
- Explanation: At least one keyframe entry is missing a required field, or its name is spelled differently. Field names are case-sensitive.
- Solution: Make sure every entry contains exactly the required field names
frameandimage, for example{"frame": 9, "image": "fluid/middle.png"}.
TypeError: string indices must be integers, not 'str'
- Explanation: The parsed JSON has the wrong structure. For example, a single object instead of a list, or a list of plain strings instead of keyframe objects, can produce this error; wording can vary with the Python version.
- Solution: Put each keyframe object inside a surrounding list, such as
[`{"frame": 0, "image": "fluid/start.png"}`].
ValueError: invalid literal for int() with base 10
- Explanation: A frame value cannot be converted to an integer, for example because it contains text such as
"start"or a decimal string such as"9.5". - Solution: Use whole-number JSON values such as
0,9, or120. Avoid text labels and decimal strings for frame positions.
FileNotFoundError: [Errno 2] No such file or directory
- Explanation: An image path does not resolve to an existing file. A misspelled filename, incorrect subfolder, or image saved outside the expected input location can cause this.
- Solution: Put the image inside ComfyUI’s input folder and check its relative path, extension, and capitalization. For example,
fluid/start.pngshould identify that file inside the input folder’sfluidsubfolder.
PIL.UnidentifiedImageError: cannot identify image file
- Explanation: The image reader cannot recognize a referenced file as a supported image. The file may be damaged, incomplete, or a different kind of file with an image extension.
- Solution: Open the file in an image editor and export a fresh RGB PNG, then update the image path if necessary. Changing an extension alone does not convert the file.
PermissionError: [Errno 13] Permission denied
- Explanation: The process running ComfyUI cannot read the referenced image, or the path points to a location it cannot access.
- Solution: Confirm that the path points to an image file and that ComfyUI has read access. Copying the image into an accessible subfolder of ComfyUI’s input folder can help resolve location-related access problems.
MemoryError, numpy allocation error, or device out-of-memory error
- Explanation: The requested sequence is too large for available memory. The node allocates all frames as a float32 array, including black frames, and then converts that array for ComfyUI; the precise error depends on where allocation fails.
- Solution: Reduce width, height, or frames and test again. Free memory used by other workflows, and avoid treating the maximum allowed dimensions and frame count as a practical combination for your hardware.
No exception, but the sequence is black or a painting is missing
- Explanation: Black frames are intentional wherever no keyframe is assigned. An empty list produces only black frames, an out-of-range position is moved to an endpoint, and a later entry can overwrite an earlier painting on the same frame.
- Solution: Inspect the specific assigned frames rather than expecting a continuously painted sequence. Check that keys is not
[], verify zero-based frame positions, and remove unintended duplicate or clamped positions.
