split_item
Cut one or more timeline items at given frame positions. One call can split many items, each at one or many frames.
When to use
Cut a clip into pieces while preserving its source mapping, fades, effects, transitions, and markers. Splitting does not change which spoken content plays — the same media bytes play end-to-end across the resulting pieces.
Use this for physical clip management: preparing a transition, isolating a piece for visual treatment, splitting around an effect boundary, or making manual timeline organization easier while the content still plays the same.
For trimming (shortening one edge), prefer edit_item updates on durationInFrames + the source-offset field. Use split_item when you actually need two or more pieces.
When NOT to use
Do not use split_item for transcript-based editing: clipping/highlight extraction, "cut slices", "keep the part about X", deleting a sentence, removing a retake, or making a short version based on what the speaker says. Do not take frames from find_transcript, split at those frames, and delete pieces to select spoken content. Use Script instead: read_script → edit timeline.md → apply_script.
Body shape
{"splits": [{"id": "...", "atFrame": 90}, {"id": "...", "atFrames": [60, 120, 180]}]}
Each entry:
id: timeline item id (short prefix frompreview_timelineaccepted).atFrame: single timeline-frame cut position.atFrames: multiple cut positions; the item is cut into N+1 pieces.
Both atFrame and atFrames accept timeline frames (not source seconds). All cut frames must lie strictly inside the item (from < cut < from + durationInFrames).
What survives the cut
Source offset — each piece keeps the correct
sourceStartFromInSecondsslice of the source media, accounting forplaybackRate.Fades —
fadeIn/audioFadeInstays on the first piece only;fadeOut/audioFadeOutstays on the last piece only. Middle pieces have all fades zeroed.Effects — clip-anchored effects follow the resulting piece and split at cut points when necessary.
Transitions — a transition where the original item was the outgoing side now points at the last piece; incoming-side transitions point at the first piece.
Adjustment-track effects keep their absolute timeline range unchanged.
Markers — clip markers move to whichever piece contains them; item-local markers have their
fromFramere-anchored.
Constraints
Cannot split
effectortransitionitems. Useedit_itemto delete those.Canonical caption Programs are timeline-wide subtitle containers and cannot be split into clips. Regular caption clips still support frame cuts. To split a caption Card at word boundaries, call
read_captions {"words":true}for its Card id, current revision, and timed word token ids, thenedit_captionswith top-levelaction="split_card"andjsoncontainingcardId,revision, andbeforeWordKey(orbeforeWordKeys). This does not turn arbitrary frame cuts into word boundaries or hide a time range.A single
split_itemcall may not list the sameidtwice. Combine cuts for one item into a singleatFramesarray.Locked tracks reject splits with a clear error.
Return
{"splits": [{"itemId": "<original prefix>", "type": "video", "newIds": ["<piece1>", "<piece2>", ...]}, ...]}
The original item id is deleted after the call. Subsequent edits should reference the returned newIds.
Examples
Single cut on one item:
{"splits": [{"id": "abc123", "atFrame": 150}]}Three cuts on one item (4 pieces):
{"splits": [{"id": "abc123", "atFrames": [60, 120, 180]}]}Cut two different items in one call:
{"splits": [{"id": "abc123", "atFrame": 60}, {"id": "def456", "atFrames": [30, 90]}]}
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"json": "<json>"
},
"name": "split_item"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| json | Yes | {"splits":[{"id":"...","atFrame":150}]} or {"splits":[{"id":"...","atFrames":[60,120]}]} | |
| projectId | No | Project for this call (full ID or unambiguous prefix). Explicit-timeline calls never change the target of later calls; legacy project selection applies otherwise. | |
| timelineId | No | Timeline id/prefix (from manage_timelines list) holding every listed item. Edits that timeline without switching the active timeline; defaults to the active timeline. |