OpenKatana · Fill storyboard:
OpenKatana_fill_storyboard replaces storyboard placeholder slates with media that you have already imported into an OpenKatana project, helping you turn a planned sequence of shot briefs into an assembled edit. It works with an existing storyboard whose slots define shot timing, duration, subject, camera direction, and creative role, such as a hook, burst, or outro. You choose which imported asset should occupy each available slot and, for video footage, where playback should begin within that asset. This lets you build the sequence progressively or fill several slots together while retaining the storyboard’s planned timing. The supplied tests demonstrate replacement with both video clips and still images, rejection of video footage that is too short, and tracking of remaining gaps. This node assembles existing media; it does not generate new images or video to satisfy the shot briefs.
OpenKatana · Fill storyboard Input Parameters:
project_id
A required STRING identifying the OpenKatana project in which the storyboard and imported assets are located. This establishes the project context for the operation, so you should use the project containing the storyboard you want to fill rather than a project name or media filename unless that is its actual identifier. Keeping the storyboard and asset references within the correct project is essential for locating the intended material. The provided node interface does not specify a default value, a minimum or maximum length, or a list of allowed identifiers.
arguments
A required STRING carrying the tool arguments as JSON text. The underlying operation accepts a required storyboard_id and an optional fills list; these are entries inside this text, not separate node inputs. Each fill entry identifies a storyboard slot with slot, an imported asset with asset_id, and optionally a source starting frame with srcf. For example, {"storyboard_id":"your_storyboard_id","fills":[`{"slot":"C01","asset_id":"your_asset_id","srcf":10}`]} requests replacement of slot C01 using the referenced asset starting at source frame 10. The source frame selects a position within the footage, not a time in seconds or a position on the storyboard timeline. The tests show that omitting srcf is supported, although the supplied excerpt does not explicitly establish its default value. The underlying method declares fills=None as its default, but the behavior of an omitted or empty fill list is not shown; provide an explicit list when you want to replace slots. No default text, size limits, or numeric bounds are specified for this node input.
after
An optional STRING accepted by the node’s execution method. Its Python default is None, meaning it can be left unconnected. In the supplied implementation, the value is not read or forwarded into the tool arguments, so it does not select a storyboard, choose footage, or change the fill operation. Although an optional connection may be useful within a broader workflow, no additional sequencing behavior is established by the supplied code. No allowed values, minimum or maximum length, or interface-level text default are shown.
OpenKatana · Fill storyboard Output Parameters:
result_json
A STRING containing the tool response formatted by the node’s response helper. Treat it as a textual response to inspect or pass to a compatible JSON-processing step, not as an image, video, or directly viewable timeline. The underlying fill API is declared to return a dictionary, but its implementation and the response helper are not included, so the exact JSON fields and wrapping cannot be guaranteed from the supplied context. The storyboard’s provided status-reporting function distinguishes FILLED from a message beginning with GAPS storyboard: and reports the total slot count and remaining gaps. Where such status information appears in the response, FILLED means no active placeholder gaps remain, while a gaps report identifies slots still awaiting replacement. Gap details can include slot identifiers, frame and time boundaries, required duration, and creative brief information.
OpenKatana · Fill storyboard Usage Tips:
- Plan the storyboard first and retain its returned
storyboard_idand slot list. Use the exact slot identifiers from that list; generated identifiers follow a pattern such asC01andC02. - Import your footage or still images before filling slots, then use their actual asset identifiers in
arguments. Anasset_idrefers to an imported asset, not directly to a file path. - Match each asset to the slot’s subject, shot description, camera brief, and creative role. These details help you choose appropriate footage, but the supplied context does not establish automatic visual checking against the brief.
- Check
needs_sbefore selecting video footage, and leave enough usable material after the chosensrcf. A long clip can still be unsuitable if the requested starting frame is too close to its end. - Use frame counts rather than seconds for
srcf. For example, frame 60 corresponds to approximately two seconds into footage running at 30 frames per second. - Fill a single slot first when checking your asset references and source offset, then supply multiple fill entries together once those references are confirmed. The implementation and tests support iterating over a list of replacements.
- Use still images when a shot should hold on a single composition. The tests demonstrate that a one-frame image asset can fill a storyboard slot; do not assume a one-frame video asset will behave the same way.
- Recheck remaining gaps before submitting another batch. Already-filled slots are rejected, and the status logic treats the saved timeline as authoritative: a placeholder removed manually is no longer counted as a live gap, even if its storyboard record still says
gap.
OpenKatana · Fill storyboard Common Errors and Solutions:
Unknown storyboard 'your_storyboard_id'
- Explanation: This error is explicitly raised when the storyboard loader cannot find the storyboard JSON file under the project root. The identifier may be incorrect, or you may be operating in a different project.
- Solution: Copy the
storyboard_idreturned by the planning operation and confirm thatproject_ididentifies the same project. If the storyboard files are no longer available, create a new storyboard and use its new identifier.
Video footage is too short for the slot
- Explanation: This is a descriptive error condition, not a confirmed literal message. The tests establish that insufficient video footage raises
ContractError. The selected asset must provide enough footage for the slot from the requested source position. - Solution: Choose a longer asset or move
srcfearlier. Compare the slot’s required duration with the footage remaining after your chosen starting frame.
Storyboard slot is already filled
- Explanation: This is a descriptive error condition; the exact message is not supplied. A test confirms that attempting to fill a previously filled slot raises
ContractError. - Solution: Submit only slots that still have active placeholders. To change an already assembled shot, use an appropriate timeline-editing operation rather than assuming this node will overwrite it.
Invalid JSON in arguments
- Explanation: The exact parsing error is not shown, but incorrectly formatted argument text can prevent the request from reaching the fill operation. Common mistakes include single quotes, missing commas, and unmatched brackets.
- Solution: Use a valid JSON object with double-quoted names and string values. Start with
{"storyboard_id":"your_storyboard_id","fills":[`{"slot":"C01","asset_id":"your_asset_id"}`]}and replace the example identifiers with real ones.
Missing or incorrect storyboard, slot, or asset reference
- Explanation: This is a troubleshooting category rather than a quoted error message. The fill request needs references to the intended storyboard, its slots, and imported assets. The supplied excerpts do not show the exact validation messages for missing or invalid slot and asset references.
- Solution: Include
storyboard_idinarguments, copy slot identifiers from that storyboard’s slot list, and copy asset identifiers from the project’s imported assets. Check spelling and capitalization rather than guessing identifiers.
unexpected inputs: ...
- Explanation: This message is explicitly raised by the node wrapper when unsupported named execution fields are supplied. The authoritative node interface exposes only
project_id,arguments, and optionalafter; tool-level entries are not additional node sockets. - Solution: Put
storyboard_idandfillsinside the JSON text supplied toarguments. Remove unsupported extra named inputs from custom calls to the node.
