Every action available to the AI assistant and the Editor API.
The video editor has 92 actions. The AI assistant uses 89 of them. The other three are the lock actions in Locks, which only a person may run. Your own code runs them on the mounted Editor API, with execute(name, args), or with executeAsync(name, args) for itemUnlock. The standalone Headless Runtime is Coming soon.
Every action that is not a reading action also needs scopeReason. From your own code, pass 'explicit'. The tables leave scopeReason out of the required arguments.
list() returns each action with its name, title, category, description, usage, and argsSchema, the JSON Schema of its arguments. Read argsSchema for the optional arguments, their units, and their limits.
Lists the actions this editor can run now, for one item type or one category if you ask.
none
readCanvasState
Returns everything on the video canvas: every item with its real colours, text styling, geometry, timing, group membership, plus the current selection and canvas size.
none
readItems
Finds items by a structured query. It always returns ranked candidates and a resolution verdict, never one guessed answer.
none
readLayoutCheck
Checks the layout and returns problems, worst first: items fully off the canvas, overlapping pairs, text below 12 px, and items that cross the safe-area margin.
none
readCaptionsFile
Returns the captions of the video as the text of a subtitle file, with the times of the finished video: srt, vtt, or txt (a transcript with no times). It is the same text that the Export panel's Download buttons save. speakerNames: true writes each line's speaker name into the file.
format
readSubtitleCues
Reads the caption lines of one caption track, a page at a time, including each line's number, its start and end time, its words, and the timing of each individual word when the track has them.
ids
readTextTemplates
Reads the catalogue shown in Styles: host templates and categories followed by built-ins, unless replaceBuiltIns is true.
Removes everything the user has put on the canvas, on every part of the timeline.
none
canvasMatchMedia
Resizes the canvas to the size of one clip, and places that clip so it fills the canvas exactly. An odd width or height is reduced by one pixel, because MP4 video cannot store it.
ids
canvasResize
Changes the width and height of the canvas, and says what happens to the items already on it.
width, height
canvasSetBackgroundFill
Sets the canvas background to one solid colour.
fillColor
canvasSetBackgroundFromItem
Makes the canvas background a blurred, darkened copy of one picture or video clip, fitted to the canvas from the clip's own frames as it plays. Optional ids (one item; left out: the bottom-most picture or clip on screen at the playhead), blur (0 to 40) and dim (0 to 1).
none
canvasSetBackgroundGradient
Sets the canvas background to a colour blend (two or more stops). Optional angle, 0 to 359: 90 is left to right, 180 is top to bottom.
gradientColors
canvasSetBackgroundImage
Puts a picture from a web address behind everything else on the canvas, scaled to cover it and centred. Optional blur (0 to 40) and dim (0 to 1).
imageUrl
canvasSetBackgroundLook
Makes the background picture or blurred copy softer or darker, and keeps the picture. blur (0 to 40), dim (0 to 1), or both.
none
canvasSetSelection
Selects the given items, so the user can see what the assistant is talking about or what has changed.
Lines items up with each other or with the edges of the canvas, or spreads them out evenly.
ids, action
itemClearAnimations
Removes every animation (in, out, loop and motion) from the items.
ids
itemDelete
Permanently removes items from the canvas.
ids
itemDuplicate
Copies items 10 px down and to the right of the originals, and returns the new ids.
ids
itemGroup
Ties two or more items together so they move and select as one.
ids
itemMoveLayer
Moves items up or down in the visual stacking order.
ids, direction
itemSetAnimations
Sets the animations of an item by slot: "in" plays once as it appears, "out" once as it leaves, "loop" repeats while it is visible, and "motion" moves the whole clip.
ids, animations
itemSetOpacity
Sets how see-through an item is on the video canvas.
ids, opacity
itemSetPosition
Moves items to an exact position on the video canvas.
ids
itemSetRotation
Rotates text, video, shape and picture (image, gif, sticker) items.
ids, rotation
itemSetSize
Sets an item's width and/or height in canvas pixels.
ids
itemSetTimelinePlacement
Moves an item along the timeline: when it appears (startSeconds) and how long it stays (durationSeconds or endSeconds). For a video or sound clip, sourceStartSeconds trims its start: the second of its own file at which it begins. The clip's end stays where it is.
ids
itemUngroup
Releases the groups the given items belong to, one level at a time.
These three actions are part of item locking, which is new in @layermetry/media-editor. Item locking needs version 1.0.0 or later; versions before 1.0.0 do not have these actions. They are for a person only: the assistant is not offered them, and it is refused when it calls one. Each one is one undo step.
Action
What it does
Required arguments
itemSetLocks
Locks or unlocks kinds of change on items. Only the design's creator may run it. Give locks, one switch per scope (true locks it, false unlocks it, a scope you do not name stays as it is), or preset: 'all' locks every scope and 'none' unlocks every scope.
ids, and locks or preset
itemUnlock
Unlocks kinds of change on items, after your onUnlock allows it. A creator may always run it, and an adopter only when you pass allowUnlock. scopes is always a list, for example ['move'], or ['all'] for every scope. Run it with executeAsync, because it waits for your onUnlock.
ids, scopes
designSetDefaultLocks
Sets the default locks that every item without its own lock follows, and whether new items may be added (add). Only the design's creator may run it. Give locks or preset, as for itemSetLocks.
locks or preset
Without exactly one of locks and preset, itemSetLocks and designSetDefaultLocks answer ok: false with "itemSetLocks needs exactly one of locks (one switch per kind of change) or preset ('all' or 'none')." The refusal reasons of every action are listed in Item locks.
Adds a picture from a web address to the video canvas and returns its id.
url
mediaAddVideoFromUrl
Adds a video clip from a web address to the canvas and returns its id.
url
mediaClearCrop
Removes a crop so the whole source shows again.
ids
mediaClearFilters
Removes every picture filter from a photo or a moving clip at once: full colour again, normal brightness, perfectly sharp, normal contrast.
ids
mediaClearMask
Removes a mask so the whole picture or clip shows again. The crop is not changed.
ids
mediaCrop
Crops a picture, GIF, sticker or video clip to a rectangle of its own pixels, not canvas pixels.
ids, crop
mediaFitToCanvas
Sizes a picture, GIF, sticker or video clip against the canvas. fit shows the whole picture, fill covers the canvas and crops the rest, and stretch fills the canvas and distorts the picture.
ids
mediaReplaceSource
Replaces the picture or clip an item shows with a new one from a web address, at the same place, the same size and the same moment in the video.
ids, url
mediaSetFilters
Changes how a photo or a moving clip looks: make it grey, sepia or colour-reversed, make it brighter or darker, blur it, or push the contrast up or down.
ids
mediaSetMask
Cuts a picture, GIF, sticker or video clip to a shape: a rectangle, an ellipse, a star, a polygon, your own path, or one straight edge. The shape is given as fractions of the item's box. invert hides the inside instead, and feather softens the edge. No pixels are deleted.
Merges two pieces of the same clip back into one, undoing a split.
ids
clipSetMuted
Mutes or unmutes a video clip or audio item — explicitly, never a toggle.
ids, muted
clipSetSpeed
Plays a video or sound clip faster or slower, from 0.25 to 4 times its recorded speed. The clip gets shorter or longer on the timeline, and its sound changes pitch with the speed.
ids, speed
clipSplit
Cuts a video or audio clip into two at a moment on the timeline.
Adds a new text item to the video canvas and returns its id. It also takes the six values of a text style, all optional: fontFamily, fontSize, fontWeight, fontStyle, textDecoration, and lineHeight.
text
textApplyStyle
Gives text items a text style in one step: typeface, size, weight, italic, underline, and line spacing. It sets each value it is given, never switches one, and leaves a value you omit as it is. It applies to the whole item and is one undo step.
ids
textApplyEffectPreset
Applies a ready-made lettering look to a text item: "Neon", "Outline", or "Drop Shadow".
ids, preset
textClearEffects
Removes a text item's outline, shadow/glow, letter spacing and line height overrides.
ids
textSetAlign
Aligns the lines inside a text item's box: left, center or right.
ids, align
textSetBold
Turns bold on or off for a text item — explicitly, never a toggle.
ids, bold
textSetColor
Sets the lettering colour of a text item.
ids, textColor
textSetEffects
Styles a text item's lettering: outline (stroke), shadow/glow, letter spacing and line height, in one call.
ids
textSetFontFamily
Sets the typeface of a text item by family name.
ids, fontFamily
textSetFontSize
Sets a text item's lettering size in canvas pixels.
ids, fontSize
textSetItalic
Turns italics on or off for a text item — explicitly, never a toggle.
ids, italic
textSetText
Replaces the words of an existing text item.
ids, text
textSetUnderline
Turns underlining on or off for a text item — explicitly, never a toggle.
ids, underline
textSetWeight
Sets how heavy a text item's letters are, from 100 (thinnest) to 900 (heaviest).
ids, weight
textSetWidth
Sets how wide a text item's column is, in canvas pixels.
ids, width
textTransformCase
Rewrites a text item's words in UPPERCASE, lowercase or Capitalized Case.
Listens to a clip with sound and adds a caption track under it with the words that are said, each line timed to the voice. It uses your transcription service, which can cost credits.
ids
subtitleAdd
Adds a caption track from a list of caption lines and returns its id. The line times count from the track's start. Without startSeconds, the track starts at 0, so each line shows at the second it names. Without endSeconds, the track ends where its last line ends.
cues
subtitleApplyPreset
Puts a ready-made look on a caption track: typeface, size, colours, outline and shadow in one step.
ids, presetId
subtitleSetAlign
Lines the caption words up to the left, the centre or the right of the canvas.
ids, align
subtitleSetCues
Replaces every caption line on a caption track with the list you give, written exactly as given.
ids, cues
subtitleSetCueText
Changes the words of a single caption line, leaving its times, its word timings and every other line untouched.
ids, cueId, text
subtitleSetStyle
Changes how a caption track looks: typeface, size and colour, the plate behind the words, where on screen it sits, outline, shadow, spacing, capitalisation, and how each line arrives (animation: none, fade, slide, or bounce). positionY: null removes an exact height, so position places the captions again.
ids
captionsFromClip takes time, so it runs only through executeTool, the way the AI assistant runs actions. execute answers it at once with ok: false and the sentence "captionsFromClip takes time (it waits for work outside the editor), so it cannot answer at once. Run it through executeTool, the door the assistant uses, instead of execute." The optional language is a short code such as en or pt-BR. Without it, the action uses the language chosen in the Captions panel, or lets the service detect it. See Editor API.
When the editor has no transcription service, captionsFromClip answers "Captions cannot be written here: this editor has no transcription service. Nothing was changed." When your ai setting has captions: false, toolContracts leave the action out, and a call is refused with "Captions are switched off in this editor, so the sound was not sent anywhere." When none of the clips has speech, it answers, for example, "No captions were written: voiceover-1, no speech was heard in it."
Adds a sound clip — spoken narration, music, an effect — from a web address, and returns its id. With the optional presetId, the clip is added with that audio treatment, and one undo removes both.
url
audioApplyPreset
Applies a named audio treatment to a clip that has sound — for example making a voice clearer, or making music sit behind speech.
ids, presetId
audioClearProcessing
Puts every sound setting of a clip back to its starting value, with the loudness at 100 percent.
ids
audioReplaceRange
Replaces the part of a sound clip between two moments with a new recording from a web address. The clip is cut at both moments, and one undo brings it back whole.
ids, url, startSeconds, endSeconds
audioSetFades
Fades a clip's sound in from silence at its start, out to silence at its end, or both, in straight lines. fadeInSeconds and fadeOutSeconds are 0 to 60, and 0 removes a fade.
ids
audioSetProcessing
Changes the sound of a clip by hand: cut low or high sounds, hold loud parts back, change the tone, even out the level, add warmth, or move the sound left or right.
ids
audioSetVolume
Sets how loud one clip is, as a percentage: 100 leaves it as recorded, 50 is half as loud, 200 is twice as loud, 0 is silent.
ids, volumePercent
voiceoverSetScript
Puts the words that a person will read aloud into the voiceover recorder. It replaces the script, and an empty text clears it. It changes nothing on the timeline.
text
presetId takes the same values as audioApplyPreset, for example clean-up-noise or voice-boost. voiceoverSetScript takes at most 20,000 characters. Where the editor has no voiceover recorder, it answers ok: false with "This editor has no voiceover recorder here, so a script cannot be prepared. Nothing was changed."
Starts making a video file from the design as it is now. Later changes do not reach an export that has started. format chooses the file: 'mp4' (the default), 'webm', or 'gif'. codec is 'h264' or 'hevc' for an MP4, and 'vp9' for a WebM. withoutSound: true leaves the sound out. gifColors, gifDither, and gifLoop apply to a GIF only. subtitles chooses how captions reach the file: 'burn' (the default), 'track', or 'both'. A WebM or a GIF has no subtitle track.
none
readExportCapabilities
Says, for each kind of file, whether this browser can make its picture and whether it can keep the sound, and which file to ask for when the video has sound. Only an editor on a page can answer.
none
readExportJobs
Lists every export in the queue with its state — waiting, running, finished, failed or cancelled — how far along it is, and which one is running now.
Editing through a custom action after the editor closes returns { ok: false, reason: "editor-closed" }. A closed editor also aborts the action's signal.
