OpenKatana · Analyze clip:
OpenKatana_analyze_clip gives you access to OpenKatana’s clip-analysis and processing tool from a ComfyUI workflow. It supports four operation categories: masks, faces, interpolation, and retiming. These categories let you target tasks such as working with subject masks, analyzing faces, or requesting frame and timing processing for an existing project clip. The node acts as a bridge to OpenKatana’s project-based editing tools rather than performing the image processing directly inside its wrapper. This makes it useful when you want to incorporate clip-level analysis into a larger editing workflow. The supplied context also shows that mask work can require visual review and refinement, so processing a clip should be treated as one step in achieving a production-ready result, not a guarantee that every frame is immediately ready to use.
OpenKatana · Analyze clip Input Parameters:
project_id
A required STRING identifying the OpenKatana project that contains the clip you want to process. The node passes this value through its argument-building system so the tool call can target the intended project. Use the identifier of an existing project, rather than assuming that a project’s display name or a folder path is interchangeable with its identifier. Selecting the correct project is important because clip identifiers are interpreted within the project context. No default value, length limits, or list of permitted identifiers is shown in the supplied node source.
arguments
A required STRING carrying the arguments for the tool call. Supply a JSON object containing the settings expected by the underlying analysis API; the provided signature identifies clip_id and operation, with optional options and apply settings. For example, {"clip_id":"your_clip_id","operation":"masks","apply":false} expresses a mask-operation request for a particular clip. The documented operation choices are exactly masks, faces, interpolate, and retime. The underlying API defaults options to None and apply to False; these are tool-call defaults, not a documented default for the STRING field itself. The supplied code does not show the accepted contents of the operation-specific options dictionary, numeric limits, or the exact effects of applying each operation. Although these settings belong inside this argument payload, they are not separate node inputs. No default text or length limits for arguments are shown.
after
An optional STRING accepted by the node’s execution method, with a Python default of None when omitted. In the supplied wrapper, this value is not referenced when building the analysis arguments or invoking the tool, so it is not shown to control the selected operation, its settings, or its processing results. It may serve a role elsewhere in the surrounding workflow system, but that behavior is not established by the provided code. Leave it unconnected unless your broader OpenKatana workflow provides a documented reason to use it; do not put analysis settings here. No permitted values, length limits, or interface-level default text are shown.
OpenKatana · Analyze clip Output Parameters:
result_json
A STRING containing the tool response as JSON text. The wrapper invokes the OpenKatana tool and passes its response through a response-formatting function; the underlying analyze_clip method is annotated to return a dictionary. This output is therefore a structured text response, not a direct ComfyUI IMAGE, MASK, or video connection. Inspect or parse it to understand the result of the requested operation before taking further workflow steps. The supplied context does not define the response fields, so you should not assume that it always contains a particular file path, success flag, measurement, or updated clip reference. Its exact contents depend on the operation and the tool implementation.
OpenKatana · Analyze clip Usage Tips:
- Start with a known project identifier and an existing clip identifier from that project. Checking both before processing helps avoid requests aimed at the wrong clip or project.
- Use a minimal argument object first, such as
{"clip_id":"your_clip_id","operation":"masks","apply":false}. Add operation-specificoptionsonly when you have documentation for their supported names and values. - Choose the operation explicitly using one of the four documented values:
masks,faces,interpolate, orretime. Do not substitute related workflow names such ascutoutfor the API’s operation values. - Leave
applyomitted or set it tofalsefor an initial request when you do not intend to request application of the result. The API defaults it toFalse, but the supplied code does not establish exactly what processing still occurs or what changes each operation applies; inspect the response before requesting application. - Review generated masks visually. The supplied gate logic calls for matte review every 0.25 seconds and on the last frame, and it directs rejected mattes toward refinement or another mask run. This is especially useful for catching brief failures that are easy to miss during normal playback.
- If your mask-processing route uses the supplied SAM2 cutout workflow, select an installed SAM2 model and provide positive subject points on the first frame; that workflow also supports optional negative points and propagates the selection through the clip. The mapping from
analyze_clipoptions to this workflow is not shown, so obtain the supported option schema before encoding these settings. - Inspect
result_jsonbefore connecting subsequent automation. Treat it as a tool response to interpret, rather than assuming the node directly supplies a mask sequence or processed video.
OpenKatana · Analyze clip Common Errors and Solutions:
unexpected inputs: ...
- Explanation: This is an explicit error pattern in the node wrapper. It occurs when extra execution fields are supplied that are not recognized by the node’s declared typed inputs.
- Solution: Use only the exposed inputs:
project_id,arguments, and optionalafter. Put tool settings such asclip_id,operation,options, andapplyinside theargumentspayload rather than adding new node inputs.
Invalid JSON in arguments — possible parsing error
- Explanation: The exact parsing error text is not provided, but malformed argument text can prevent the tool request from being constructed. Common mistakes include single quotes, trailing commas, or Python-style
Falseinstead of JSON-stylefalse. - Solution: Supply a valid JSON object with double-quoted property names and strings. Start with
{"clip_id":"your_clip_id","operation":"masks","apply":false}and replace the clip identifier with your actual value.
Missing clip_id or operation — possible argument validation error
- Explanation: The underlying API signature requires both values. If the argument-building system does not receive them, the request may fail before clip processing begins. The exact error message is not shown.
- Solution: Include both
clip_idandoperationinarguments, and make sure neither is accidentally placed inafter. Use an existing clip identifier and one of the documented operation names.
Unsupported operation — possible validation or dispatch error
- Explanation: The supplied API signature lists only
masks,faces,interpolate, andretime. Other names fall outside that documented contract, although the exact runtime validation behavior is not shown. - Solution: Use one of the four listed strings exactly. If you need mask refinement, keep the operation as
masksand consult the supported options schema rather than inventing a new operation name.
Project or clip not found — possible lookup error
- Explanation: Processing depends on identifying a project and a clip within it. An incorrect identifier or a clip belonging to another project can prevent the tool from locating the intended media. The supplied code does not include the exact lookup error message.
- Solution: Confirm that the project exists and that the clip identifier belongs to that project. Copy identifiers from the project’s current state rather than using filenames or display names unless they are explicitly the recorded identifiers.
Specify an installed SAM2 model choice, e.g. sam2.1_hiera_base_plus.safetensors
- Explanation: This exact error appears in the supplied cutout workflow when its model setting is missing. It is relevant only if your analysis request reaches that SAM2-based workflow; the context does not show that every mask request uses it.
- Solution: Select an installed SAM2 model supported by that workflow. Confirm how your OpenKatana installation passes the model setting through analysis options before adding it to the argument payload.
the matte of clip … was rejected in review: refine it (analyze_clip masks mode refine) or re-run masks
- Explanation: This is a review-gate message shown in the supplied code, not necessarily an exception from this node. It indicates that the clip’s matte has been reviewed and rejected, so completing the processing request alone has not satisfied the quality check.
- Solution: Inspect the problematic frames, then refine the mask using the documented refinement options or rerun mask processing. Review the replacement matte again, including samples every 0.25 seconds and the final frame; the exact JSON settings for refinement are not included in the supplied context.
