Embed API
The Tella Embed API allows you to control embedded videos using JavaScript’spostMessage API. This enables you to build custom video experiences, synchronize playback with your application, and respond to playback events.
Quick start
Commands
Send commands to the embedded player usingpostMessage. All commands are sent as JSON objects with a type field.
Always wait for the
ready event before sending commands to ensure the player
is initialized.Play
Start video playback.Pause
Pause video playback.Seek
Jump to a specific time in the video.Mute
Mute the video audio.Unmute
Unmute the video audio.Set volume
Set the video volume level.Events
The embedded player sends events to the parent window. Listen for these events usingwindow.addEventListener.
Ready
Sent once when the player is initialized and ready to receive commands.Pointer down
Sent when a viewer presses inside the embedded player. This signals an interaction, not that playback has started.event.origin and event.source === iframe.contentWindow so only your own player can trigger it.
Playback state
Sent when the playback state changes (play, pause, stop, etc.).Time update
Sent approximately every 250ms during playback to report the current time.Complete example
Here’s a complete example showing how to build a custom video controller:Live preview player
The live preview player shows a video as it is being edited. Each saved edit appears a moment later, with no re-render. Get its URL from the MCP toolget_live_preview_link or from POST /v1/videos/{id}/live-preview. Load that URL in your iframe exactly as returned: the access token is in its #token= fragment.
The live preview uses the same postMessage protocol as the embed player, with these differences:
- It sends
ready,playbackStateandtimeUpdate. It also sendsplaybackStateafter each edit appears, so a changeddurationshows up there. - Any
httpspage can embed it in an iframe. - The link stops working at the
expiresAttime it came with (24 hours later), or as soon as the person who requested it loses edit access to the video.
Security considerations
When sending commands, you can use either the specific origin or'*':
Embed URL parameters
You can customize the initial embed behavior using URL parameters:autoLoad=0 still loads the player iframe; it does not create a click-to-load thumbnail. To generate that HTML, turn on Lightweight embed in Share → Embed and use Copy code. See Customize embed settings.