OpenKatana · Plan music edit:
OpenKatana_plan_music_edit helps you turn a music track into a practical starting point for a rhythm-driven edit. It analyzes the music and plans cuts around the detected beat grid, adjusting the editing rhythm to quieter, medium-level, and louder sections. Automatic pacing chooses among one-, two-, four-, and eight-beat intervals, aiming for shots of at least two seconds in quiet sections, one second in medium-level sections, and half a second in loud sections. It can also suggest a brief burst of half-beat cuts after a qualifying drop, along with visual accents and sound cues such as a white flash, camera punch, camera shake, riser, impact, or whoosh. When suitable project assets are supplied, it can prepare a draft timeline with clips assigned in order. This is a planning aid rather than a finished edit: you still choose the best imagery, review the musical timing, and decide which treatments to apply. Nothing is saved by this operation.
OpenKatana · Plan music edit Input Parameters:
project_id
A required STRING identifying the OpenKatana project in which the planning operation takes place. The tool resolves this project before analyzing the music, so you should supply the identifier of an existing, accessible project. This project context is particularly important when requesting a draft timeline using project assets or when the music track is already part of the project. The supplied node interface does not show a default value, allowed identifier format, or minimum or maximum string length.
arguments
A required STRING containing the tool-call arguments, normally expressed as a JSON object. This is where you supply the music source and planning settings; these settings are not separate node sockets. The underlying operation requires source and supports asset_ids, start, duration, fps, width, height, pace, min_shot, and burst. For example, {"source": "/path/to/music.wav", "duration": 30, "fps": 30, "pace": "auto", "burst": true} requests a 30-second analysis with automatic pacing, provided the source can be resolved by OpenKatana. The node interface does not expose a default string or string-length limits. Separately, the underlying operation defines these setting defaults and limits: asset_ids defaults to no asset list; start defaults to 0 seconds and must be at least 0; duration defaults to no explicit duration and, when supplied, must be between 1 and 1800 seconds; fps defaults to 30 and accepts 1–120; width defaults to 1080 and height to 1920, with each requiring an integer between 16 and 7680; pace defaults to auto and also accepts bar, two, beat, and half, corresponding to four, two, one, and half a beat; min_shot defaults to 0.15 seconds and accepts 0.05–10 seconds; and burst defaults to true. These settings control the analyzed passage, editing rhythm, frame timing, and optional draft-timeline dimensions. Supplying asset_ids allows the operation to assign clips in order to a draft timeline, and the music track is included when it exists in the project.
after
An optional STRING accepted by the shared node execution interface. The supplied implementation receives this value but does not explicitly use it when constructing the planning arguments or invoking the tool. Consequently, the provided code does not establish any effect on beat detection, cut timing, timeline creation, or execution order. No default string, supported values, or minimum or maximum length is shown. You can leave it unconnected for the planning configuration described here; do not use it as a substitute for the music settings in arguments.
OpenKatana · Plan music edit Output Parameters:
result_json
A STRING containing the serialized response from the OpenKatana tool call. The operation is intended to return the music analysis and a beat-aligned editing plan, with an optional draft timeline when assets are provided. The supplied planning code confirms plan fields named cuts, shots, frames, and suggestions: these describe proposed cut points, shot spans, the total planned frame count, and suggested accents or cues. Shot boundaries use frame indices such as f0 and f1; suggestion timing can use at_frame, while a camera-punch suggestion uses an at time in seconds relative to the beginning of its containing shot. Suggestions can include a two-frame white special at a drop, camera shake on the drop shot, camera punch on downbeats in loud sections, and audio cues around drops or section changes. Treat these as recommendations to review, not proof that effects have been applied or a project has been saved. The visible code does not show the complete response wrapper or the exact top-level arrangement of the returned JSON, so inspect the response before building downstream logic around particular JSON paths.
OpenKatana · Plan music edit Usage Tips:
- Start with
"pace": "auto"to let the edit respond to changes in musical intensity. At 120 BPM, its duration thresholds correspond to four-beat shots in quiet sections, two-beat shots in medium-level sections, and one-beat shots in loud sections, before other planning constraints are considered. - Use
"pace": "bar"for a steadier four-beat rhythm,"pace": "two"for two-beat intervals,"pace": "beat"for a more active edit, or"pace": "half"for half-beat intervals. These settings describe musical spacing, not a fixed number of seconds. - Keep
"burst": trueif you want extra energy immediately after a detected drop. A qualifying drop is a level increase of at least 4 dB into a loud section, and the burst targets half-beat cuts during its first bar. Set"burst": falsewhen you prefer a more restrained transition. - Increase
min_shotwhen you need more time to read titles, appreciate detailed artwork, or recognize a subject. This setting enforces minimum spacing between planned cuts; it is not the same as choosing a musical pace. - Set
fpsto match your intended edit before reviewing frame-based timing. For an optional draft timeline, setwidthandheightto your intended canvas size; the underlying defaults are 1080 by 1920. - Use
startanddurationto test a particular passage, such as a chorus or drop, before planning a longer edit. For example,"start": 30, "duration": 20selects a passage beginning 30 seconds into the source. - Supply
asset_idsin your preferred clip order when requesting a draft timeline. Clip assignment follows the supplied order, so you should still review whether each image or video suits its musical moment. - Listen to the track while checking the proposed cuts. The operation explicitly advises checking the detected beat grid before committing, and the analysis code recognizes that half-time or double-time tempo interpretations can be ambiguous.
- Review suggestions separately from the cut plan. A flash, shake, punch, or sound cue may strengthen a particular moment, but it is a creative recommendation rather than a requirement.
OpenKatana · Plan music edit Common Errors and Solutions:
pace: use auto, bar, two, beat, half
- Explanation: This validation error occurs when the pace setting is neither
autonor one of the supported fixed musical intervals. - Solution: Use exactly
"auto","bar","two","beat", or"half"insidearguments. Avoid alternatives such as"fast"or"4 beats".
unexpected inputs: ...
- Explanation: The node explicitly raises this error if it receives additional execution fields that are not declared by its interface. Planning settings such as
fpsandpaceare not separate inputs on this node. - Solution: Use only the exposed
project_id,arguments, and optionalafterinputs. Place supported planning settings inside the JSON object supplied througharguments.
Invalid arguments JSON or missing source
- Explanation: The exact parsing error is not shown in the supplied code, but the operation needs tool arguments and a required
sourcevalue. Malformed JSON or an omitted music source prevents a valid planning request. - Solution: Use a JSON object with double-quoted property names and strings, no trailing commas, and lowercase JSON booleans such as
true. Include a validsource, for example{"source": "/path/to/music.wav", "pace": "auto"}.
Project or music source cannot be resolved
- Explanation: The exact error text is not provided, but the operation resolves the project and source before analyzing the track. An incorrect project identifier, unavailable source, or unreadable audio can stop planning.
- Solution: Verify that
project_ididentifies an accessible project and thatsourcerefers to audio available to the OpenKatana environment. If you use a file path, check access from the environment running OpenKatana rather than only from your local computer.
start or duration fails validation
- Explanation: The supplied validation requires
startto be a number at least 0 and an explicitly supplieddurationto be between 1 and 1800 seconds. The exact validation message is not shown. - Solution: Enter numeric values in seconds, such as
"start": 0, "duration": 30. Do not include units in the value, and omitdurationif you do not want to specify it explicitly.
fps or min_shot fails validation
- Explanation: The operation accepts
fpsfrom 1 to 120 andmin_shotfrom 0.05 to 10 seconds. Values outside these ranges, or values supplied as unsuitable types, can fail validation; the exact error wording is not provided. - Solution: Use numeric values within the supported ranges, such as
"fps": 30, "min_shot": 0.15. Remember thatmin_shotis measured in seconds, not frames.
width or height fails validation
- Explanation: Both canvas dimensions must be integers between 16 and 7680. Decimal dimensions, text values, or values outside this range can fail validation; the exact message is not shown.
- Solution: Enter whole-number pixel dimensions, such as
"width": 1080, "height": 1920. Use numbers without quotation marks or apxsuffix.
Cuts do not match the rhythm you expected
- Explanation: This is a planning-quality issue rather than a confirmed exception message. The detected beat grid can differ from the rhythm you hear, including half-time or double-time interpretations, and minimum shot spacing can limit how closely rapid cuts are placed.
- Solution: Listen against the proposed cut points, review the returned tempo information where available, and try a different supported
pace. Check whethermin_shotis too large for your intended rhythm, and manually refine the plan before committing.
No draft timeline, or no project changes after execution
- Explanation: This is not necessarily an error. A draft timeline is conditional on supplying assets, and the operation explicitly does not save anything. Suggested effects and cues are also not equivalent to applied edits.
- Solution: Supply suitable project
asset_idsif you need a draft timeline, then inspectresult_json. Use a separate editing or saving step to apply and persist the plan.
