OpenKatana · Revise motion:
OpenKatana_revise_motion helps you review and refine a project's camera motion against a reference, making it easier to identify movement that is too weak or otherwise outside the comparison criteria. It uses measured motion differences to guide a limited revision process rather than relying only on visual guesswork. The supplied implementation restricts revision proposals to shot camera settings, preserving the rest of the edit's structure. Supported adjustments include adding short camera “punch” movements and increasing their strength when motion is insufficient, with limits to prevent unrestricted changes. This makes the node useful for improving motion consistency while protecting your existing edit, although some comparisons may still require an editor's judgment rather than an automatic correction.
OpenKatana · Revise motion Input Parameters:
project_id
A required STRING identifying the OpenKatana project you want to work on. It provides the project context for the motion-revision tool, so you should use the identifier of the project whose camera motion you intend to review. Choosing a different project changes the edit being evaluated; it is not simply a label for the result. The supplied node interface does not specify a default value, allowed identifier format, or minimum or maximum string length.
arguments
A required STRING carrying the underlying tool's arguments as a JSON object. The node processes this text together with the project context before invoking the motion-revision tool. The supplied API signature requires a reference string and supports max_revisions with a default of 2, locked_shots with a default of None, floor with a default of 0.6, reference_start with a default of 0, reference_duration with a default of None, apply with a default of False, and ceiling with a default of None; these are fields inside the argument text, not separate node inputs. They let you specify the reference, limit revision attempts, protect selected shots, configure comparison settings, select a reference segment, and control whether revisions are applied. For example, {"reference":"path/to/reference.mp4","max_revisions":2,"apply":false} explicitly requests a reference comparison without enabling application of revisions. The supplied node class does not specify a default text value, minimum or maximum string length, or selectable options for this input. The API excerpt also does not establish validated numeric ranges, the exact interpretation of the comparison thresholds, or the complete set of accepted reference formats.
after
An optional STRING that can provide a workflow dependency when connected to another node's output, allowing you to place this operation after earlier work in the graph. In the supplied execution method, its value is accepted but is not read or forwarded to the motion-revision tool, so it does not directly change the reference comparison, camera adjustments, or revision settings. Treat it as a connection for workflow ordering rather than a place to supply motion instructions. The Python execution method defaults it to None when omitted; the supplied interface does not specify a text-field default, allowed options, or minimum or maximum string length.
OpenKatana · Revise motion Output Parameters:
result_json
A STRING containing the response returned through the tool-response wrapper. The underlying motion-revision API returns a dictionary, so this output is the node's text-based way of passing the tool's result to you or to subsequent workflow steps. Read it to determine the outcome of the comparison and revision operation rather than treating the presence of an output as proof that the motion passed or that changes were applied. The supplied context confirms that motion records can contain a status such as needs_editor, indicating that editor attention may still be needed, but it does not show the complete return structure or response-wrapper format. Consequently, specific report fields, file paths, revision identifiers, and error-envelope details cannot be guaranteed from the supplied code.
OpenKatana · Revise motion Usage Tips:
-
Begin with an explicit non-applying configuration, such as
{"reference":"path/to/reference.mp4","max_revisions":2,"apply":false}. Inspect the result before choosing to run withapplyset totrue; do not assume that generating a revision proposal automatically applies it. -
Keep tool settings inside
arguments. This node exposes onlyproject_id,arguments, andafter; settings such asreference,floor, andmax_revisionsare not additional input sockets. -
Start with the API's default
max_revisionsof 2. The implementation loops overmax_revisions + 1iterations, so the revision limit should not be interpreted as an identical count of all evaluation passes. Increase it cautiously rather than assuming more attempts guarantee a successful match. -
Use
locked_shotsinside the JSON arguments to protect shots you do not want revised. Confirm the shot numbering used by your project before supplying the list; the supplied snippets use internal shot indices but do not establish the external numbering convention. -
Use
reference_startandreference_durationwhen only a particular section of the reference is relevant. Their API defaults are 0 andNone, respectively; confirm the expected time units in your installed tool before entering non-default values, because the supplied excerpts do not document those units. -
Start with the default
floorof 0.6 and noceilingunless you have confirmed how the installed comparison report interprets these thresholds. The excerpts expose these controls but do not provide enough detail to recommend precise threshold values for a particular visual style. -
Review motion changes in a preview, especially around intended pauses or freezes. The supplied example explicitly identifies an intentional freeze, illustrating why little movement is not always an artistic mistake.
-
Expect bounded camera corrections rather than unrestricted animation changes. The shown implementation caps punch events at eight per shot, and its insufficient-motion adjustment caps the punch strength at 0.15. If the reference requires a substantially different edit or movement style, manual camera work may be more appropriate.
OpenKatana · Revise motion Common Errors and Solutions:
unexpected inputs: ...
- Explanation: This is an explicit error from the node's execution method when it receives keyword inputs that are not declared by its interface. It can occur if a custom workflow or integration tries to pass tool settings as additional node inputs.
- Solution: Supply only
project_id,arguments, and the optionalafterinput. Put settings such asreference,max_revisions, andapplyinside the JSON text inarguments.
Invalid JSON in arguments — exact message depends on the argument parser
- Explanation: The argument text must be readable by the argument-processing layer. Missing quotation marks, trailing commas, or Python-style values such as
Falseinstead of JSON'sfalsecan prevent the call from being prepared. The supplied excerpts do not show the parser's exact error wording. - Solution: Use a JSON object with double-quoted field names and string values. Start with
{"reference":"path/to/reference.mp4","apply":false}and add settings one at a time.
Missing required reference — exact message depends on the tool dispatcher
- Explanation: The underlying API requires
referenceand provides no default for it. Supplying a project identifier alone does not provide the material needed for a reference comparison. - Solution: Include a valid
referencestring insidearguments. If the reference is a file, verify that it is available to the environment running OpenKatana, not only to your local browser.
Incorrect argument types — exact message depends on validation
- Explanation: The API expects particular value types: for example,
max_revisionsis an integer,locked_shotsis a list of integers or null, andapplyis a Boolean. Quoted numbers, a single text value in place of a list, or a string such as"false"may be rejected or handled differently from the intended value. - Solution: Use values such as
"max_revisions":2,"locked_shots":[0,2], and"apply":false. Use JSONnullrather than PythonNonewhen explicitly supplying an unset optional value.
measure the current revision against the reference with revise_motion
- Explanation: This exact message appears in the supplied strict-gate test when the current project revision still needs a recorded motion comparison. It is a workflow requirement, not necessarily a failure inside this node.
- Solution: Run the motion comparison for the current revision and inspect its result. A recorded comparison can satisfy this gate even when its status is
needs_editor, so passing the gate does not by itself prove that the motion meets the comparison criteria.
needs_editor
- Explanation: This is a status shown in the supplied test, not a Python exception. Treat it as a signal to review the motion manually rather than as confirmation of a successful automatic correction. The excerpts do not document every condition that produces it.
- Solution: Inspect the returned response and preview the project. Check whether protected shots, intentional stillness, or differences that require more than camera-only changes are relevant, then make an editorial decision before proceeding.
Revisions were proposed, but the project appears unchanged
- Explanation: This is a troubleshooting symptom rather than a quoted error message. The API defaults
applytoFalse, and the revision process is limited to shot camera changes. A completed call therefore does not necessarily mean that project changes were applied or that non-camera parts of the edit were modified. - Solution: Review the result first, then explicitly use
"apply":trueif you intend to apply revisions. Also check your locked-shot settings and remember that clip structure and other non-camera edit content are outside the shown revision scope.
