edit timeline
Mutate a timeline with a list of typed operations applied as one transaction: add, move, trim, split, slip and remove clips, ripple and close gaps, speed, clip properties, keyframes and camera moves, tracks, text, markers, links, caption settings, dimensions and frame rate. Returns what changed, the new revision and check: check_timeline’s structure findings for the saved cut; sound only by check_timeline. Clips and tracks are named by their ids. Free.
Authorizations
An API key (es_live_…) from Settings, under API keys, or an OAuth access token.
Headers
Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.
The workspace this one call acts in, when it is not the default: for a key or a connected agent, one of the workspaces the user allowed it.
Body
The timeline id.
Operations, by type. Frames count at the timeline's fps, and every frame field has a seconds twin (from_seconds, duration_seconds, trim_start_seconds, to_seconds, delta_seconds, at_seconds), one or the other. Clips: addClip {trackId, ref | timeline_id | clip, id?, from?, source? [start_s, end_s] (edges move to the quiet between the file's words; snap: false keeps them), durationInFrames?, trimStart?} (from left out: after the last clip on that track, so adds build a cut in order; one that would overlap another lands on a fresh track above); insertClip and overwriteClip (the fields of addClip; insert pushes what follows right on every track, overwrite clears the span on that track); replaceSource {clipId, ref}; removeClip {clipId}; rippleDelete {clipId}; rippleDeleteRange {from, durationInFrames, trackIds?}; overwriteRange {trackIds, from, durationInFrames}; rippleInsert {from, deltaFrames, trackIds?}; closeGaps {trackIds?, from?}; closeGap {trackId, atFrame}; moveClip {clipId, toFrame, toTrackId?}; trimClip {clipId, edge, deltaFrames, ripple?}; slipClip {clipId, deltaFrames}; splitClip {clipId, atFrame, newClipId?}; setSpeed {clipId, speed}; updateClip {clipId | trackId (every clip on it), patch} (volume, opacity, holdFrames (a frame hold, 2 for on twos, up to 6), fadeIn/OutFrames, transform, grade, effects, masks, transitionIn/Out, objectFit, placeholder, category, label, the text fields; grade and effects replace whole); setKeyframes {clipId, property, keyframes: [{frame | at_seconds, value, interp?}]} (position, scale, rotation, opacity, crop, focus, volume, fx.; the list replaces that track); cameraMove {clipId | trackId, move} (zoom-in, zoom-out, pan-right, pan-left, slow-push, slow-pull, reveal, punch-in, snap-zoom, handheld, impact, drift, rise, roll-in, none); linkClips {clipIdA, clipIdB, linkId}; unlinkClips {clipId}; detachAudio {clipId}; reattachAudio {clipId}. Tracks (a fresh timeline has one visual track, id visual-main): addTrack {track: {kind: visual | audio, index, id?, clips?}}; removeTrack {trackId}; reorderTrack {trackId, index} (a track already at the index moves up one, with those above); updateTrack {trackId, patch: {muted?, hidden?, locked?, height?}}. Markers: addMarker {marker: {from, label, kind: chapter | note, body?, durationInFrames?, id?}}; updateMarker {markerId, patch}; removeMarker {markerId}. Document: setCaptionSettings {settings}; setAspectRatio {ratio}; setDimensions {width, height}; setFrameRate {fps}; setMeta {patch: {title?, note?, platforms?}} (platforms: where it goes, by platform name, drawn under its post). Every field with its units and defaults, hand-built clips, effects, grade, masks, transitions, text and keyframes: skill-timeline-operations, read with manage_skills get.
1 - 1000 elementsThe revision get_timeline returned. A stale one fails with revision_conflict instead of applying; so does no revision once a user edited the timeline in the app since this connection last read it.
Optional: one sentence shown to the user beside this action.
600