Effects & compositions

Generated from project.v1.schema.json at the documented engine version. The schema checks shape only; the engine’s validation also checks ranges, limits, references and keyframe order.

ClipComposition

A clip's use of a Composition, and how its time maps onto it.

Composition time is offset + (t - clip start) * scale for timeline time t, rounded down to a tick. Moving a clip keeps its offset, so its animation moves with it; trimming its start by d adds d * scale to the offset, so what remains of the animation stays where it was. Extending the start before composition time zero makes the offset negative: settings hold their first keyframe there, and media nodes show their first frame.

Field	Type	Description
idrequired	CompositionId	The composition shown.
offset	MediaTime	Composition time at the clip's start. Default: 0
scale	TimeScale	Composition time per timeline time. Default: {"den":1,"num":1}

ClipEffect

One versioned runtime effect invocation: a composition's effect or transition node, or a timeline transition.

Field	Type	Description
idrequired	string	Stable effect definition identifier.
params	{ [name]: Animated_EffectValue }	Named parameter values, constant or keyframed. Omitted entries use definition defaults. Keyframe times are composition times in a composition node and timeline times in a timeline transition. A parameter's keyframes all have one value type, and enum and bool keyframes only hold. An interpolated value that a timing curve carries past the parameter's range is clamped to it; an authored value outside it is an error. Default: {}
resources	{ [name]: EffectResourceId }	Named external resources matched against the effect definition. Default: {}
versionrequired	integer (uint32)	Exact effect definition version required by the project.

Composition

An acyclic graph of image operations with one selected output.

Field	Type	Description
controls	CompositionControl[]	The node settings a group node may set, by name.
idrequired	CompositionId	Stable composition identity.
inputs	string[]	The images a group node gives it, by name, in port order: its GroupInput nodes read them.
nodes	CompositionNode[]	The graph's nodes. Their order has no meaning: a node may name a node listed after it as its input. Default: []
output	NodeId | null	The node whose image is the composition's picture. A composition without one saves, but cannot be rendered. Default: null

CompositionControl

A node setting a composition exposes to the group nodes that use it: an effect or transition parameter of one of its nodes.

Field	Type	Description
namerequired	string	The name a group node sets it by; unique in the composition.
noderequired	NodeId	The effect or transition node.
paramrequired	string	The parameter of its effect.

CompositionId

A stable composition-graph identifier.

Type: string

CompositionNode

One image operation in a Composition.

Field	Type	Description
bypass	boolean	Whether the node passes its bypass_input through unchanged instead of operating. A node without inputs cannot be bypassed. Default: false
idrequired	NodeId	Identity, unique within its composition.
oprequired	NodeOp	What the node does, with its inputs and settings.

EffectValue

Serializable value supplied to one runtime effect parameter.

One of:

type: "float"

One finite scalar.

Field	Type	Description
valuerequired	number (float)

type: "vec2"

Two finite components, normally in normalized coordinates.

Field	Type	Description
valuerequired	number (float)[]

type: "vec4"

Four finite components that are not a color, such as per-channel thresholds; they keyframe component by component.

Field	Type	Description
valuerequired	number (float)[]

type: "color"

Straight (not premultiplied), sRGB-encoded RGBA components in the inclusive unit interval, as a color picker shows them.

Field	Type	Description
valuerequired	number (float)[]

type: "enum"

Index into an effect definition's enum choices.

Field	Type	Description
valuerequired	integer (uint32)

type: "bool"

Boolean toggle.

Field	Type	Description
valuerequired	boolean

MergeLayer

One layer of a Merge.

Field	Type	Description
blend_mode	ClipBlendMode	How the layer blends with the layers under it. Default: "normal"
input	NodeId | null	The layer's image. Default: null
opacity	Animated_float	The layer's opacity, in 0..=1. Default: {"mode":"constant","value":1}

NodeId

A stable identifier of a node within one composition graph. It has no /, which joins the IDs of the group and media nodes a step was drawn through.

Type: string

NodeOp

The operation of a CompositionNode.

Animated settings are keyed in composition time (see ClipComposition), not timeline time.

One of:

type: "clip"

The picture of the clip showing the composition: its source at the source time the clip's time map gives, or what its generated source draws.

type: "media"

Another visual source, read at start plus the composition time. A media node adds no sound to the mix.

Field	Type	Description
source_idrequired	SourceId	The source; a video, image, or generated source.
start	MediaTime	Source time shown at composition time zero. Non-negative. Default: 0

type: "generator"

A picture the engine draws.

Field	Type	Description
generatorrequired	Generator	What is drawn.

type: "effect"

A registered effect: its input and the named images it samples besides.

Field	Type	Description
effectrequired	ClipEffect	The versioned effect and its parameters.
input	NodeId | null	The image the effect processes; a bypassed node passes it through. Default: null
inputs	{ [name]: NodeId | null }	The images the effect samples besides its input, by the names its definition declares (sample_<name> in its shader); at most MAX_EFFECT_INPUTS. A name the definition does not declare, or one it declares and this leaves out, fails the frames that draw the node.

type: "transition"

A registered two-input transition at an explicit progress.

Field	Type	Description
effectrequired	ClipEffect	The versioned transition and its parameters.
from	NodeId | null	The image at progress zero. Default: null
progressrequired	Animated_float	Progress through the transition, in 0..=1.
to	NodeId | null	The image at progress one. Default: null

type: "transform"

The input placed on the canvas by a transform and opacity.

Field	Type	Description
input	NodeId | null	The image placed. Default: null
transform	VisualProperties	Position, anchor, scale, rotation, and opacity. Default: {"anchor":{"x":0.5,"y":0.5},"opacity":{"mode":"constant",…

type: "merge"

Ordered layers composited over transparency.

Field	Type	Description
layers	MergeLayer[]	Layers from bottom to top. Default: []

type: "matte"

The input kept where a second image says.

Field	Type	Description
input	NodeId | null	The image kept. Default: null
matte	NodeId | null	The image whose alpha or luminance is coverage. Default: null
moderequired	MatteMode	Which property of the matte image is coverage.

type: "shape_mask"

The input kept inside shapes.

Field	Type	Description
input	NodeId | null	The image masked. Default: null
masksrequired	ShapeMask[]	The shapes, combined in order; at most MAX_CLIP_MASKS. Geometry is in the input image's normalized space.

type: "group"

Another composition drawn in this one's time, as a group: its output, with its group inputs fed from inputs and its controls set from controls.

Field	Type	Description
compositionrequired	CompositionId	The composition drawn.
controls	{ [name]: Animated_EffectValue }	Values for its controls, by name; a control not set keeps the composition's own value. Keyed in composition time.
inputs	NodeId | null[]	The image for each of its inputs, in its port order. Default: []

type: "group_input"

In a composition used as a group, the image the group node gives its input index.

Field	Type	Description
indexrequired	integer (uint32)	The input, in the composition's port order.