Miraiclip SDK
API reference

Commands

Every built-in command and its payload.

Every edit is a command: project.dispatch({ type, payload }). This page lists the 26 built-in commands with their payload fields, generated from project.commandCatalog() (JSON Schema). Times are integer microseconds. How commands behave, and the errors they throw: Commands.

CommandWhat it does
project/set-settingsChange composition settings (width, height, fps; NTSC rates like 29.97 are stored exactly as 30000/1001, or pass frameRate {num, den}).
asset/addRegister a media asset (video, audio, image, font) by id and src.
asset/removeRemove an asset.
asset/set-propertySet or clear an asset's name and provenance (source, license, attribution).
track/addAdd a track.
track/removeRemove a track and every clip on it.
track/reorderMove a track to a new index in the render order (0 = bottom layer).
track/renameRename a track.
track/set-propertySet a track property: muted, solo, locked, or hidden (hidden tracks aren't drawn; audio follows muted).
clip/addAdd a clip (video, text, caption, …) to a track at a timeline position.
clip/removeRemove a clip.
clip/moveMove a clip to a new timeline start (and optionally another track).
clip/trimChange a clip's in-point (trimStartUs) and/or duration without moving other clips.
clip/splitSplit a clip in two at a timeline position; the right half gets newClipId.
clip/duplicateDuplicate an existing clip to a new id, optionally at a new position.
clip/set-propertySet a clip property (transform fields, volume, audio fades, text content, …) as a static value.
keyframe/setSet a keyframe for an animatable property, with optional easing.
keyframe/removeRemove the keyframe at an exact time (and anchor) for one property of a clip.
keyframe/clearRemove ALL keyframes for one property of a clip.
effect/addAdd an effect to a clip's effect stack (omitted params take defaults).
effect/updateUpdate an effect's params (and/or enabled flag) in place.
effect/removeRemove one effect from a clip by index.
effect/reorderMove an effect to a new index in the clip's stack (stack order = application order).
transition/addAdd a transition (crossDissolve, dipToBlack, dipToWhite, wipe, slide) across the cut between two adjacent clips.
transition/updateUpdate a transition's duration, kind, or params.
transition/removeRemove a transition.

Project

Guide: Project & time

project/set-settings

Change composition settings (width, height, fps; NTSC rates like 29.97 are stored exactly as 30000/1001, or pass frameRate {num, den}).

FieldTypeRequiredNotes
widthinteger> 0
heightinteger> 0
fpsnumber> 0
frameRate{ num, den }
namestring

Asset

Guide: Assets

asset/add

Register a media asset (video, audio, image, font) by id and src. Metadata only — nothing is decoded.

FieldTypeRequiredNotes
idstringyesnon-empty
kind"video" | "audio" | "image" | "font"yes
srcstringyesnon-empty
durationUsinteger> 0
widthinteger> 0
heightinteger> 0
fpsnumber> 0
familystringnon-empty
weightinteger≥ 100, ≤ 900
style"normal" | "italic"
weightRange[integer, integer]
namestringnon-empty
source{ provider, id, url }
license{ id, url, commercial, attributionRequired }
attributionstringnon-empty

asset/remove

Remove an asset. Fails while any clip still references it.

FieldTypeRequiredNotes
idstringyesnon-empty

asset/set-property

Set or clear an asset's name and provenance (source, license, attribution). null clears a field.

FieldTypeRequiredNotes
idstringyesnon-empty
namestring | null
source{ provider, id, url } | null
license{ id, url, commercial, attributionRequired } | null
attributionstring | null

Track

Guide: Tracks

track/add

Add a track. Track order defines layering: later tracks render on top.

FieldTypeRequiredNotes
idstringyesnon-empty
kind"video" | "audio"yes
namestring
indexinteger≥ 0

track/remove

Remove a track and every clip on it.

FieldTypeRequiredNotes
idstringyesnon-empty

track/reorder

Move a track to a new index in the render order (0 = bottom layer).

FieldTypeRequiredNotes
trackIdstringyesnon-empty
indexintegeryes≥ 0

track/rename

Rename a track.

FieldTypeRequiredNotes
trackIdstringyesnon-empty
namestringyesnon-empty

track/set-property

Set a track property: muted, solo, locked, or hidden (hidden tracks aren't drawn; audio follows muted).

FieldTypeRequiredNotes
trackIdstringyesnon-empty
mutedboolean
soloboolean
lockedboolean
hiddenboolean

Clip

Guide: Clips

clip/add

Add a clip (video, text, caption, …) to a track at a timeline position. Times are microseconds.

kind: "video"

FieldTypeRequiredNotes
kind"video"yes
idstringyesnon-empty
trackIdstringyesnon-empty
assetIdstringyesnon-empty
startUsintegeryes≥ 0
durationUsintegeryes> 0
trimStartUsinteger≥ 0, default 0
volumenumber≥ 0, default 1
fadeInUsinteger≥ 0
fadeOutUsinteger≥ 0
transform{ x, y, scale, rotation, opacity }

kind: "audio"

FieldTypeRequiredNotes
kind"audio"yes
idstringyesnon-empty
trackIdstringyesnon-empty
assetIdstringyesnon-empty
startUsintegeryes≥ 0
durationUsintegeryes> 0
trimStartUsinteger≥ 0, default 0
volumenumber≥ 0, default 1
fadeInUsinteger≥ 0
fadeOutUsinteger≥ 0
transform{ x, y, scale, rotation, opacity }

kind: "image"

FieldTypeRequiredNotes
kind"image"yes
idstringyesnon-empty
trackIdstringyesnon-empty
assetIdstringyesnon-empty
startUsintegeryes≥ 0
durationUsintegeryes> 0
transform{ x, y, scale, rotation, opacity }

kind: "text"

FieldTypeRequiredNotes
kind"text"yes
idstringyesnon-empty
trackIdstringyesnon-empty
startUsintegeryes≥ 0
durationUsintegeryes> 0
textstringyes
fontFamilystringdefault "sans-serif"
fontSizePxnumber> 0, default 48
colorstringdefault "#ffffff"
fontWeightinteger≥ 100, ≤ 900
fontStyle"normal" | "italic"
lineHeightnumber> 0, ≤ 5
letterSpacingnumber≥ -0.5, ≤ 2
textAlign"left" | "center" | "right"
transform{ x, y, scale, rotation, opacity }

kind: "caption"

FieldTypeRequiredNotes
kind"caption"yes
idstringyesnon-empty
trackIdstringyesnon-empty
startUsintegeryes≥ 0
durationUsintegeryes> 0
words{ text, startUs, durationUs }[]yes
style{ preset, fontFamily, fontSizeFrac, color, highlightColor, backgroundColor, … }default
transform{ x, y, scale, rotation, opacity }

kind: "html"

FieldTypeRequiredNotes
kind"html"yes
idstringyesnon-empty
trackIdstringyesnon-empty
startUsintegeryes≥ 0
durationUsintegeryes> 0
templatestringyesnon-empty
paramsRecord<string, string | number | boolean>default
widthPxinteger> 0
heightPxinteger> 0
animatedboolean
animationOffsetUsinteger≥ 0
transform{ x, y, scale, rotation, opacity }

Variant

FieldTypeRequiredNotes
kindstringyesnon-empty
idstringyesnon-empty
trackIdstringyesnon-empty
startUsintegeryes≥ 0
durationUsintegeryes> 0
propsRecord<string, unknown>default
transform{ x, y, scale, rotation, opacity }

clip/remove

Remove a clip. Transitions attached to it are dropped.

FieldTypeRequiredNotes
clipIdstringyesnon-empty

clip/move

Move a clip to a new timeline start (and optionally another track).

FieldTypeRequiredNotes
clipIdstringyesnon-empty
startUsinteger≥ 0
trackIdstringnon-empty

clip/trim

Change a clip's in-point (trimStartUs) and/or duration without moving other clips.

FieldTypeRequiredNotes
clipIdstringyesnon-empty
startUsinteger≥ 0
durationUsinteger> 0
trimStartUsinteger≥ 0

clip/split

Split a clip in two at a timeline position; the right half gets newClipId.

FieldTypeRequiredNotes
clipIdstringyesnon-empty
atUsintegeryes> 0
newClipIdstringnon-empty

clip/duplicate

Duplicate an existing clip to a new id, optionally at a new position.

FieldTypeRequiredNotes
clipIdstringyesnon-empty
newClipIdstringnon-empty
startUsinteger≥ 0
trackIdstringnon-empty

clip/set-property

Set a clip property (transform fields, volume, audio fades, text content, …) as a static value.

FieldTypeRequiredNotes
paramsRecord<string, string | number | boolean>
animatedboolean
templatestringnon-empty
unsetParamsstring[]
widthPxinteger | null
heightPxinteger | null
clipIdstringyesnon-empty
transform{ x, y, scale, rotation, opacity }
volumenumber≥ 0
fadeInUsinteger | null
fadeOutUsinteger | null
textstring
fontFamilystring
fontSizePxnumber> 0
colorstring
fontWeightinteger | null
fontStyle"normal" | "italic" | null
lineHeightnumber | null
letterSpacingnumber | null
textAlign"left" | "center" | "right" | null
style{ preset, fontFamily, fontSizeFrac, color, highlightColor, backgroundColor, … }
words{ text, startUs, durationUs }[]

Keyframe

Guide: Keyframes & animation

keyframe/set

Set a keyframe for an animatable property, with optional easing. Time is relative to the clip's visible start, or with anchor "end" measured back from its end (use that for exit animations so they follow trims).

FieldTypeRequiredNotes
clipIdstringyesnon-empty
property"x" | "y" | "scale" | "rotation" | "opacity" | "volume"yes
timeUsintegeryes≥ 0
anchor"start" | "end"
valuenumberyes
easing"linear" | "hold" | "easeIn" | "easeOut" | "easeInOut" | { kind, x1, y1, x2, y2 } | { kind }default "linear"

keyframe/remove

Remove the keyframe at an exact time (and anchor) for one property of a clip.

FieldTypeRequiredNotes
clipIdstringyesnon-empty
property"x" | "y" | "scale" | "rotation" | "opacity" | "volume"yes
timeUsintegeryes≥ 0
anchor"start" | "end"

keyframe/clear

Remove ALL keyframes for one property of a clip.

FieldTypeRequiredNotes
clipIdstringyesnon-empty
property"x" | "y" | "scale" | "rotation" | "opacity" | "volume"

Effect

Guide: Effects

effect/add

Add an effect to a clip's effect stack (omitted params take defaults). Built-in kinds: colorAdjust, mono, invert, warm, cool, hueShift, vibrance, exposure, contrastCurve, gamma, channelSwap, duotone, gradientMap, colorPop, solarize, threshold, posterize, sepia, vintage, polaroid, kodachrome, technicolor, thermal, grain, tealOrange, noir, bleachBypass, crossProcess, faded, matte, goldenHour, moonlight, cyberpunk, vaporwave, cyanotype, infrared, lomo, nightVision, pixelate, halftone, dotMatrix, crosshatch, neonEdges, sketch, emboss, sharpen, toon, oilPaint, hexPixelate, retro8bit, dither, frostedGlass, rgbSplit, scanlines, crt, vhs, glitch, tvStatic, lensFringe, blur, vignette, glow, dreamy, tiltShift, zoomBlur, motionBlur, colorVignette, lightLeak, fisheye, pinch, swirl, wave, ripple, mirrorX, mirrorY, kaleidoscope, chromaKey, letterbox, roundedCorners; or a registered custom kind.

FieldTypeRequiredNotes
clipIdstringyesnon-empty
kindstringyesnon-empty
paramsRecord<string, unknown>
enabledbooleandefault true
indexinteger≥ 0
effectIdstringnon-empty

effect/update

Update an effect's params (and/or enabled flag) in place.

FieldTypeRequiredNotes
clipIdstringyesnon-empty
effectIdstringyesnon-empty
paramsRecord<string, unknown>
enabledboolean

effect/remove

Remove one effect from a clip by index.

FieldTypeRequiredNotes
clipIdstringyesnon-empty
effectIdstringyesnon-empty

effect/reorder

Move an effect to a new index in the clip's stack (stack order = application order).

FieldTypeRequiredNotes
clipIdstringyesnon-empty
effectIdstringyesnon-empty
indexintegeryes≥ 0

Transition

Guide: Transitions

transition/add

Add a transition (crossDissolve, dipToBlack, dipToWhite, wipe, slide) across the cut between two adjacent clips.

FieldTypeRequiredNotes
idstringnon-empty
kindstringyesnon-empty
fromClipIdstringyesnon-empty
toClipIdstringyesnon-empty
durationUsintegeryes> 0
paramsRecord<string, unknown>

transition/update

Update a transition's duration, kind, or params.

FieldTypeRequiredNotes
transitionIdstringyesnon-empty
durationUsinteger> 0
paramsRecord<string, unknown>

transition/remove

Remove a transition.

FieldTypeRequiredNotes
transitionIdstringyesnon-empty

Overview

Every export of every package, generated from the published type definitions.

@miraiclip/core

Headless, command-driven engine for building video editors — state, commands, history, patches, events.

On this page

Projectproject/set-settingsAssetasset/addasset/removeasset/set-propertyTracktrack/addtrack/removetrack/reordertrack/renametrack/set-propertyClipclip/addclip/removeclip/moveclip/trimclip/splitclip/duplicateclip/set-propertyKeyframekeyframe/setkeyframe/removekeyframe/clearEffecteffect/addeffect/updateeffect/removeeffect/reorderTransitiontransition/addtransition/updatetransition/remove