Skip to main content

Embed API

The Tella Embed API allows you to control embedded videos using JavaScript’s postMessage 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 using postMessage. 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 using window.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.
If you use this event to reveal a hidden player, verify both 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 tool get_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, playbackState and timeUpdate. It also sends playbackState after each edit appears, so a changed duration shows up there.
  • Any https page can embed it in an iframe.
  • The link stops working at the expiresAt time it came with (24 hours later), or as soon as the person who requested it loses edit access to the video.
Anyone with the link can watch the video without signing in, so share it only with the person you’re editing for.

Security considerations

Always verify the event.origin when receiving messages to ensure they come from https://www.tella.tv.
When sending commands, you can use either the specific origin or '*':

Embed URL parameters

You can customize the initial embed behavior using URL parameters:
Setting 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.
Last modified on October 28, 2026