OpenKatana · Save reference plan:
OpenKatana_save_reference_plan records a verified specification for matching an edit to a reference, giving you a persistent checklist of timing, text, fonts, and selected shot or effect requirements. It validates the specification before saving it, records a SHA-256 fingerprint of the reference file so later checks can detect changes, and preserves a history copy when replacing an existing plan. The saved specification supports later audits of the timeline, and the tool documentation states that rendering blocks mismatches against recorded requirements. This node does not automatically recognize reference content, transcribe text, identify fonts, or confirm that your specification accurately describes the reference: you must review those details yourself. Its main benefit is making an approved creative target explicit and checkable, rather than relying on visual memory or loosely worded instructions.
OpenKatana · Save reference plan Input Parameters:
project_id
A required STRING identifying the OpenKatana project in which you want to save the reference plan. The operation resolves this project, accesses its state, and writes the plan to its project directory as reference-plan.json. Choose the project that will contain the timeline you intend to compare with the reference; saving to a different project separates the specification from the intended edit. The supplied interface does not specify a default value, length limits, or an allowed list of identifiers.
arguments
A required STRING carrying the tool arguments, including the reference specification as a JSON object under plan. The plan requires source, a reference-file path; fps, a number from 1 to 120; frames, an integer of at least 1; and cut_frames, a list containing every internal shot boundary. Cut positions must be integers from 1 through ``frames
- 1
in strictly increasing order; use[]for a single shot. Optional plan fields includetexts,fonts,shots,allow_extra_text, andnotes. When provided,texts,fonts, andshotsmust be arrays. Each text entry supportstext,f0,f1, andfamily:textmust be the literal transcription,f0must be an integer from 0 throughframes - 1, andf1must be an integer fromf0 + 1throughframes. The optionalallow_extra_textfield must be a Boolean and defaults totruewhen omitted. Omitted text, font, and shot arrays are treated as empty arrays during the shown validation. The supplied context does not provide the complete font or shot-entry schema, so consult the tool-audit guide before specifying those requirements. A minimal single-shot example is{"plan":{"source":"/path/to/reference.png","fps":24,"frames":24,"cut_frames":[]}}``. The interface does not specify a default or length limits for the STRING itself.
after
An optional STRING accepted by the node wrapper, with a Python execution default of None. In the supplied implementation, this value is not forwarded to the reference-plan API and does not change the plan, reference fingerprint, or saved file contents. Its presence can provide a connection point in the node graph, but the supplied code does not define a required value format or additional sequencing behavior. No minimum, maximum, or selectable options are specified.
OpenKatana · Save reference plan Output Parameters:
result_json
A STRING containing the tool response in JSON form. On success, the underlying API returns saved, the path to the project's reference-plan.json file, and note, whose text is This records an agent/user-verified specification, not automatic reference recognition. The saved file contains the validated plan, the resolved reference path, its SHA-256 fingerprint, and a recording timestamp; these stored details are not all returned directly in the success payload. Use the returned path to identify the saved specification and the note to distinguish successful recording from automatic reference analysis. A successful save does not mean the current timeline matches the plan or that the plan faithfully describes the reference; those require a separate audit and visual review. The provided node code wraps the API response, but the exact outer response structure is not shown.
OpenKatana · Save reference plan Usage Tips:
- Review the reference visually before saving its specification. Check the wording, timing, fonts, and effects you intend to enforce: a later audit checks the recorded requirements, not whether you described the reference correctly.
- Use frame positions rather than seconds for
cut_frames,f0, andf1. For example, at 24 fps, a cut at one second is frame 24; a two-second plan can use"frames":48and"cut_frames":[24]. - Include every internal shot boundary, but do not include frame 0 or the total frame count in
cut_frames. Keep the positions strictly increasing, and use[]when there is only one shot. - Preserve text exactly, including capitalization, punctuation, and spacing. If you want to prohibit additional text, explicitly set
"allow_extra_text":falserather than relying on its default oftrue. - Use the tool-audit guide for font-file hash requirements and shot-setting details. The supplied excerpts identify these capabilities but do not provide enough schema information to safely construct all such entries.
- Keep the reference file unchanged after recording the plan. A test confirms that changing its contents makes a later audit report that the plan no longer matches, even when the file path stays the same.
- Save a timeline before running the separate reference-plan audit. Saving this node's plan alone does not perform that audit or create a timeline.
- Treat replacing the plan as a specification revision, not a shortcut around a mismatch. Existing plans are copied into the project's
historydirectory before replacement, so revise only after confirming the new requirements.
OpenKatana · Save reference plan Common Errors and Solutions:
Reference plan needs a source path
- Explanation: The plan's
sourcevalue is missing or is not a string. The node needs a reference-file path so it can resolve the file and record its fingerprint. - Solution: Supply a quoted path inside
plan, such as"source":"/path/to/reference.png", and make sure the file is available to the OpenKatana environment.
cut_frames must list all internal shot boundaries; [] for one shot
- Explanation:
cut_framesis missing or is not a JSON array. This field is required even when your reference has no cuts. - Solution: Use an array such as
"cut_frames":[24,48]for multiple shots, or"cut_frames":[]for one shot.
Cut frames must strictly increase
- Explanation: A cut position repeats an earlier position or appears out of order. For example,
[12,4]is invalid, and the supplied test confirms that this invalid plan is not saved. - Solution: Remove duplicates and arrange the verified cut positions in ascending order. Also confirm that all cuts are internal boundaries rather than the beginning or end of the plan.
Numeric validation failure for fps, frames, cut frame, text.f0, or text.f1
- Explanation: A numeric field has the wrong type or falls outside its permitted range. The exact error wording from the numeric-validation helper is not supplied.
- Solution: Set
fpsbetween 1 and 120 andframesto an integer of at least 1. Use integer cut positions from 1 throughframes - 1. For each text entry, use an integerf0from 0 throughframes - 1and an integerf1fromf0 + 1throughframes. Enter numbers without quotation marks.
texts must be an array / fonts must be an array / shots must be an array
- Explanation: One of these optional fields contains something other than a list, such as a single object, a string, or
null. Each field produces its corresponding error message. - Solution: Put entries inside square brackets, use an empty array if there are no entries, or omit the optional field. Consult the tool-audit guide for the complete font and shot-entry formats.
allow_extra_text must be boolean
- Explanation:
allow_extra_textcontains a value other than a JSON Boolean. - Solution: Use
trueorfalsewithout quotation marks. Usefalsewhen additional text should not be allowed; omitting the field defaults totrue.
Reference text must preserve the literal transcription
- Explanation: A text entry lacks a string-valued
textfield. This check validates the value's type, not its accuracy against the reference. - Solution: Provide the exact wording as a quoted JSON string, then verify it visually against the reference. Do not use a description of the wording in place of the transcription.
Invalid JSON or unsupported plan fields
- Explanation: The arguments must be readable by the tool's argument handling, and plan validation checks supported field names. The supplied context does not show the exact error messages for malformed JSON or unexpected plan keys.
- Solution: Use valid JSON with double-quoted keys and strings and no trailing commas. Place the specification under
planand use the documented plan fields:source,fps,frames,cut_frames,texts,fonts,shots,allow_extra_text, andnotes.
Reference-file access or save failure
- Explanation: The operation must resolve and read the reference file, compute its fingerprint, and write into the project directory. An unavailable file or insufficient filesystem permissions can prevent completion; exact messages are not supplied.
- Solution: Check that the reference path exists from the OpenKatana process's perspective, that the file is readable, and that the project directory is writable. In a container or remote installation, use a path available inside that environment rather than only on your local computer.
Save a timeline before auditing
- Explanation: This message comes from the separate audit operation, not from saving the reference plan. It means the project does not yet have a saved timeline to compare with the specification.
- Solution: Save the intended timeline in the same project, then run the audit. Do not interpret a successful reference-plan save as confirmation that a timeline exists or matches.
