timeline_id or canvas_id.
A project is a timeline that holds clips cut from one recording with cut_clips. Each clip is a timeline of its own with a parent_id, and edit_clips and render_clips work on a set of them.
Reading and writing
get_timeline or get_canvas returns the document with a stable id for every clip, track or layer, and its revision. A read stops at about 60,000 characters, says so in cut_short, and can continue from next_cursor. Ranges, tracks, slides and fields narrow a read. response_format: "detailed" returns every property a clip or layer can be set to, so an existing look can be matched exactly instead of guessed.
edit_timeline and edit_canvas take a list of typed operations that apply as one transaction. Every operation is checked before any is applied. A bad one is named by its position, and nothing is written. The response says what changed and includes the new revision. The full list of operations is in two skills, Timeline operations and Canvas operations, available through manage_skills.
Ids are returned in a short form and are accepted back in that form.
Revisions
A write acceptsif_revision from the last read or write response. A stale revision fails with revision_conflict instead of overwriting another editor’s change, whether that editor is a user or another agent. A write with no revision fails with the same code once a user has edited the document in the app since this connection last read it. A fresh document nobody has edited accepts a write without one. Documents are live: a user can have one open, and the next agent reads whatever state it was left in.
undo returns a document to how it was before its last edit, or restores any saved revision, forward or back. A timeline keeps 50 revisions, a canvas 20. An edit made by someone else is named in the result and kept, unless a revision is named explicitly.
Words on a clip
Words on a clip come from transcription. An empty transcript on uploaded speech means the file has not been transcribed, not that it is silent.transcribe_media with timeline_id gives the clips their words, and captions, get_transcript and remove_words read from there. remove_words shifts word indices, so indices read before a cut no longer match, and get_transcript returns the new ones.
When speech is both cleaned and cut, clean_audio goes before any cut, because the cleaned file replaces the clip’s whole media and the transcribed words stay with the original file; remove_silence and remove_words each shift the word positions, so the transcript is re-read between them.
Keyframe tracks
A punch-in, a reframe and music ducking (auto_zoom, auto_reframe, duck_music) each write a keyframe track, replacing what was on it. setKeyframes on edit_timeline sets a single property by hand. On updateClip, grade and effects are replaced as a whole.
Motion graphics
A motion graphic is code drawn on its own track over the clips below it: a title, a lower third, a chart, kinetic type or a whole animated scene.compose_motion places one written as Remotion JSX or as a HyperFrames HTML document, which is HTML and CSS animated by a GSAP timeline. Both are drawn in the app’s preview and rendered with the timeline, in the cloud or through the desktop app, with nothing to install. A graphic is revised in place with clip_id, and the Motion graphics skill holds the rules for each format.
Checking and rendering
check_timelineis free, except the first time it measures a file’s sound, which uses cloud processing;audio: falseskips that. It reports black stretches, buried clips, trims past the end of a file, missing media, muted sound, unreadable text and the loudness of the speech.inspect_timelineandinspect_canvasrender real frames of the composite, which is how an edit can be checked.render_timelineexports an mp4, a transparent WebM, a GIF, or an mp3 or wav.render_timelinereturns a job.render_canvassaves the images or the PDF to the library within the call, and a PDF over twelve pages becomes a job. The item each one produces is the finished file. Through the desktop app, a render runs on that computer for free, at any length and resolution. Elsewhere,inspect_timeline,inspect_canvasand every render use cloud processing, and a render is charged what it actually cost.
setFrameRate changes the frame rate and keeps every clip at the same second. Generation settings are independent of these.
Templates
manage_timelines and manage_canvases can save a finished document as a template, and get_templates lists it. A timeline saved as a template turns its picture clips into empty slots, and manage_timelines create with from_template and fill copies it with new files in one call. A canvas saved as a template is copied with manage_canvases create from_canvas, and its image layers are the parts meant to be replaced. get_templates also includes the catalogue shown in the app’s Templates panel: motion graphics, caption templates, camera moves, filters and fonts, each with the exact call that uses it. compose_motion save_as and captions generate save_template_as save a graphic or a caption look for the workspace; manage_templates renames or deletes one.
