Listening to events

To create an interactive user interface around the SDK, you need a way to interact with its state. We achieve this by emitting events in response to SDK actions. For example, when a layer is created, or when a clip is modified, we emit corresponding events. Once you receive an event, you can store it in your preferred state management library and react accordingly to the changes. A complete list of supported events can be found here: SDK Events.

Setting Up Listeners

To listen for an event, use the following code:

Engine.getInstance().events.on("layer:added", ({ layerId }) => {
  console.log(`Layer ${layerId} was added`);
});

When using TypeScript, you will benefit from automatic validation of the received payload, ensuring you always know what data you are receiving.

Removing Listeners

It is a good practice to remove listeners when you are done with them. You can do this as follows:

Engine.getInstance().events.off("layer:added", handleLayerAdded);

To remove all listeners, you can use:

Engine.getInstance().events.removeAllListeners();

Event Catalog

Core

Event	Payload	Description
`ready`	`undefined`	The Engine finished initialization.
`playing`	`{ isPlaying: boolean }`	Playback started or paused.
`time`	`number`	Current time in seconds. Fires on every frame.
`log`	`{ name, message }`	Debug log emitted by the SDK.
`error`	`{ name, message }`	Generic error.

Rendering

Event	Payload	Description
`render:completed`	`undefined`	Export finished successfully.
`render:canceled`	`undefined`	Export was canceled via `cancelExport`.
`render:error`	`{ name, message }`	Export failed.

Layer

Event	Payload	Description
`layer:added`	`{ layerId }`	A new layer was added.
`layer:removed`	`{ layerId }`	A layer was removed.
`layer:updated`	`{ layerId }`	A layer was updated (generic).
`layer:property:updated`	`{ layerId, property, value }`	A layer property changed (name, mute, volume, visibility).
`layer:error`	`{ layerId, name, message }`	Error on a specific layer.
`layers:order:updated`	`{ layersIds }`	The layer order changed.

Clip

Event	Payload	Description
`clip:added`	`{ clipId }`	A clip was added to a layer.
`clip:removed`	`{ clipId, layerId }`	A clip was removed.
`clip:updated`	`{ clipId }`	A clip was updated (generic).
`clip:updated:text`	`{ clipId, text }`	A text clip’s text was changed.
`clip:error`	`{ clipId, name, message }`	Error on a specific clip.
`clip:style:updated`	`{ clipId, property, value }`	A style property changed (position, scale, color, etc.).
`clip:filter:added`	`{ clipId, id, filterId }`	A filter was attached.
`clip:filter:removed`	`{ clipId, id, filterId }`	A filter was detached.
`clip:filter:updated`	`{ clipId, id, filterId }`	A filter was updated.
`clip:effect:added`	`{ clipId, id, effectId }`	An effect was attached.
`clip:effect:removed`	`{ clipId, id, effectId }`	An effect was detached.
`clip:effect:updated`	`{ clipId, id, property, value }`	An effect property changed.
`clip:animation:updated`	`{ clipId }`	The `clip.animationController` animation changed.
`clip:keyframe:changed`	`{ clipId, property? }`	A keyframe from the Property Animator changed.
`clip:lottie-property:updated`	`{ clipId, propertyId }`	A Lottie property changed.

Transition

Event	Payload	Description
`transition:added`	`{ layerId, transitionId }`	A transition was added between clips.
`transition:removed`	`{ layerId, transitionId }`	A transition was removed.
`transition:updated`	`{ transitionId }`	A transition was updated.
`transition:property:changed`	`{ id, property, value }`	A transition property changed.
`transition:error`	`{ transitionId, name, message }`	Error on a specific transition.

Library

Event	Payload	Description
`library:added`	`{ mediaDataId }`	Media was added.
`library:removed`	`{ mediaDataId }`	Media was removed.
`library:replaced`	`{ mediaDataId }`	Media file was replaced.
`library:media:ready`	`{ mediaDataId }`	Media is fully loaded and ready.
`library:media:updated`	`{ mediaDataId, status }`	Media metadata or status changed.
`library:media:samples:updated`	`{ mediaDataId, status }`	Audio samples have been processed.
`library:media:filmstrip:updated`	`{ mediaDataId, status }`	Filmstrip thumbnails have been processed.
`library:progress`	`{ mediaDataId, status, progress }`	Load / transcode progress.
`library:error`	`{ mediaDataId, error }`	Library-level error.
`library:effect:added`	`{ effectId }`	Effect added to library.
`library:effect:removed`	`{ effectId }`	Effect removed from library.
`library:filter:added`	`{ filterId }`	Filter added to library.
`library:filter:removed`	`{ filterId }`	Filter removed from library.
`library:transition:added`	`{ transitionId }`	Transition added to library.
`library:transition:removed`	`{ transitionId }`	Transition removed from library.

Subtitles

Event	Payload	Description
`subtitles:added`	`{ subtitlesId }`	Subtitles were added to the library.
`subtitles:removed`	`{ subtitlesId }`	Subtitles were removed from the library.
`subtitles:main-style:updated`	`undefined`	Main text style changed.
`subtitles:highlighted-style:updated`	`undefined`	Highlighted text style changed.
`subtitles:animation:updated`	`undefined`	Highlight animation changed.
`subtitles:text-mode:updated`	`undefined`	Text mode (full/partial) changed.
`subtitles:transform:updated`	`undefined`	Subtitles position or scale changed.
`subtitles:content:updated`	`{ subtitlesId }`	Many text blocks were updated at once.
`subtitles:duration:updated`	`{ subtitlesId, duration }`	Subtitles duration changed.
`subtitles:textblock:added`	`{ subtitlesId, index }`	A text block was added.
`subtitles:textblock:removed`	`{ subtitlesId, index }`	A text block was removed.
`subtitles:textblock:updated`	`{ subtitlesId, index }`	A text block changed.

Fonts

Event	Payload	Description
`font:added`	`{ fontId }`	A font was registered.
`font:removed`	`{ fontId }`	A font was unregistered.
`font:error`	`{ fontId, name, message }`	Font load error.

Display

Event	Payload	Description
`display:resolution:updated`	`{ width, height }`	Canvas resolution changed.
`display:background:updated`	`{ backgroundColor }`	Canvas background color changed.

Undo / Redo

Event	Payload	Description
`undo:redo:changed`	`{ canUndo, canRedo }`	Use this to drive the enabled state of your Undo and Redo buttons.
`undo:performed`	`{ group }`	An undo just ran.
`redo:performed`	`{ group }`	A redo just ran.
`undo:process:custom`	`{ undoRecord, redoGroup }`	A custom undo record is being processed.

Project

Event	Payload	Description
`project:id:changed`	`{ projectId }`	The project id was changed via `setProjectId`.