Cue GitHub (1)
Docs · Agent tool reference

Agent tool reference

Every tool an agent can call, 172 in all, grouped as in the app's source. The same list is served to MCP clients and to the agents in the Agent panel; the editor itself uses the same actions.

Times are in milliseconds. Positions on the frame are shares of the canvas from 0 to 1. Ids come from get_state and get_timeline (tracks like V1, clips c_…, media a_…, markers m_…). Agents are told to read get_guide once before editing. To try a tool from a terminal, clone the repository and run:

node scripts/mcp-call.mjs list

This page is generated from electron/control/contract.ts. Nested object inputs (clip patches, styles, settings) are described in each tool's text.

Overview

cut_out

Cut the subject (people, objects) out of a picture, or of a video frame at atMs, into a new image with a transparent background, a paper-white outline (px, 0 for none) and a soft shadow (0–1) — the collage cut-outs of explainer videos. Returns the new media; with trackId and startMs it is placed too. Turn it slightly (transform.rotation -3…3) and add a small wiggle for the hand-made look. macOS only.

  • assetIdstringrequired
  • atMsnumberoptional
  • outlinenumberoptional
  • shadownumberoptional
  • trackIdstringoptional
  • startMsnumberoptional

list_playbooks

Cue's playbooks: how to work in Cue (read 'working-in-cue' first), how to match a reference video ('match-a-reference', with analyze_reference), a complete worked example ('example-why-we-say-ok'), editing craft, premium motion design, and recognisable styles (Vox explainer, map documentary, flat vector, tech review, captions talking head, product film, true crime, video essay, news, beat montage, podcast clip, product explainer, vlog) taken apart into techniques with Cue's tools and numbers. Read the relevant one with get_playbook before building a video in a style.

  • category"workflow" | "craft" | "style" | "example"optional

get_playbook

A playbook's full text (markdown), by id from list_playbooks.

  • idstringrequired

wait_for

Wait for a long call to finish. Calls that take longer than about 45 seconds (exports, voiceovers, transcripts) reply with {status: 'running', callId, progress} instead of their result; pass that callId here to wait again (up to about 45 seconds per call) and get the result. Never start the same work twice.

  • callIdstringrequired
  • waitMsnumberoptional

get_guide

How Cue works and how to edit with these tools: concepts, units, track order, workflows and which tool does what. Read it once before editing. topic 'motion' is the guide to designing motion graphics (the spec format, design rules and patterns); read it before create_motion_graphic with a spec.

  • topic"editing" | "motion"default "editing"

list_motion_templates

Cue's motion graphic templates (lower thirds, titles, kinetic words, bar/donut/line charts, big numbers, callouts, timelines, checklists, quotes, a subscribe reminder, a chapter progress bar, a route map, editorial annotations, device frames with see-through screens for footage (retro TV, laptop, phone, polaroid, film strip, taped photo), and transitions that cover a cut), each with its parameters and an example, plus the colour themes. Use one with create_motion_graphic {template, params}.

  • category"lowerthird" | "title" | "chart" | "stat" | "callout" | "list" | "quote" | "overlay" | "map" | "transition" | "annotation" | "frame"optional

create_motion_graphic

Make a motion graphic (a Lottie animation, played like video) from a template with params, or from a spec you write (see get_guide {topic: 'motion'}). It is added to the media; with trackId, startMs or atCutMs it is also placed on the timeline (on the top picture track when free there, else a new Graphics track). atCutMs centres a transition on a cut. Text and data are editable later with update_motion_graphic; look at it with render_frame. Device frames (category frame: frame-crt, frame-laptop, frame-phone, frame-polaroid, frame-film-strip, frame-photo-card) have see-through screens: the reply's regions give each screen's {name, x, y, width, height} (shares of the frame) and fit {"16:9", "4:3", "9:16"}: the {x, y, scale, crop} transform that makes a clip of that shape fill it. Put the frame on an upper track and the footage on a track below it; fit: [{clipId, region?}] applies the fit to those clips (by their media's shape) for you.

  • templatestringoptional
  • paramsobjectoptional
  • specobjectoptional
  • namestringoptional
  • trackIdstringoptional
  • startMsnumberoptional
  • durationMsnumberoptional
  • atCutMsnumberoptional
  • fitvaluerequired

update_motion_graphic

Rebuild a motion graphic made in Cue: params merge with its current ones (change a title, the data, the theme, colors); spec replaces it entirely; template switches to another template. Clips using it update; one undo step. Device frames reply with their regions again; pass fit [{clipId, region?}] to refit the footage after moving or resizing the frame.

  • assetIdstringrequired
  • paramsobjectoptional
  • specobjectoptional
  • templatestringoptional
  • fitvaluerequired

edit_motion_layer

Change one layer of a motion graphic made in Cue without rewriting its spec: layer is its name or path (see get_motion_graphic layers, e.g. 'Title' or '1.0'); patch sets spec properties of that layer (text, color, fill, size, x, y, rotation, opacity, enter, exit, keys…; null removes one); move {dx, dy} shifts it in composition pixels (lines by their points, groups with everything in them); remove deletes it. A graphic made from a template becomes its own design (the template's params stop applying). One undoable step; clips using it update. Works without the window on screen.

  • assetIdstringrequired
  • layerstringrequired
  • patchobjectoptional
  • moveobjectoptional
  • removebooleanoptional

get_motion_graphic

A motion graphic's source: the template and params it was made from, its full spec (for templates, the spec they build) and its layers (name, type, path) for edit_motion_layer. Copy and change the spec to make a new graphic in the same style.

  • assetIdstringrequired

get_state

Overview of the open project: canvas, tracks, media, script lines with take status (empty/ok/tight/over), selection and recorder. Call this first. Clips are summarised; use get_timeline for details.

No inputs.

get_timeline

Every clip (id, track, start, duration, source in-point, text, style) optionally limited to a time range.

  • fromMsnumberoptional
  • toMsnumberoptional
  • trackIdstringoptional

render_frame

Show the actual viewer image at a moment, with its PNG path. Use it to inspect framing, text and captions.

  • atMsnumberrequired

inspect_edit

Inspect the current edit in one call: sampled viewer images across a time range, active clips at each sample, and director's notes about likely issues. Returns actual images as MCP content so you can see the cut. Use get_timeline for exact clip details and render_frame to zoom in on a problem moment.

  • fromMsnumberoptional
  • toMsnumberoptional
  • sampleCountintegerdefault 4

get_activity

Recent edits with who made them (user or agent).

  • limitintegerdefault 30

Projects

list_projects

Every project in the projects overview (recent ones and those in the projects folder) with length, canvas, clip count, last change and the collection it is in (collectionId; see list_collections).

No inputs.

list_collections

Collections in the projects overview: named groups of projects, like folders (the pieces of one video — its edit, graphics made as their own projects, other versions). Each has an id, name and its project files. list_projects shows which collection each project is in.

No inputs.

create_collection

Make a collection in the projects overview, optionally with projects (their file paths) moved into it. A project is in one collection at most.

  • namestringrequired
  • projectsstring[]optional

delete_collection

Delete a collection. Its projects are not deleted: they go back to the ungrouped list.

  • idstringrequired

move_to_collection

Move projects (file paths) into a collection, out of any other; collectionId null takes them out of their collection.

  • projectsstring[]required
  • collectionIdstring | nullrequired

close_project

Save and close the open project, back to the projects overview.

No inputs.

save_project_as

Save a copy of the project (.cueproj) at a new path and switch to it. Media stays where it is.

  • pathstringrequired

add_project_media

Place another Cue project (or one of its sequences) in this one as media, like a pre-composition shared between projects: it is rendered to a video (text and graphics included) and rendered again whenever that project file changes (on opening this project, when Cue comes to the front, before export, or with refresh_project_media). With trackId it is also put on the timeline at startMs. Its media item has projectSource with the file. Long: may reply with a callId for wait_for.

  • pathstringrequired
  • sequenceIdstringoptional
  • trackIdstringoptional
  • startMsnumberoptional

refresh_project_media

Render again the projects placed as media (add_project_media) whose files changed. Returns how many were updated.

No inputs.

analyze_reference

Measure a reference video you are asked to match (a style, a creator, an ad): where its cuts are, shot lengths (median, mean, range), cuts per minute and per 10 s (where it speeds up or breathes), brightness, colourfulness and how much is black and white, its dominant colours, loudness, and a contact sheet with one frame per shot (returned as an image). Give a file path or the assetId of imported media. Use the numbers to set your pacing, grade and palette, then read the matching playbook (list_playbooks) and the 'match-a-reference' playbook. Long: may reply with a callId for wait_for.

  • filestringoptional
  • assetIdstringoptional

package_project

Package the project and every media file it uses into one .zip to share or archive (like Premiere's Project Manager): media outside the project folder is copied in, caches and history are left out, and the zip opens anywhere. trim (default true) cuts long video and audio down to the parts the edit uses plus 1 s handles, so footage from a long film stays small. readme adds a README.txt (credits, sources, how it was made). out defaults to the project's export folder. Long: may reply with a callId for wait_for.

  • outstringoptional
  • trimbooleandefault true
  • readmestringoptional

find_offline_media

Search near the project (and optionally in extra folders) for offline media that moved, and relink what is found.

  • foldersstring[]optional

import_timeline

Import an OpenTimelineIO (.otio) timeline from DaVinci Resolve, Premiere, Kdenlive and others as new tracks. Media is linked in place.

  • filestringrequired

open_project

Open a .cueproj project (or a folder containing one; older .cue.json files work too).

  • pathstringrequired

create_project

Create a project. Optionally start from a video (placed on track V1, canvas matches its size) and a voiceover script from an .srt file or a list of lines.

  • pathstringrequiredProject file or folder.
  • namestringoptional
  • videostringoptional
  • srtstringoptional
  • linesarrayoptional

set_canvas

Output size, frame rate and background colour.

  • widthintegeroptional
  • heightintegeroptional
  • fpsnumberoptional
  • backgroundstringoptional

Media and tracks

list_library_assets

Browse Cue's curated library: stock footage, original graphics, Textures (paper, kraft, cardboard, newsprint and construction-paper boards; film dust, light leak, halftone and vignette overlays) and Sound effects (whooshes, paper slaps and rustles, pop, tick, camera shutter, typewriter, riser, impacts, a title chime, room tone). category narrows it (e.g. "Textures", "Sound effects"); query searches names, descriptions and tags. Each result has its kind (video, image, audio), duration for sounds and loops, source, credit and license, and `use`: how to use it (blend, opacity, track: bottom for boards, top for overlays, audio; volume; loop; syncMs, the moment in a sound to line up with the event; and a note). Add one with import_library_asset.

  • querystringoptional
  • categorystringoptional

show_library_asset

Select a curated asset in Cue's asset gallery and return its source, license and usage notes.

  • idstringrequired

import_library_asset

Copy (or, for stock footage, download) a curated asset into the open project and import it as media. Give trackId, startMs or atMs to also place it, following its `use`: without trackId, sounds go on a free "SFX" audio track (made when needed), paper boards on a new bottom picture track (under everything: put graphics and cut-outs above it), and overlays (dust, light leak, halftone, vignette) on a new top track, with the suggested blend mode (multiply for paper over footage, screen for dust and light leaks) and opacity. atMs lines the sound's sync point up with an event (a whoosh's peak on the cut): startMs = atMs - use.syncMs. durationMs sets the length (stills default to 5 s; loops repeat back to back to fill it). blend, opacity and volume override the suggestions. To lay paper over footage instead, pass a trackId above the footage and blend "multiply". Stock footage comes from its credited source; check the license before publishing.

  • idstringrequired
  • trackIdstringoptional
  • startMsnumberoptional
  • atMsnumberoptional
  • durationMsnumberoptional
  • blendenumoptional
  • opacitynumberoptional
  • volumenumberoptional

import_media

Add video, audio, image or motion graphic files to the media library. With trackId, also place them back to back from startMs. Motion graphics are Lottie animations (.json or .lottie), the format After Effects exports with the Bodymovin or LottieFiles plug-in; they go on video tracks and list their editable text layers, colours and markers (see update_clip motion).

  • filesstring[]required
  • trackIdstringoptional
  • startMsnumberdefault 0

list_media

The media library: id, kind, name, duration, origin (import/recording/tts/generated), the line a take belongs to, bin (id and path), tags, rating (0–5), note, whether and where it is used, and technical info (codec, fps, bitrate, file size, audio channels and sample rate, recording date). filter narrows it: binId (media directly in that bin; null for media in no bin), tag, kind, unused (no timeline uses it), minRating, query (words to find in the name, tags, note or transcript).

  • filterobject | nulloptional

remove_media

Remove media items (id, or ids for several) and every clip that uses them, as one undo step.

  • idstringoptional
  • idsstring[]optional

rename_media

Rename a media item in the library (the file on disk keeps its name).

  • idstringrequired
  • namestringrequired

list_bins

The bins (folders) of the media library: id, name, parentId for sub-bins, and how many items each holds directly.

No inputs.

create_bin

Create a bin (folder) for media. parentId makes it a sub-bin of a top-level bin (bins nest one level deep). Returns the new bin's id in created.

  • namestringrequired
  • parentIdstringoptional

rename_bin

Rename a bin.

  • idstringrequired
  • namestringrequired

remove_bin

Delete a bin. Nothing is lost: its media and sub-bins move up to where the bin was (its parent, or the top level).

  • idstringrequired

move_media

File media items in a bin, or at the top level with binId null.

  • assetIdsstring[]required
  • binIdstring | nullrequired

tag_media

Tag, rate and annotate media items. add and remove are lists of tags (merged with the tags they have; case doesn't matter). rating 1–5 stars (5 is a favourite), 0 clears it. note replaces the note; an empty note clears it. Fields you leave out stay as they are.

  • assetIdsstring[]required
  • addstring[]optional
  • removestring[]optional
  • ratingintegeroptional
  • notestringoptional

list_capture_sources

What can be recorded: screens and windows (ids for record_screen), cameras and microphones, and whether macOS allows Cue to record the screen, camera and microphone (granted, denied, not-determined).

No inputs.

record_screen

Start recording a screen or window, optionally with the camera and microphone, in the editor window (a 3-2-1 countdown, then a recording bar the user can stop). Tell the user before calling. Returns once recording has started; call stop_screen_recording to finish, or it stops by itself after maxSeconds. The screen is recorded natively (ScreenCaptureKit on macOS) at full resolution. The result is imported and placed at the playhead: the screen on a free video track, the camera on the track above (as a picture-in-picture bubble when bubble is true, round with the studio look), linked together; the microphone is recorded into the screen's sound. Use pause_screen_recording to pause and resume.

  • sourceIdstringoptionalA screen or window id from list_capture_sources; omit for the main screen; 'none' records the camera alone
  • camerabooleandefault false
  • microphonebooleandefault true
  • bubblebooleandefault trueShow the camera small in the bottom-right corner (round, with the studio look)
  • maxSecondsnumberoptional
  • studiobooleandefault trueThe Recordly-style finish: the screen inset on a wallpaper with rounded corners and a shadow, the real pointer replaced by a smooth larger cursor, zooms on the clicks and a ripple on each click. All of it is ordinary clips, keyframes and zooms on their own tracks (Background, Cursor, Clicks), so it can be edited afterwards
  • wallpaper"none"optionalStudio background (default dusk)
  • autoZoombooleandefault trueStudio: zoom in where the clicks are
  • smoothCursorbooleandefault trueStudio: leave the real pointer out and draw a smooth, larger cursor
  • cursorSizenumberdefault 1Studio: cursor size (1 is about 5% of the frame height)
  • clickRipplesbooleandefault trueStudio: a ripple on each click
  • cameraIdstringoptionalA camera id from list_capture_sources (default: the system camera)
  • microphoneIdstringoptionalA microphone id from list_capture_sources (default: the system microphone)

pause_screen_recording

Pause (paused: true) or resume (paused: false) the running screen recording. Paused time is left out of the recording, the pointer track and the zooms.

  • pausedbooleanrequired

stop_screen_recording

Stop the screen or camera recording started with record_screen (or by the user), then import it and return the new media and clips.

No inputs.

add_track

Add a video, audio or text track. index 0 is the top.

  • kind"video" | "audio" | "text"required
  • namestringoptional
  • indexintegeroptional

update_track

Rename, mute, solo, lock, hide, set volume (0–2) or pan (-1 left to 1 right), mark as the voiceover track, or duck it (lower it automatically while the voiceover speaks). eq: three bands in dB (-12 to 12): low (shelf at 120 Hz: rumble, boom), mid (1.2 kHz: presence, honk), high (shelf at 8 kHz: air, hiss); bands you leave out keep their value, null makes it flat. compressor: {amount 0–1} evens out loud and quiet parts (0.3 gentle, 0.5 voice, 0.8 heavy), null turns it off. Presets: Voice is eq {low:-3, mid:2, high:3} with compressor 0.5; Music bed is eq {mid:-2} with compressor 0.3.

  • idstringrequired
  • patchobject | nullrequired

auto_mix

Level the mix in one undoable step: measures each audible track's loudness and sets track volumes so dialogue and voiceover sit at about -16 LUFS and music or background tracks about 8 dB under them, turns on ducking for music tracks, and gives the voiceover track the Voice preset (EQ and compressor) if it has no EQ yet. Tracks are told apart by the voiceover flag, their names (Music, Voice, …) and transcripts. Returns each track's measured loudness and what changed.

No inputs.

measure_loudness

Measure the loudness of the whole mix as it would be exported (EBU R128): integrated LUFS and true peak in dBTP. Nothing is changed.

No inputs.

move_track

Reorder a track (0 = top; upper video tracks draw over lower ones). Video and text tracks always stay above audio tracks.

  • idstringrequired
  • indexintegerrequired

Clip editing

add_clips

Place clips. Media clip: {type:'media', trackId, assetId, startMs, durationMs?, inMs?, speed?, volume?, fadeInMs?, fadeOutMs?, transform?}. Text clip: {type:'text', trackId, startMs, durationMs?, text, style?, animationIn?, animationOut?}.

  • clipsarrayrequired

add_text

Add a title from a template (preset): title, headline, outline, gradient, lower-third, caption, subtitle (yellow outlined), minimal, quote, label or big-number. Style and animations can be changed after with update_clip. Uses the first text track unless trackId is given.

  • textstringrequired
  • startMsnumberrequired
  • durationMsnumberdefault 3000
  • preset"title" | "headline" | "outline" | "gradient" | "lower-third" | "caption" | "subtitle" | "minimal" | "quote" | "label" | "big-number"default "title"
  • trackIdstringoptional
  • styleobjectoptional

update_clip

Change a clip: timing, in-point, speed, volume, fades, denoise (off | light: FFT filter for steady hiss and hum | voice: RNNoise speech model that removes most non-speech noise; true means light), color {brightness -1–1, contrast 0–3, saturation 0–3, temperature -1–1, lut: .cube path}, transform (x, y, scale, opacity, crop {left,top,right,bottom} as shares 0–0.45), text, style or animations. mask {shape rectangle|ellipse, x, y, width, height (shares of the picture), feather 0–1, invert} or null. key (chroma key) {color '#00ff00', similarity 0.01–0.6, blend 0–0.5} or null. effects {blur, sharpen, vignette, glow, grain (film grain): 0–1, stabilize: boolean} (partial, merged) or null; on an adjustment layer vignette and grain give the whole edit a filmic look. transform.rotation turns a picture (degrees; cut-outs and clippings look placed by hand at -3 to 3). wiggle {position: px drift, rotation: degrees, speed: per second} or null adds a gentle hand-held drift (e.g. {position: 4, rotation: 0.5, speed: 1}); stepFps (12 = 'on twos') moves keyframes, wiggle and motion graphics in whole steps like stop-motion paper, or null for smooth. blend: normal | multiply | screen | overlay | soft-light | darken | lighten combines a picture with the tracks below (multiply a paper texture over everything, screen a light leak) or null. frame {radius: corner radius in canvas pixels, shadow 0–1} rounds and shadows a picture (the studio look of screen recordings) or null. Motion graphics (media kind lottie): motion {text: {layerId: 'new text'}, colors: {'#original': '#new'}, loop: boolean} rewrites text layers and swaps colours without changing the file (ids and colours come from list_media motion); patches merge, an empty string removes a text change, mapping a colour to itself removes that swap, null resets. Past its end a graphic holds its last frame, or loops; if the file has an 'out' or 'outro' marker, a longer clip holds before the outro and plays it as the clip ends. Text clips: wordStyle {mode highlight|reveal|pop|bounce, color} animates word by word (words are timed from speech for captions, else spread over the clip); words [{text, startMs, endMs}] (clip-local) sets the timing; null clears either. disabled: true keeps it on the timeline but unseen and unheard. label: a colour tag (red, orange, yellow, green, blue, purple, pink) or null.

  • idstringrequired
  • patchobjectrequired

move_clips

Move clips by deltaMs (linked picture and sound move together). trackId puts all the listed clips on that track; tracks {clipId: trackId or 'new'} moves single clips to other tracks ('new' makes a new track of that kind) while their linked clips keep theirs. overwrite: true makes the moved clips replace what they land on (trimming, splitting or removing it) instead of overlapping it, as dragging does in the timeline.

  • deltaMsnumberrequired
  • trackIdstringoptional
  • tracksobjectoptional
  • overwritebooleanoptional

trim_clip

Move a clip's start or end edge to toMs. Extending is limited by the source media.

  • idstringrequired
  • edge"start" | "end"required
  • toMsnumberrequired

split_clip

Split one clip at a timeline position.

  • idstringrequired
  • atMsnumberrequired

split_at

Blade: split every clip crossing atMs (optionally only on some tracks).

  • atMsnumberrequired
  • trackIdsstring[]optional

delete_clips

Delete clips; ripple closes the gap on their tracks.

  • ripplebooleandefault false

detach_audio

Split a video clip's sound onto its own audio track (the video clip is muted).

  • idstringrequired
  • trackIdstringoptional

remove_ranges

Cut time ranges out of the timeline on every (or the given) track and close the gaps. Script lines and markers after a range move with it.

  • rangesobject[]required
  • trackIdsstring[]optional

get_history

The project's complete history, newest first: every change with its step number, who made it (user, agent or system), when, and on which timeline. It persists across sessions.

  • limitintegerdefault 100
  • beforeintegeroptionalonly steps before this number (paging)
  • afterintegeroptionalonly steps after this number (what's new)

restore_history

Bring the project back to how it was right after a history step. This is a new step itself, so it can be undone.

  • nintegerrequired

list_sequences

Every timeline (sequence) in the project, which one is open, and which appear nested inside others.

No inputs.

new_sequence

Create a timeline (sequence) and open it (open: false keeps the current one open).

  • namestringrequired
  • openbooleandefault true

open_sequence

Open another timeline. Editing tools always work on the open one.

  • idstringrequired

delete_sequence

Delete a timeline that is not open and not nested anywhere.

  • idstringrequired

branch_sequence

Try an alternative cut without touching the original: copies the open timeline (or from) as a branch named e.g. 'Main · alt 1' and opens it. Edit the branch; the user can A/B compare it with the original (backquote key) and keep it with promote_branch.

  • namestringoptional
  • fromstringoptionalsequence id to branch; default the open one

promote_branch

Keep a branch ('Use this version'): it takes the original's name and the original is renamed '… (old)', in one undoable step. The original is found by name ('Main · alt 1' → 'Main') unless originalId is given.

  • idstringrequired
  • originalIdstringoptional

nest_clips

Nest clips (Premiere's Nest): move them into a new sequence that takes their place as one clip. Open the new sequence to edit inside it; the nested clip updates when you come back.

  • idsstring[]required
  • namestringoptional

add_adjustment_layer

Add an adjustment layer: a clip on a video track whose colour grade (update_clip color) and mask apply to everything on the tracks below it for as long as it lasts. Without trackId it goes on a new top track.

  • startMsnumberrequired
  • durationMsnumberdefault 5000
  • trackIdstringoptional

copy_grade

Copy one clip's colour grade (color, including its LUT) to other video or picture clips, e.g. to match shots from the same scene. effects (default true) copies the picture effects (blur, sharpen, vignette, glow, stabilize) too. The whole look is copied: an ungraded source clears the targets' grade. Text clips in toClipIds are skipped.

  • fromClipIdstringrequired
  • toClipIdsstring[]required
  • effectsbooleandefault true

speed_ramp

Speed ramp part of a media clip (fromMs–toMs in clip time, default all of it): up = ease to peak speed, down = ease from peak back to normal, inOut = fast in the middle (montage), outIn with peak < 1 = slow-motion hit. Later clips on the track move to make room.

  • clipIdstringrequired
  • shape"up" | "down" | "inOut" | "outIn"required
  • peaknumberrequired
  • fromMsnumberoptional
  • toMsnumberoptional
  • stepsintegerdefault 10

lift_range

Remove everything between two times (the in and out points) but leave the gap, like Premiere's Lift. Use remove_ranges to close the gap (Extract).

  • startMsnumberrequired
  • endMsnumberrequired
  • trackIdsstring[]optional

insert_edit

Three-point edit: put a media item's range (inMs–outMs, default whole) on a track at atMs. insert pushes later material along on every unlocked track; overwrite replaces what is there.

  • mode"insert" | "overwrite"required
  • assetIdstringrequired
  • trackIdstringrequired
  • atMsnumberrequired
  • inMsnumberoptional
  • outMsnumberoptional

freeze_frame

Hold the frame at atMs (inside a video clip) for durationMs; later clips on that track move along.

  • clipIdstringrequired
  • atMsnumberrequired
  • durationMsnumberdefault 2000

remove_silence

Find pauses in the speech (video and voiceover audio, or given clips) and cut them out across all tracks. keepMs leaves a little air on each side. Use dryRun to preview the ranges first.

  • clipIdsstring[]optional
  • thresholdDbnumberdefault -38
  • minSilenceMsnumberdefault 600
  • keepMsnumberdefault 150
  • dryRunbooleandefault false

slip_clip

Change which part of the source a clip shows without moving it (deltaMs of source time).

  • idstringrequired
  • deltaMsnumberrequired

roll_edit

Move the cut between two adjacent clips on a track to toMs (one gets longer, the other shorter).

  • leftIdstringrequired
  • rightIdstringrequired
  • toMsnumberrequired

slide_clip

Move a clip between its neighbours; the neighbour before grows and the one after shrinks so nothing else moves.

  • idstringrequired
  • deltaMsnumberrequired

group_clips

Link clips so they move and delete together (e.g. picture and its sound).

  • idsstring[]required

add_transition

Transition into a clip from the clip right before it on the same track. Every kind but dip overlaps the clips and crossfades their sound: crossfade, wipe-left/right, slide-left/right, zoom, blur, paper-tear (ragged paper edge), signal-glitch (staggered horizontal signal breakup), ink-blot (organic radial reveal). Dip fades through black. Adding one to a clip that has one replaces it.

  • clipIdstringrequired
  • kind"crossfade" | "dip" | "wipe-left" | "wipe-right" | "slide-left" | "slide-right" | "zoom" | "blur" | "paper-tear" | "signal-glitch" | "ink-blot"default "crossfade"
  • durationMsnumberdefault 600

remove_transition

Remove a clip's transition (a crossfade's overlap is undone).

  • clipIdstringrequired

set_keyframe

Animate a media clip: set x or y (0–1, centre on canvas), scale (1 = fit), rotation (degrees, clockwise), opacity (0–1) or volume (0–2) at a clip-local time. ease is how the value travels to the next keyframe: linear, ease (slow in and out), ease-in (starts slow), ease-out (ends slow), hold (jumps at the next keyframe) or bezier with curve [x1, y1, x2, y2] like CSS cubic-bezier (x 0–1; y below 0 or above 1 overshoots, e.g. [0.34, 1.56, 0.64, 1] for a bounce back).

  • clipIdstringrequired
  • propenumrequired
  • atMsnumberrequired
  • valuenumberrequired
  • ease"linear" | "ease" | "ease-in" | "ease-out" | "hold" | "bezier"default "ease"
  • curvevalueoptionalBezier handles [x1, y1, x2, y2] for ease bezier.

edit_keyframes

Change several keyframes of one clip in one undoable step. Each edit picks a keyframe by prop and its clip-local atMs, then moves it (toMs), changes its value, ease or curve, or removes it (remove: true).

  • clipIdstringrequired
  • editsobject[]optional

remove_keyframe

Remove one keyframe.

  • clipIdstringrequired
  • propenumrequired
  • atMsnumberrequired

clear_keyframes

Remove all keyframes of a property (or of the clip).

  • clipIdstringrequired
  • propenumoptional

add_zoom

Push in on part of a video clip, like a screen recorder's auto-zoom: startMs/endMs are clip-local, x/y is the point of the source to zoom into (0–1), scale 1.2–4.

  • clipIdstringrequired
  • startMsnumberrequired
  • endMsnumberrequired
  • scalenumberdefault 1.8
  • xnumberdefault 0.5
  • ynumberdefault 0.5
  • easeMsnumberdefault 450

update_zoom

Change a zoom.

  • clipIdstringrequired
  • zoomIdstringrequired
  • patchobjectrequired

remove_zoom

Remove a zoom.

  • clipIdstringrequired
  • zoomIdstringrequired

transcribe_media

Word-level transcript of a media item (stored on it). Needed for text-based editing.

  • assetIdstringrequired
  • languagestringoptional

get_transcript

Words of a transcribed media item with their index and source time. Optionally search for a phrase to get its word indices.

  • assetIdstringrequired
  • searchstringoptional

cut_words

Text-based editing: remove words (inclusive index ranges from get_transcript) from the timeline on every track, closing the gaps.

  • assetIdstringrequired
  • rangesobject[]required

remove_filler_words

Cut um, uh, erm and similar from a transcribed media item across all tracks.

  • assetIdstringrequired
  • fillersstring[]optional

build_proxies

Create lightweight playback copies of large videos so the editor plays and scrubs smoothly.

No inputs.

duplicate_clips

Copy clips right after themselves, or offsetMs from their start; trackId puts the copies on another track.

  • offsetMsnumberoptional
  • trackIdstringoptional

select_clips

Select clips in the editor so the user sees what you mean.

  • idsstring[]required

Voiceover script and takes

set_lines

Replace the voiceover script.

  • linesarrayrequired

import_script

Load script lines from an .srt file or a JSON array of lines. replace=false appends.

  • filestringrequired
  • replacebooleandefault true

update_line

Change a line. Moving startMs also moves its voiceover clip.

  • idstringrequired
  • patchscript linerequired

remove_line

Delete a script line (takes stay in the library).

  • idstringrequired

shift_lines

Move lines starting at or after fromMs by deltaMs, with their clips.

  • fromMsnumberrequired
  • deltaMsnumberrequired

select_line

Focus a line in the editor (teleprompter and takes).

  • idstringrequired

record_line

Record a take with the user's microphone: the editor rolls from the pre-roll with a teleprompter and stops after the line's max + post-roll. Tell the user before calling. With wait=true returns the take with its speech length and fit.

  • idstringrequired
  • prerollMsnumberoptional
  • waitbooleandefault true
  • timeoutMsnumberoptional

import_take

Use an audio file as a take for a line. recordedAtMs is where the file starts on the timeline; otherwise its speech starts at the line start.

  • lineIdstringrequired
  • filestringrequired
  • recordedAtMsnumberoptional

list_takes

Takes per line with speech length, fit and which one is used.

  • lineIdstringoptional

choose_take

Use a take for its line (null removes the line's voiceover clip).

  • lineIdstringrequired
  • assetIdstring | nullrequired

Generative tools

generate_take

Generate a spoken take for a line with text-to-speech (placeholder or final voice). Optional voice and delivery instructions.

  • lineIdstringrequired
  • voicestringoptional
  • instructionsstringoptional
  • textstringoptional

rewrite_line

Rewrite a script line with the text model (OpenAI, Ollama or LM Studio per settings). goal fit makes it fit the line's max length; clearer, shorter, or custom with instructions. Returns before and after.

  • idstringrequired
  • goal"fit" | "clearer" | "shorter" | "custom"default "fit"
  • instructionsstringoptional

arrange_clips

Put several pictures on screen at once (clips that play at the same time on different video tracks): side-by-side, top-bottom, thirds, grid (four), full (back to full frame), or picture in picture pip-br / pip-bl / pip-tr / pip-tl (the clip on the higher track becomes the small one; one clip alone is just made small). Split layouts fill areas in the order of clipIds, each picture centre-cropped to fill its area.

  • layout"full" | "side-by-side" | "top-bottom" | "thirds" | "grid" | "pip-br" | "pip-bl" | "pip-tr" | "pip-tl"required
  • clipIdsstring[]required

add_overlay

Add a graphic over the picture in one step. box, circle, arrow, line: an outline in color (arrows and lines go from (x - width/2, y - height/2) to (x + width/2, y + height/2), so width and height can be negative to point the other way); callout: a dark box with text; redact: a solid box (black by default) that hides what is under it; blur: blurs everything under that area (an adjustment layer with a mask). x, y (centre), width, height are shares of the frame. Graphics go on a 'Graphics' text track and pop in; edit them afterwards with update_clip (style x/y, shape {kind, width, height, fill, stroke, strokeWidth, radius}, text).

  • kind"box" | "circle" | "arrow" | "line" | "callout" | "blur" | "redact"required
  • startMsnumberrequired
  • durationMsnumberdefault 3000
  • xnumberdefault 0.5
  • ynumberdefault 0.5
  • widthnumberdefault 0.3
  • heightnumberdefault 0.2
  • colorstringoptional
  • textstringoptional

add_infographic

A quick way to make a data chart over the video: bars compares values, donut shows parts of a whole, cards shows up to four key numbers, line shows a trend, and timeline shows ordered milestones with a value each. Give real numbers and a source when available. It makes a motion graphic from the matching template (bar-chart, donut-chart, stat-row, line-chart, timeline) on a card over the footage and places it at startMs; it returns the assetId, template and params. Change it with update_motion_graphic {assetId, params} (e.g. new items, a theme or colors), or use create_motion_graphic directly for more options (columns, a highlighted bar, full-frame backdrops). Palette: editorial (warm paper, red accent), electric (the dark signal theme with lime), mono (black and white). Without durationMs the template's own length is used.

  • kind"bars" | "donut" | "cards" | "line" | "timeline"required
  • titlestringrequired
  • itemsobject[]required
  • unitstringoptional
  • sourcestringoptional
  • palette"editorial" | "electric" | "mono"default "editorial"
  • startMsnumberrequired
  • durationMsnumberoptional

add_data_callout

Pin an animated callout to a point in the video: a pulsing marker on the target (targetX, targetY), a leader line and a label box with an optional value and source at x, y. Positions are shares of the frame, 0–1. It makes a motion graphic from the callout template and places it at startMs; it returns the assetId, template and params. Move or reword it with update_motion_graphic {assetId, params: {targetX, targetY, labelX, labelY, label, value, source, theme}}. Use for a place, person, object, or sourced fact visible in the shot.

  • labelstringrequired
  • valuestringoptional
  • sourcestringoptional
  • xnumberdefault 0.72
  • ynumberdefault 0.38
  • targetXnumberrequired
  • targetYnumberrequired
  • palette"editorial" | "electric" | "mono"default "editorial"
  • startMsnumberrequired
  • durationMsnumberoptional

review_changes

The user's decision on an agent's proposed changes (review mode): accept keeps them, reject undoes them; clipIds limits it to those clips. Agents cannot call this: when get_state shows pendingReview, tell the user what you changed and let them decide.

  • action"accept" | "reject"required
  • clipIdsstring[]optional

make_variants

Make other versions of the edit without changing the open timeline: other frame shapes (9:16 vertical, 1:1, 4:5, 16:9; full-frame pictures are centre-cropped) and/or shorter cuts (e.g. 15, 30, 60 s). Every combination is exported as a video to the project's export folder; saveProjects also saves each as a project next to this one to fine-tune later. For short cuts, pass keep: the timeline stretches worth keeping (e.g. found with find_moments or from the transcript); otherwise the edit ends at the last cut before the target length.

  • aspects("9:16" | "1:1" | "4:5" | "16:9")[]optional
  • lengthsSecnumber[]optional
  • keepobject[]optional
  • saveProjectsbooleandefault false
  • exportVideosbooleandefault true
  • followFacesbooleandefault falsepan wide shots to follow faces in narrower shapes (on-device, macOS)

search_shots

Find moments in the media by what they show, text on screen or what is said there, e.g. 'dog on a beach', 'whiteboard', 'the word pricing on a slide'. Runs on this Mac (Apple Vision labels, text recognition and faces, plus transcripts); the first search indexes each video, which takes a moment. Returns source ranges (assetId, startMs, endMs) best first, ready for add_clips (inMs = startMs) or insert_edit.

  • querystringrequired
  • assetIdsstring[]optional
  • limitintegerdefault 12
  • describebooleandefault falsealso describe each sampled frame with the vision model of the text provider in Settings (OpenAI sends small frames to OpenAI; Ollama or LM Studio stay on this Mac); descriptions are cached, so later searches are instant

follow_faces

Pan a video clip so the main face stays in the middle of the frame: sets smoothed x keyframes (one undoable step). For pictures wider than the frame, e.g. 16:9 footage in a 9:16 edit (reframe or make_variants first). Faces are found on this Mac.

  • clipIdstringrequired

split_at_scenes

Find the shot changes in the part of a video clip's source it plays and cut the clip (and its linked sound) there, or add 'Shot' markers instead with split false. threshold 0.05–0.9: lower finds more (dissolves), higher only hard cuts. Returns the cut times on the timeline.

  • clipIdstringrequired
  • thresholdnumberdefault 0.3
  • splitbooleandefault true

detect_beats

Tempo (BPM) and beats of a media item with sound. addMarkers puts a green 'Beat' marker on every beat (or every Nth with every) where the item is used on the timeline.

  • assetIdstringrequired
  • addMarkersbooleandefault false
  • everyintegeroptional

snap_cuts_to_beats

Move each cut on a track to the nearest beat of a music item on the timeline (rolling edits, within toleranceMs).

  • trackIdstringrequired
  • musicAssetIdstringrequired
  • toleranceMsnumberdefault 350

rough_cut

Rough cut from a script or brief, on device: finds where each line was said in the transcribed media (word matching that tolerates small wording changes and gaps) and lays the matches out in line order in a new sequence (opened), padded by padMs. Video keeps its sound; audio-only media goes on a Dialogue track. lines default to the project's script lines; assetIds to all media with speech. Returns each match with its confidence (0–1) and the lines not found. Media must be transcribed first (transcribe_media). One undoable step.

  • linesstring[]optional
  • assetIdsstring[]optional
  • namestringoptional
  • padMsnumberdefault 150

beat_montage

Music-driven montage: detects the music's beats and builds a new sequence (opened) with the music on an audio track (fading out at the end) and the pictures cut exactly on every 1, 2 or 4 beats, cycling through the media and taking a different part each time (starting on shot changes where found). Stills last one cut and get a gentle push-in. assetIds default to every video and image except the music; lengthSec defaults to the whole song. One undoable step.

  • musicAssetIdstringrequired
  • assetIdsstring[]optional
  • everyvaluedefault 2
  • lengthSecnumberoptional
  • namestringoptional
  • zoomStillsbooleandefault true

find_moments

Search the edit by meaning using the transcript and the text model, e.g. 'where they talk about pricing'. Returns timeline ranges with reasons. Transcribe first.

  • querystringrequired

generate_chapters

Chapters from the transcript: adds chapter markers and returns a YouTube-ready chapter list.

  • addMarkersbooleandefault true

suggest_broll

Suggest cutaway images (B-roll) for moments in the transcript: times, durations and image prompts. Nothing is generated yet.

  • countintegerdefault 4

add_broll

Generate B-roll images and place them on a B-roll track above the picture, with short fades.

  • itemsobject[]required

reframe

Change the frame size (e.g. 1080×1920 for vertical) and make full-frame pictures fill it with a centre crop. Adjust transform.x per clip afterwards to follow the subject.

  • widthintegerrequired
  • heightintegerrequired

get_ai_status

Which providers handle voice, transcription, text and images (cloud or on this Mac), and whether each is ready.

No inputs.

generate_voiceover

Generate takes for many lines at once (by default only lines without a take).

  • lineIdsstring[]optional
  • onlyMissingbooleandefault true
  • voicestringoptional
  • instructionsstringoptional

auto_captions

Transcribe the voiceover track (or the full mix) and add timed caption clips on a new Captions track, with word timings. style plain gives classic subtitles; highlight, reveal, pop or bounce give animated word-by-word captions in a bold social style (wordColor for the word being said).

  • source"voiceover" | "mix"default "voiceover"
  • maxCharsintegeroptional
  • style"plain" | "highlight" | "reveal" | "pop" | "bounce"default "plain"
  • wordColorstringoptional
  • languagestringoptional

script_from_media

Transcribe a media item's speech into script lines (e.g. to re-record an existing narration).

  • assetIdstringrequired
  • idPrefixstringdefault "L"
  • replacebooleandefault true

review_edit

Director's notes: a quick on-device review of the open timeline. Returns notes {id, atMs, endMs?, kind, severity tip|warning|problem, message, clipId?, fix?} for flash frames and tiny gaps, very short clips, jump cuts, long static shots, titles too fast to read, too small or outside title safe, music that starts or stops abruptly, long pauses in the voiceover, vertical video without captions, no music bed, offline media and disabled clips. A fix is a ready tool call {tool, params, label}: call that tool with those params to apply it. measureAudio also measures the mix's loudness and peaks (slower).

  • measureAudiobooleandefault false

list_recipes

List quick recipes and style guides. Style guides include a goal, required media, structure, directions and review checks. Follow them adaptively with Cue tools; only quick recipes run automatically.

No inputs.

list_styles

Browse the style library. Returns each style's id, name, category, description, preview and recommended library assets; use show_style to select one in the editor and read its full guide.

  • categorystringoptional
  • querystringoptional

show_style

Select a style in Cue's Style library and return its full goal, footage requirements, structure, directions and review checks. Then use the normal Cue editing tools to adapt it to the project.

  • idstringrequired

run_recipe

Run a quick recipe's steps in order on the open project. Style guides without steps are followed by an agent using normal Cue tools instead. Placeholders are filled from the project; dryRun returns resolved calls without running them. On a required-step failure, earlier project edits are restored; optional steps are skipped.

  • idstringrequired
  • dryRunbooleandefault false

save_recipe

Save a quick recipe, style guide, or both. A style guide has format 'style' and guide {goal, requires[], structure[], directions[], review[]}; agents follow it adaptively. Repeatable edits use steps [{tool, params, label?, optional?, each?}] and may use {playheadMs}, {selectedClipIds}, {selectedClipId}, {durationMs}, {projectName}, {voiceoverAssetId}, {musicAssetId}, {firstVideoClipId}, {firstMusicClipId}, {voiceClipIds}, {captionSource}. Saving with the same name replaces your recipe.

  • namestringrequired
  • descriptionstringdefault ""
  • categorystringoptional
  • format"recipe" | "style"optional
  • guideobjectoptional
  • stepsobject[]default {}

delete_recipe

Delete a saved recipe (built-in recipes stay).

  • idstringrequired

generate_image

Generate a still image (title card, B-roll, background). With trackId it is placed at startMs for 5 s.

  • promptstringrequired
  • orientation"landscape" | "portrait" | "square"default "landscape"
  • trackIdstringoptional
  • startMsnumberdefault 0

Playback

seek

Move the playhead.

  • msnumberrequired

play

Play from the playhead or fromMs (optionally stop at toMs).

  • fromMsnumberoptional
  • toMsnumberoptional

pause

Pause playback.

No inputs.

preview_media

Play a media item (e.g. a take) on its own.

  • assetIdstringrequired

Settings, markers, history, export

update_settings

Project settings: recording (prerollMs, postrollMs, autoStop, monitor mute/timeline, padMs, silenceDb), useProxies, and separateAudio (a placed video's sound goes on an audio track, linked; default true).

  • settingsobjectrequired

update_export

Export settings: stemsDir, stemPattern ({id},{index}), normalize, voiceoverFile, videoFile ({name}), videoQuality.

  • exportobjectrequired

update_ai

Generation settings: ttsModel, voice, voiceInstructions, transcriptionModel, imageModel. For images, choose gpt-image-2.5-flare (fast) or gpt-image-2.5-sunburst (precise); older saved models remain usable.

  • aiobjectrequired

add_marker

Add a timeline marker, e.g. to flag something for the user.

  • atMsnumberrequired
  • labelstringrequired
  • color"accent" | "success" | "warning" | "danger"default "accent"

update_marker

Rename, move or recolour a marker.

  • idstringrequired
  • patchobjectrequired

clear_markers

Remove all markers, or only those with a given label (e.g. 'Beat').

  • labelstringoptional

undo

Undo the last edit.

No inputs.

export

Export. stems: one WAV per script line + durations.json. voiceover: the voiceover track as one WAV. audio: full mix (with ducking); the file type follows out (.wav, .mp3, .m4a, .flac). gif: an animated GIF (up to 720 px wide, 15 fps), for short clips. video: rendered video with every visible track and the mix (codec, hardware encoding and scale from export settings). captions: SRT + VTT from the caption clips. otio / fcpxml / mlt / edl: the timeline for another editor (OpenTimelineIO for Resolve, Premiere, Kdenlive; FCPXML for Final Cut Pro and Resolve; MLT for Shotcut; CMX3600 EDL for anything), linking the original media.

  • kind"stems" | "voiceover" | "audio" | "video" | "gif" | "captions" | "otio" | "fcpxml" | "mlt" | "edl"required
  • outstringoptional
  • rangeobjectoptionalvideo/gif/audio only: export just this part, e.g. between the in and out points

export_frame

Save the frame at atMs as a PNG (as the viewer shows it) and return its path.

  • atMsnumberrequired
  • outstringoptional

set_in_out

Set the editor's in and/or out marks (the range for lift, extract, play-in-to-out and range export). null clears one.

  • inMsnumber | nulloptional
  • outMsnumber | nulloptional

set_view

Show the user something: go to a page (edit, motion, titles, colour, audio, voice, review, deliver, agent — motion with motionAssetId opens that graphic on the Motion page), switch workspace (window layout), open a sidebar panel or a dock beside the viewer, fit the whole timeline in view, zoom the timeline (px per second), open a media item in the source monitor, zoom the viewer, turn viewer overlays on or off, split before/after, or A/B compare two sequences.

  • page"edit" | "motion" | "titles" | "colour" | "audio" | "voice" | "review" | "deliver" | "agent"optional
  • motionAssetIdstringoptionalmotion graphic to open on the Motion page
  • panel"media" | "library" | "script" | "transcript" | "text" | "mixer" | "generate" | "history" | "agent" | "settings"optional
  • dock"none" | "mixer" | "scopes" | "agent" | "history" | "markers" | "notes"optionalpane beside the viewer; notes shows the director's notes
  • fitTimelinebooleanoptional
  • zoomnumberoptional
  • openSourcestringoptionalasset id
  • viewerZoomvalueoptionalZoom the viewer to inspect the frame: 'fit', or a percentage of the canvas's real pixels (100 = one canvas pixel per screen pixel)
  • overlaysobjectoptionalViewer overlays: safeAreas (title and action safe guides), teleprompter (script beside the viewer), compare (before/after controls), sourceTwoUp (source monitor beside the viewer), clipStrip (shots under the viewer)
  • beforeAfterobjectoptionalSplit before/after in the viewer: the ungraded picture left of a divider at `at`
  • compareSequencesvalue | nulloptionalA/B compare two sequences (ids from list_sequences): the user flips between them at the same moment with the backquote key; null stops
  • workspace"editing" | "audio" | "colour" | "voiceover" | "titles" | "agent" | "review"optionalediting; audio (mixer docked, tall audio tracks); colour (scopes, before/after, colour tools); voiceover (script and teleprompter); titles (safe areas, text tools); agent (chat and history); review (big viewer, director's notes)

get_app_settings

App-wide settings: theme, projects folder, which AI providers and models are used (voice, transcription, text, images), and editing defaults.

No inputs.

update_app_settings

Change app-wide settings, e.g. {ai: {tts: 'macos', macVoice: 'Samantha'}} or {editor: {snapping: false}} or {theme: 'light'}. API keys and agent access can only be changed by the user.

  • patchobjectrequired