ComfyUI Node: ComfyArt Timeline Render

ComfyArt Timeline Render:

ComfyArtTimeline, displayed as “ComfyArt Timeline Render” in the ComfyArt category, renders a timeline-based media edit into a saved video file. It is designed to help you assemble visual material into a timed sequence, combining video clips and still images with control over when each item appears and how it fits within the frame. The supplied implementation supports layered visual tracks, source offsets, playback speed adjustments, centered contain or cover fitting, circular masking, and transitions between adjoining clips. It builds each frame by placing active visual material over a black background, processing higher-numbered tracks after lower-numbered tracks so they can appear above them. This makes it useful for turning separate creative assets into a composed presentation or edited sequence without manually assembling every frame. Rendering is driven by a JSON timeline description, giving you repeatable control over the edit while saving the finished result in ComfyUI’s output directory.

ComfyArt Timeline Render Input Parameters:

timeline

A required STRING field with multiline text entry that contains the timeline description in JSON format. This description controls the edit that the renderer produces, rather than serving as a natural-language prompt. The node parses the text as JSON before beginning the render, so valid punctuation, double-quoted property names, and properly matched brackets are essential. The supplied code confirms that the top-level format setting defaults to mp4 when omitted; other format values must exist in the renderer’s encoder registry, whose complete options are not included in the supplied context. The visual clip implementation also supports settings such as start, duration, offset, speed, track, fit, transition, transform, and maskShape, although the complete top-level timeline schema is not shown. Connected video sources are made available through references such as @clip and @clip2 wherever the timeline expects a media source. No default text, minimum length, maximum length, or selectable options are declared for this input.

filename_prefix

A required STRING that determines the prefix and optional subfolder used to save the rendered video within ComfyUI’s output directory. Its default value is comfyart/edit. With that default, the node requests a save location under the comfyart subfolder and constructs a filename such as edit_00001_.mp4, with a five-digit counter supplied by ComfyUI’s save-path helper and an extension determined by the timeline format. Changing this value helps you organize different projects or versions without changing the visual composition. Supply a prefix rather than a complete filename with an extension, because the node adds the counter and extension itself. No minimum length, maximum length, or predefined options are declared.

clip

An optional VIDEO connection that makes a video from your workflow available to the timeline as @clip. The node saves the connected video to a temporary MP4 file and resolves that reference to the temporary file during rendering. Connecting it does not automatically determine its position, duration, or appearance in the edit; those decisions belong in the timeline description. This lets you incorporate a workflow-generated video without first saving it manually and entering its path. The node attempts to delete the temporary file after rendering, including when rendering fails. No default value, numeric range, or selectable options are declared.

clip2

An optional VIDEO connection that makes another video available through the timeline source reference @clip2. It follows the same temporary-MP4 process as clip, allowing you to use a second connected source in your edit. Its socket number is an identifier, not a sequencing instruction: the timeline determines whether this source appears before, after, or above other material. Every connected video is saved temporarily, even if the timeline does not reference it, so leaving unused connections disconnected avoids unnecessary preparation work. No default value, numeric range, or selectable options are declared.

clip3

An optional VIDEO connection whose timeline source reference is @clip3. Use it to provide an additional video directly from your workflow, then assign its timing and visual placement through the timeline description. The node writes it to a temporary MP4 before rendering and attempts to remove that temporary file afterward. This input does not impose a particular track or order in the finished edit. No default value, numeric range, or selectable options are declared.

clip4

An optional VIDEO connection exposed to the timeline as @clip4. It provides another independently addressable video source for an edit containing multiple connected assets. As with the other video connections, the node prepares a temporary MP4, while the timeline controls when and how the material is displayed. Use the exact reference @clip4 when selecting this connected source in your timeline’s media-source field. No default value, numeric range, or selectable options are declared.

clip5

An optional VIDEO connection exposed to the timeline as @clip5. It is the fifth and final optional video socket listed by this node’s interface and lets you incorporate another workflow video without manually managing an intermediate saved file. The connected video is temporarily saved as MP4 and made available to the renderer; connecting it alone does not add a visible segment to the edit. No default value, numeric range, or selectable options are declared.

ComfyArt Timeline Render Output Parameters:

(none)

This node has no output sockets and does not return a video connection, image batch, or filename string for downstream nodes. Instead, it acts as an output node: it saves the rendered video in ComfyUI’s output directory and returns interface metadata containing the saved filename, subfolder, output location type, and an animated-media flag. That metadata allows the interface to present the saved result, but it is not a connectable workflow output. Use the saved file as your finished deliverable rather than expecting to connect this node directly to another processing node.

ComfyArt Timeline Render Usage Tips:

• Start from a known-valid timeline description for this renderer, then change one setting at a time. The supplied context does not include the complete top-level JSON schema, so an arbitrary JSON object may parse successfully without being a valid render specification.
• Use the exact connected-source references: @clip, @clip2, @clip3, @clip4, and @clip5. Disconnect unused video inputs to avoid saving unnecessary temporary MP4 files.
• Omit format to use the default mp4 format. Do not assume that any video extension is supported; explicitly selected formats must match the renderer’s encoder registry.
• Use fit: "contain" when preserving the entire source image matters. This is the visual clip default and fits the source inside the frame; uncovered areas reveal lower tracks or the black background. Use fit: "cover" when filling the frame matters more than retaining every edge of the source.
• Place background material on lower-numbered tracks and overlays on higher-numbered tracks. Within a track, the compositor selects active material in start-time order rather than freely stacking all overlapping clips, so use separate tracks for intentional visual layering.
• For a transition between consecutive clips on the same track, make the preceding clip’s end match the following clip’s start. The implementation checks this boundary within approximately 0.001 seconds and uses the following clip’s transition settings. The transition duration is centered on the join, extending half before and half after it.
• Adjust offset to choose where playback begins within a source, and speed to change how quickly source time advances. The default offset is 0 and default speed is 1; a speed of 2 advances through source material twice as quickly. A speed value of 0 is replaced with 1 by this implementation, so it is not a freeze-frame setting.
• Use maskShape: "circle" for a circular crop. Keep in mind that the shown transform handling applies uniform scaling and translation; it does not demonstrate support for arbitrary rotation or skew.
• Choose a project-specific filename_prefix, such as project_a/edit, to keep rendered versions organized. Ensure both the output and temporary directories have adequate free space, since connected videos are saved temporarily before the final render is produced.

ComfyArt Timeline Render Common Errors and Solutions:

JSONDecodeError: Expecting value / Expecting property name enclosed in double quotes

• Explanation: The timeline text could not be parsed as JSON. Common causes include an empty field, single quotes instead of double quotes, trailing commas, comments, or an ordinary written description in place of JSON.
• Solution: Check the timeline with a JSON validator, use double quotes for property names and text values, remove comments and trailing commas, and begin with a known-valid timeline specification.

AttributeError: 'list' object has no attribute 'get'

• Explanation: The timeline is valid JSON but its top-level value is a list rather than an object. The node expects an object because it immediately reads the format setting using spec.get. Other top-level values, such as a string or null, can produce similar errors.
• Solution: Supply a timeline object with the structure expected by the renderer, not a bare list of clips or a quoted JSON string.

ValueError: unsupported format '…'

• Explanation: The timeline’s format value is not present in the renderer’s encoder registry. This check happens before connected videos are prepared.
• Solution: Remove the format setting to use the default mp4, or select a format verified as supported by your installed renderer. Do not include a leading dot or assume that changing a file extension enables a new encoder.

KeyError: 'start' / KeyError: 'duration'

• Explanation: A visual clip specification is missing a required timing field. The supplied visual clip implementation reads both start and duration directly.
• Solution: Give each visual clip a numeric start time and duration in seconds. For example, a start of 0 and duration of 2 describe a clip scheduled for the first two seconds of the timeline.

ValueError: could not convert string to float

• Explanation: A numeric clip setting contains text that cannot be converted to a number. Fields such as start, duration, offset, and speed are converted to floating-point numbers.
• Solution: Use plain numeric values such as 2.5, not labels such as "2.5 seconds". Also check that track contains an integer-compatible value.

FileNotFoundError / No such file or directory

• Explanation: A source file may be unavailable, or an expected temporary file may not exist. An incorrectly spelled connected-source reference can also prevent the intended temporary source from being selected. Exact messages depend on the media loader.
• Solution: Confirm that source files still exist and are accessible. For connected sources, check the exact @clip reference and ensure the matching socket is connected. If the error names a temporary file, inspect earlier log messages for a failure while saving that video.

IndexError: list index out of range

• Explanation: One possible cause is opening a source that contains no video stream, because the shown decoder accesses the first video stream directly. An audio-only file cannot serve as a video clip through that path.
• Solution: Verify that the source contains playable video. For a still image, use the renderer’s image clip specification with type: "image" rather than relying on the default video type.

PermissionError / No space left on device

• Explanation: The node may be unable to create temporary videos or write the final output because a directory is not writable or the storage device is full. File deletion can also fail if a temporary file is locked.
• Solution: Check free space and write permissions for both ComfyUI’s temporary and output directories. Close applications holding temporary files open, and try a simple filename prefix in a writable output subfolder.

Media decoding or encoding error

• Explanation: Opening, decoding, saving, or encoding media can fail if a source is damaged or a required codec is unavailable. The supplied code does not define a single fixed error message for these failures.
• Solution: Test the source in a media player, try a known-working short video, and review the full error log to identify whether the failure occurred while preparing a connected video or rendering the final file. Re-export problematic source media into a format supported by your installation.