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

If you embed the player from your custom domain, use that domain’s origin (for example https://videos.example.com) instead of https://www.tella.tv.

Commands

Send commands to the embedded player using postMessage. All commands are sent as JSON objects with a type field. Wait for the ready event before sending commands: the player ignores commands that arrive earlier. It also ignores commands from other frames on your page; only the page that embeds the player can control it.

Hello

Ask the player to send ready again. Use it when your code may start listening after the player loaded, for example in a component that mounts later. A player that isn’t ready yet sends ready when it is.

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.

Captions on and off

Show or hide captions. Captions only appear if the video has them.

Set playback rate

Set the playback speed.

Events

The embedded player sends events to the parent window. Listen for these events using window.addEventListener.
Every event has "namespace": "tella", so you can tell Tella’s messages apart from other widgets’ on the same page. With several players on one page, compare event.source with each iframe’s contentWindow to see which player sent the event.

Ready

Sent when the player is initialized and ready to receive commands, and again in reply to hello.

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.

Captions change

Sent when captions are turned on or off, by the viewer or by a captionsOn/captionsOff command.

Playback rate change

Sent when the playback speed changes, by the viewer or by a setPlaybackRate command.

Keep the viewer’s captions and speed across videos

Each embed starts with the video’s own captions and speed settings. To carry the viewer’s choices from one embed to the next (for example, lessons in a course), save them from the captionsChange and playbackRateChange events and pass them to every embed with the captions and speed URL parameters:

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, and ignores captionsOn, captionsOff and setPlaybackRate. It also sends playbackState after each edit appears, so a changed duration shows up there.
  • Any https page can embed it in an iframe.
  • Its control bar has the editor’s quality button, left of the volume control: pick Low-res (fastest), Hi-res (1080p) or Source (slowest). It starts on what the video’s editor plays, and a pick only changes this player, never the video’s editing quality. See Edit faster with low-res mode.
  • 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

When receiving messages, check both event.origin (https://www.tella.tv, or your custom domain) and event.source === iframe.contentWindow, so that only your own player can drive your page.
When sending commands, pass the exact origin rather than '*', so a command never reaches a page that isn’t the player:

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 November 2, 2026