OpenKatana · Plan storyboard:
OpenKatana_plan_storyboard turns a music-based cut plan into a practical visual storyboard, helping you decide what footage or generated imagery you need before assembling a finished edit. It organizes the planned sequence into timed slots, assigns shot briefs and camera guidance, and creates placeholder slate images so you can inspect the structure before adding real visuals. Shot roles follow the musical structure and editing plan, including opening hooks, drop entrances, bursts, and an outro where applicable. Repeated roles cycle through available shot suggestions to introduce variety. This is a planning tool rather than an image or video generator: it establishes the timing, creative direction, and missing-footage checklist for a music-driven sequence, then supports a later workflow in which you replace the placeholders with imported assets.
OpenKatana · Plan storyboard Input Parameters:
project_id
A required STRING identifying the OpenKatana project in which you want to create the storyboard. The planning operation uses the project’s storage location for storyboard records and placeholder images, and it can save the resulting timeline into that project when requested. Use the identifier of the project you intend to edit, rather than a music filename or storyboard identifier. The supplied node interface does not specify a default value, permitted identifier format, minimum length, or maximum length.
arguments
A required STRING carrying the tool arguments as JSON text. This is where you configure the storyboard operation; the underlying API parameters are not separate sockets on this node. The API signature provides source as a required string, followed by start with a default of 0, duration with a default of None, fps with a default of 30, width with a default of 1080, height with a default of 1920, pace with a default of "auto", subject with a default of "the main subject", camera with a default of None, and save with a default of False. The source identifies the media to plan from; start and duration describe the requested source interval, although the supplied excerpt does not show how an omitted duration is resolved. The frame rate controls the relationship between frame positions and seconds, while width and height determine the storyboard canvas and slate dimensions. Subject supplies the subject text for every shot brief. A provided camera value overrides role-based camera guidance; otherwise, the storyboard chooses camera guidance for each role. Pace is an API planning setting, but only its default is shown, so additional accepted values cannot be confirmed. Save controls whether the generated timeline is saved as the project edit; storyboard records and slate files are still written during planning when save is false. For example, you can supply {"source":"/path/to/music.wav","subject":"a skater","fps":30,"width":1080,"height":1920,"save":false}. No default JSON string, numeric limits, or complete option lists are specified by the node interface.
after
An optional STRING accepted by the node’s execution method, with a Python default of None. In the supplied implementation, this value is not added to the tool arguments or passed into the planning call, so it does not directly configure the storyboard’s timing, creative briefs, or save behavior. You should not use it to provide a source, a start time, or additional JSON settings. Any broader workflow-ordering behavior associated with this socket is not shown in the supplied code. No string default, minimum length, maximum length, or supported value list is declared in the visible interface.
OpenKatana · Plan storyboard Output Parameters:
result_json
A STRING containing the serialized tool response, allowing you to inspect the storyboard plan or pass its information to subsequent operations. The successful planning API returns a storyboard_id for later reference; a slots list containing the shot briefs; bpm from the music analysis; storyboard verdict information; the generated timeline; a saved value reporting the save result when saving was requested, or None otherwise; slates containing paths to the first four placeholder images at most; and explanatory notes. Each slot includes an identifier such as C01, start and end frame positions, start and end times in seconds, the required duration in needs_s, musical part, shot role, shot suggestion, subject, camera guidance, status, and asset identifier. Newly planned slots have status "gap" and no assigned asset. The timeline contains canvas settings, placeholder clip definitions, and timed shots; each placeholder is a single slate image held across its assigned shot. An initial verdict beginning with GAPS storyboard: means that footage still needs to be supplied, not that planning failed. The underlying API response passes through a response helper whose exact outer JSON structure is not included in the supplied context, so any additional wrapper fields cannot be confirmed.
OpenKatana · Plan storyboard Usage Tips:
- Start with a descriptive subject in
arguments, such as"a skater performing tricks in a concrete skatepark". The same subject text is attached to each slot, helping you keep the planned visuals consistent. - Leave
cameraomitted when you want camera suggestions to vary by shot role. Supply it when you deliberately want a shared camera direction, understanding that this replaces the role-specific guidance. - Match
fps,width, andheightto your intended edit before planning. The API defaults are 30 fps and a 1080 × 1920 portrait canvas; a landscape project can instead use dimensions such as 1920 × 1080. - Use
startanddurationto request the passage you want to storyboard rather than assuming every planning task must cover the entire source. The supplied signature does not establish valid ranges or the exact behavior of an omitted duration. - Use
"save":falsewhile reviewing a plan to avoid saving its timeline as the project edit. This does not make the operation file-free: the storyboard record and placeholder images are still created. - Review each slot’s
needs_sbefore choosing or generating footage. It tells you how many seconds the slot needs, making it easier to avoid selecting clips that are too short. - Treat the returned
slateslist as a preview, not a complete inventory. Only the first four slate paths are returned there, while the storyboard creates a slate for every slot. - Import your footage and then use the separate
fill_storyboardoperation with the returned storyboard identifier and slot assignments. Filling replaces the planned placeholders; planning alone does not produce finished visual footage. - Check the returned notes for audio availability. The implementation explicitly warns when music is outside the project and must be imported to hear it in the storyboard.
OpenKatana · Plan storyboard Common Errors and Solutions:
unexpected inputs: ...
- Explanation: This exact error prefix appears in the node wrapper when execution receives fields that are not declared as typed inputs. The authoritative interface for this node exposes only
project_id,arguments, and optionalafter; API settings such assourceandfpsare not separate node sockets. - Solution: Put storyboard settings inside the JSON text supplied to
arguments. If an older workflow or custom integration sends extra fields directly, update it to match the loaded node interface.
Invalid JSON in arguments — exact error text not shown
- Explanation: The node processes
argumentsthrough argument-handling helpers, but their parsing errors are not included in the supplied code. Malformed JSON, such as single-quoted property names or a trailing comma, can prevent the settings from being read. - Solution: Supply a valid JSON object with double-quoted keys and strings. Use JSON values such as
falseandnull, rather than Python spellings such asFalseandNone.
Missing required source — exact error text not shown
- Explanation: The underlying planning API requires
sourceand has no default for it. Providing a project identifier alone does not identify the music or source media to analyze. - Solution: Include a valid
"source"entry inargumentsand confirm that it identifies media accessible to the OpenKatana runtime. The supplied excerpt does not establish all accepted source formats.
GAPS storyboard: N of N slots still to fill
- Explanation: This is a normal storyboard verdict, not a planning exception. Newly created slots contain placeholder slates, and the timeline can also report a
storyboard_gapswarning until those slots are filled. - Solution: Review the briefs, import suitable assets, and fill the slots with the separate
fill_storyboardoperation. Check the remaining-gap count as you work; the tested fully populated storyboard verdict isFILLED.
The music is outside the project: import it to hear it in the storyboard.
- Explanation: This is an informational note returned when the planning call has no project audio to attach. A storyboard may still be created, but the planned timeline will not include that music for playback.
- Solution: Import the music into the project and use the imported source for a subsequent planning operation if you want the storyboard timeline to include audio.
Unknown storyboard '...'
- Explanation: This exact error pattern belongs to storyboard loading, which can occur during later storyboard operations rather than initial planning. It means the expected storyboard record cannot be found in the project.
- Solution: Use the
storyboard_idreturned by the successful planning call with the same project. Do not substitute a slot identifier such asC01, and verify that the project’s storyboard files have not been moved or deleted.
