OpenKatana · Preview effect:
OpenKatana_preview_effect lets you try a single OpenKatana effect in isolation before committing it to a larger edit. It builds and renders a short preview so you can judge the effect’s appearance and, when relevant, its movement over time. You can experiment with an image or video from your project, or use a built-in moving test card designed to make visual changes easier to see, including a bright highlight suitable for evaluating glows and flares. The preview workflow provides a short video and a contact sheet for reviewing representative moments without inspecting every frame individually. By keeping the preview focused on one effect, this node helps you compare settings, spot unsuitable source material, and refine your creative choices before adding the effect to your main timeline.
OpenKatana · Preview effect Input Parameters:
project_id
A required STRING identifying the OpenKatana project in which the preview operation runs. Project selection matters because a supplied source file is resolved within that project rather than treated as an unrestricted file path. Choose the project containing the image or video you want to test. The supplied app template uses my-film as an example project identifier, but the provided node class does not establish it as a default. No minimum length, maximum length, or list of valid project identifiers is shown in the supplied interface.
arguments
A required STRING used by the shared OpenKatana tool wrapper to supply additional tool arguments. The wrapper processes this value together with the project identifier and the separately exposed fields before calling the preview tool. The supplied app template uses the JSON object text {}, which is a useful starting point when the dedicated fields provide everything you need. The underlying preview implementation also accepts timing and sizing controls: seconds is validated from 0.01 to 60, fps must be an integer from 1 to 60, at must be at least 0, and max_width must be an integer from 64 to 960. These are not separate node inputs; if you provide them through the arguments mechanism, they must follow the tool’s accepted argument structure. The rounded product of duration and frame rate must also stay within the implementation’s preview-frame limit, whose numeric value is not included in the supplied context. No default value for this input, or defaults for those underlying controls, are established by the provided node class.
effect
A required STRING naming the single effect you want to preview. The name determines which effect is validated and placed in the preview timeline, so it must match an effect supported by OpenKatana. The supplied template uses local_twirl as an example, and the tests verify preview-timeline support for all names in the local-effects collection. The complete list of accepted names is not included in the provided context; consult docs/TIMELINE.md for effect names and fields and docs/EFFECTS-PLAYBOOK.md for practical recipes. No default, minimum length, or maximum length is specified by the supplied node class, and the template example should not be interpreted as a universal default.
params
A required STRING containing the JSON-formatted settings for the selected effect. These settings control what the effect does visually, and they are checked against the selected effect before rendering begins. The empty JSON object {} requests effect defaults where the effect supports that usage; some effects may need additional settings, so use the effect documentation when necessary. The supplied template demonstrates animated settings through an angle value containing keyframes, including the easing label inout3. In that example, easing attached to a key shapes the movement toward the next key, so attaching easing only to the last key does not shape any following movement. Available fields, ranges, and defaults depend on the effect, and no universal parameter schema or node-level default is shown in the provided class.
source
An optional STRING specifying a project-relative image or video path to use as the preview material. The file must exist within the selected project and have an extension recognized by the implementation’s still-image or video lists; those complete extension lists are not included in the supplied context. When no source is supplied, the preview implementation uses its moving test card, and the supplied app template leaves this field empty for that purpose. Images are corrected for EXIF orientation, converted to RGB, and resized for preview preparation. Videos are sampled into a short excerpt at the requested preview frame rate and size, without audio. A video that ends before the requested preview duration produces a shorter preview and a warning. HDR video and video carrying rotation metadata require explicit media conformance before previewing. No character-length limits or explicit node-class default are provided.
after
An optional STRING accepted by the shared OpenKatana tool interface. In the supplied execution method, this value is received but is not passed to the preview tool, merged into its arguments, or otherwise used in the shown code. Consequently, the available source does not establish any effect on preview appearance, duration, or execution order beyond a possible workflow connection dependency. Leave it unconnected unless your surrounding workflow requires it, and do not use it to supply effect settings. The execution method defaults it to None when omitted; no string default, allowed-value list, or length range is provided.
OpenKatana · Preview effect Output Parameters:
result_json
A STRING containing the response produced by the OpenKatana tool wrapper for the preview call. This is the node’s only output, so it should be treated as a textual tool result rather than a directly connectable ComfyUI image or video tensor. The underlying preview workflow prepares source material, writes a validated timeline.json, renders the preview, and selects representative frames for review; the supplied app description identifies the intended preview products as a short video and a contact sheet. Inspect the returned response to find whatever preview information and artifact references the tool exposes. The provided code does not show the response schema, exact JSON keys, or how errors and warnings are serialized, so downstream processing should be based on the actual returned structure rather than assumed field names.
OpenKatana · Preview effect Usage Tips:
- Start with no source and
paramsset to{}for an effect that supports defaults. The moving test card gives you a consistent baseline before you test the effect on your own artwork. - Use
local_twirlas a documented example effect name, but obtain its supported settings fromdocs/TIMELINE.mdordocs/EFFECTS-PLAYBOOK.mdrather than guessing parameter names. - Preview effects that depend on earlier or later frames using a video or the moving test card. A still image has no neighboring source frames, so these effects can show no change even when the settings are valid.
- For faster exploratory renders, use a shorter duration and a smaller preview width through the tool’s accepted arguments structure. Keep
max_widthwithin 64–960 and the integer frame rate within 1–60; increasing duration and frame rate together also increases the number of frames to render. - Use
atto examine a particular moment in a video, such as a bright highlight or fast movement. Keep it below the source duration; it does not shift a still image or the generated test card. - When animating effect settings with keyframes, place the easing instruction on the key that begins the transition. The supplied test confirms that an easing instruction on the final key has no following transition to influence.
- Review both the contact sheet and the rendered video. Representative frames help you compare appearance, while playback is needed to judge motion and timing.
- Prepare HDR or rotation-tagged footage with the appropriate OpenKatana import/conformance tool before previewing it, and remember that the video excerpt is prepared without audio.
OpenKatana · Preview effect Common Errors and Solutions:
source: no file at ... in the project (give a project-relative image or video path)
- Explanation: The supplied source path does not resolve to an existing file inside the selected project.
- Solution: Confirm that
project_idselects the correct project, check the filename and folder spelling, and provide a project-relative image or video path. Omit the source to test the effect on the built-in card instead.
source: expected an image (...) or a video (...)
- Explanation: The file exists, but its extension is not in the implementation’s supported image or video extension lists. The actual error includes the accepted extensions.
- Solution: Use a file type listed in the error message or convert your media to a supported format. Renaming an extension alone does not convert the file.
source: the file has no video stream
- Explanation: The source was handled as a video file, but its metadata contains no video stream.
- Solution: Choose a playable video containing visible frames, rather than an audio-only file, or export a new video from your editing application.
HDR/rotated video needs explicit conformance first (import_hdr_media / import_media)
- Explanation: The video is marked as HDR using the detected transfer characteristics, or it carries nonzero rotation metadata. This preview path requires that media to be conformed first.
- Solution: Prepare the file using the appropriate
import_hdr_mediaorimport_mediaworkflow, then preview the conformed media.
at: ... s is past the end of the source (... s)
- Explanation: The requested video start time is equal to or greater than the detected source duration.
- Solution: Set
atto a time strictly before the end of the video, preferably leaving enough footage for the preview duration you want.
source: no video frames at that time
- Explanation: The video excerpt preparation produced no usable frames at the requested position.
- Solution: Try an earlier start time, verify that the video plays correctly, and re-export or conform the source if the problem persists.
seconds x fps gives ... frames; a preview has 1..... frames
- Explanation: The rounded duration multiplied by frame rate produced a frame count outside the allowed preview budget. The actual error reports both the calculated count and the permitted maximum.
- Solution: Reduce duration or frame rate when the count is too high. If it rounds to zero, increase the duration enough to produce at least one frame.
Invalid seconds, fps, at, or max_width value
- Explanation: These underlying preview controls are validated before rendering. The precise validation-message wording is not included in the supplied context.
- Solution: Keep
secondsbetween 0.01 and 60, use an integerfpsbetween 1 and 60, keepatat or above 0, and use an integermax_widthbetween 64 and 960.
Invalid effect name or effect parameters
- Explanation: The implementation checks the effect and its settings before preparing the preview. Unsupported names or settings that do not satisfy the effect’s contract can stop the operation; exact error wording is not supplied.
- Solution: Check the effect name and parameter fields against
docs/TIMELINE.md. Ensureparamscontains valid JSON and start with documented defaults or a recipe fromdocs/EFFECTS-PLAYBOOK.md.
unexpected inputs: ...
- Explanation: The node wrapper received additional named fields that are not part of its typed interface.
- Solution: Use only the six documented node inputs. Supply supported additional tool arguments through
argumentsrather than adding new node input names.
at_ignored: at only moves the start of a video source; a still has no time
- Explanation: This is a warning rather than a rendering failure. A nonzero
atwas supplied without a video source, so it cannot change the preview’s source position. - Solution: Set
atto 0 or use a video source when you need to choose a starting moment.
source_short: the source has ... frames from ... s; the preview is that long
- Explanation: This warning means the video excerpt contains fewer frames than requested, so the preview is shortened to the available footage.
- Solution: Choose an earlier start time, request a shorter duration, or use a longer source video.
still_source: ... works on earlier or later source frames and a still picture has none
- Explanation: This warning means the selected effect needs neighboring source frames, but the source is a still image. The preview can render without showing the expected change.
- Solution: Use a video source or omit
sourceto preview the effect on the moving test card.
