OpenKatana · Analyze render motion:
OpenKatana_analyze_render_motion helps you review a rendered video for possible uneven motion, judder, stalls, and repeated frames without changing the video. It compares consecutive decoded frames using Farneback optical flow, a technique that estimates how image details move between frames. To keep analysis manageable, it measures motion on reduced-size images and scales the measurements back to the original video’s pixels per frame. Planned cuts can be excluded from motion comparisons so that a normal shot change is not mistaken for a motion problem. The resulting diagnostics help you identify moments worth checking during playback, rather than assigning an artistic quality score. Intentional freezes, occlusions, and flashes can still trigger warnings, so the findings are review candidates rather than proof of a faulty render. This node performs analysis only: it does not interpolate frames, smooth motion, or revise your video.
OpenKatana · Analyze render motion Input Parameters:
project_id
A required STRING identifying the OpenKatana project under which the analysis runs. The underlying API resolves this project and checks its state before analyzing the video, then uses the project’s motion-reports output location for the report. Choose the project associated with your review workflow so that the diagnostics are stored in the appropriate project context. The supplied node interface does not specify a default value, minimum or maximum string length, or a list of valid identifiers; use a valid existing project identifier.
arguments
A required STRING containing the tool arguments as JSON text. This is where you specify the local video and any motion-analysis settings; these settings are JSON entries, not separate node input sockets. For example, {"source":"/path/to/render.mp4","cuts":[66],"work_width":480,"moving":1.5,"ratio":2.2,"stall":0.25} supplies a video, excludes the transition into frame 66, and explicitly sets the underlying API defaults. The API requires source, a local video path, and accepts cuts, an optional list of incoming cut-frame indices whose default is None; valid cut indices run from 1 through the actual decoded frame count minus 1. Frame numbering starts at 0, and a cut at 66 skips the optical-flow comparison from frame 65 to frame 66, not the rest of the clip. The work_width setting defaults to 480 and controls the analysis width; the implementation uses the smaller of this value and the source width, preserving the aspect ratio. A smaller working width can reduce processing cost but may lose subtle motion detail. The moving, ratio, and stall settings default to 1.5, 2.2, and 0.25 respectively and configure the heuristic motion flags; the report labels them as moving_px, judder_ratio, and stall_px. Pixel-based thresholds refer to source pixels per decoded frame, rather than reduced-image pixels. The provided excerpts do not show the complete flagging rules or accepted numeric ranges for these settings, so those limits should not be assumed. The node interface itself does not declare a default JSON string or string-length limits.
after
An optional STRING accepted by the shared tool execution interface, with an execution-function default of None. The supplied implementation receives this value but does not explicitly read it or forward it to the motion-analysis API, so it is not a motion threshold, video path, or report setting. If your wider OpenKatana workflow uses this socket for connection-based ordering, keep that use separate from the analysis configuration in arguments; the excerpt does not establish any additional meaning for its contents. No allowed values, string-length limits, or interface-level default are shown.
OpenKatana · Analyze render motion Output Parameters:
result_json
A STRING containing the serialized response returned by the tool invocation. The underlying analysis creates a report containing the source video’s SHA-256 fingerprint, decoded frame count, frame rate, width, height, excluded cut indices, heuristic flags, duplicate-frame indices outside cuts, threshold settings, and descriptions of the measurement method and its limitations. It also supplies per-frame records to the report writer, including the frame index, cut status, duplicate status, median motion, and 95th-percentile motion. Median motion describes the typical measured movement across the image, while the 95th percentile highlights the higher-motion portion of the image without relying on the single largest measurement; both use source pixels per decoded frame. Motion measurements are unset for the first frame and excluded cut transitions because no eligible preceding-frame comparison is made. Duplicate detection checks exact equality between consecutive decoded full-size frames, which is different from estimating very low motion. Use this output to inspect the returned report information or pass the response to a later processing step. The supplied excerpts do not show the exact response envelope or report-writer return structure, so do not assume that every report field appears directly at the top level of this JSON string.
OpenKatana · Analyze render motion Usage Tips:
- Start with the API defaults by providing only the required local video path in
arguments, for example{"source":"/path/to/render.mp4"}. Review the findings before changing thresholds. - Add known shot boundaries through
cutsto avoid measuring motion across unrelated images. For example,"cuts":[66]excludes the comparison into zero-based frame 66, which is the 67th decoded frame. - Treat an intentional freeze separately from a cut. Marking its starting frame as a cut excludes only that transition; subsequent repeated frames can still appear as duplicates or possible stalls.
- Keep
work_widthat 480 for an initial review. Lower it when you need a less expensive pass on long or large videos, or increase it when subtle motion needs closer inspection, while remembering that the implementation never analyzes at a width greater than the source width. - Keep threshold units in mind when comparing renders. The measurements are scaled to source pixels per frame, so changing the video resolution or frame rate can change the measured values even when the overall movement looks similar.
- Inspect flagged moments in playback before deciding to rerender. Holds, flashes, and objects moving in front of one another can produce legitimate warnings, and the node does not determine whether those moments are artistically appropriate.
- Use a constant-frame-rate video where possible. The report explicitly states that constant frame rate is expected; variable timing can make frame-to-frame measurements harder to interpret.
- Analyze only completed, stable video files. The implementation checks the source fingerprint before and after analysis and rejects a file that changes during the process.
- Keep each analysis segment between 3 and 36,000 decoded frames. If you split a longer video into separate files, adjust each segment’s cut indices to match its own decoded frame numbering.
- Ensure the OpenKatana vision extra is installed in the environment running ComfyUI. This analysis depends on computer-vision functionality and does not provide an automatic repair step.
OpenKatana · Analyze render motion Common Errors and Solutions:
Motion analysis needs at least three decoded frames
- Explanation: The analyzer decoded fewer than three frames. The video may be too short, incomplete, damaged, or not decoding correctly.
- Solution: Confirm that the file plays normally and contains at least three frames. Wait for rendering or encoding to finish, or export a readable copy before running the node again.
Analyze at most 36000 frames per segment
- Explanation: The analyzer encountered more than 36,000 decoded frames in a single analysis run.
- Solution: Split the video into segments containing no more than 36,000 frames and analyze them separately. Update the cut indices for each segment.
cuts must be a list of incoming master-frame indices
- Explanation: The supplied
cutsvalue is not a list. A single number or a text value does not meet the required format. - Solution: Use a JSON array such as
"cuts":[66]or"cuts":[24,66]. If there are no planned cuts, omit the entry or use"cuts":[].
Invalid cut index — exact validation message may vary
- Explanation: A cut value is not an integer within the permitted range. For a video with N decoded frames, valid cut indices are 1 through N minus 1. Frame 0 cannot be an incoming cut because it has no preceding decoded frame.
- Solution: Count from zero, remove negative or out-of-range indices, and use whole numbers. Base the indices on the actual file being analyzed, especially after trimming or splitting it.
Source changed during motion analysis
- Explanation: The source file’s SHA-256 fingerprint changed while the analysis was running. Another process may still have been rendering, encoding, replacing, or editing that file.
- Solution: Wait until the video is complete and no application is modifying it, or analyze a separate stable copy.
Invalid video fps — exact validation message may vary
- Explanation: The analyzer validates the reported frame rate against a range of 0.01 to 1,000 frames per second. Missing, invalid, or unsupported video metadata can fail this check.
- Solution: Check the file’s frame-rate information and export a standard constant-frame-rate copy if necessary. Confirm that the copy plays correctly before retrying.
Invalid arguments JSON — exact error message depends on the shared tool layer
- Explanation: The
argumentsinput must contain JSON text that the tool can interpret. Missing quotes, trailing commas, or an incorrectly formatted object can prevent the analysis from starting. - Solution: Begin with a minimal object such as
{"source":"/path/to/render.mp4"}. Use double quotes around property names and string values, then add optional settings one at a time.
Missing or unreadable source video — exact error message depends on source validation and decoding
- Explanation: The underlying API requires a local video source. An incorrect path, inaccessible file, or decoding problem can stop the analysis before it produces useful measurements.
- Solution: Provide a valid local path in
sourceand verify that the ComfyUI process can read it. If decoding remains unsuccessful, export a new copy in a format supported by your installed video tools.
Vision dependency unavailable — exact error message depends on the environment
- Explanation: The API states that this operation requires the vision extra, and the implementation uses OpenCV for video decoding and optical-flow measurements.
- Solution: Install the OpenKatana vision dependencies according to the package’s installation instructions in the same Python environment used by ComfyUI, then restart ComfyUI.
Project lookup or state check failed — exact error message depends on the project layer
- Explanation: The API resolves
project_idand checks the project state before analyzing the source. An unknown identifier or unavailable project can prevent execution. - Solution: Verify that the project exists and that you supplied its actual identifier rather than its display name or video filename. Resolve any project-loading problem before rerunning the analysis.
unexpected inputs: ...
- Explanation: The node explicitly rejects additional execution fields that are not declared by its typed interface. Analysis settings such as
work_widthare not separate sockets in the supplied interface. - Solution: Use only
project_id,arguments, and the optionalafterinput. Put the video path and analysis settings inside the JSON object supplied througharguments.
