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

<iframe
  id="tella-player"
  src="https://www.tella.tv/video/YOUR_VIDEO_ID/embed"
  allow="autoplay; fullscreen"
></iframe>

<script>
  const iframe = document.getElementById("tella-player");

  // Wait for the player to be ready
  window.addEventListener("message", (event) => {
    if (event.data.type === "ready") {
      console.log("Player is ready!");
      // Now you can send commands
      iframe.contentWindow.postMessage(
        { type: "play" },
        "https://www.tella.tv",
      );
    }
  });
</script>

​
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. 
iframe.contentWindow.postMessage({ type: "play" }, "https://www.tella.tv");

​
Pause

Pause video playback. 
iframe.contentWindow.postMessage({ type: "pause" }, "https://www.tella.tv");

​
Seek

Jump to a specific time in the video.
ParameterTypeDescription
timenumberTime in seconds to seek to
// Seek to 30 seconds
iframe.contentWindow.postMessage(
  { type: "seek", time: 30 },
  "https://www.tella.tv",
);

​
Mute

Mute the video audio. 
iframe.contentWindow.postMessage({ type: "mute" }, "https://www.tella.tv");

​
Unmute

Unmute the video audio. 
iframe.contentWindow.postMessage({ type: "unmute" }, "https://www.tella.tv");

​
Set Volume

Set the video volume level.
ParameterTypeDescription
volumenumberVolume level from 0 (muted) to 1 (full volume)
// Set volume to 50%
iframe.contentWindow.postMessage(
  { type: "setVolume", volume: 0.5 },
  "https://www.tella.tv",
);

​
Events

The embedded player sends events to the parent window. Listen for these events using window.addEventListener. 
window.addEventListener("message", (event) => {
  // Verify the message is from Tella
  if (event.origin !== "https://www.tella.tv") return;

  const { type, ...data } = event.data;
  console.log("Event:", type, data);
});

​
Ready

Sent once when the player is initialized and ready to receive commands. 
{
  "type": "ready"
}

​
Playback State

Sent when the playback state changes (play, pause, stop, etc.).
FieldTypeDescription
statestringCurrent state: idle, playing, paused, stopped, seeking, or stalled
currentTimenumberCurrent playback position in seconds
durationnumberTotal video duration in seconds
{
  "type": "playbackState",
  "state": "playing",
  "currentTime": 15.5,
  "duration": 120.0
}

​
Time Update

Sent approximately every 250ms during playback to report the current time.
FieldTypeDescription
currentTimenumberCurrent playback position in seconds
durationnumberTotal video duration in seconds
{
  "type": "timeUpdate",
  "currentTime": 16.25,
  "duration": 120.0
}

​
Complete Example

Here’s a complete example showing how to build a custom video controller: 
<!DOCTYPE html>
<html>
  <head>
    <title>Custom Tella Player</title>
  </head>
  <body>
    <iframe
      id="player"
      src="https://www.tella.tv/video/YOUR_VIDEO_ID/embed"
      width="640"
      height="360"
      allow="autoplay; fullscreen"
    ></iframe>

    <div id="controls" style="display: none;">
      <button id="playBtn">Play</button>
      <button id="pauseBtn">Pause</button>
      <input type="range" id="progress" min="0" max="100" value="0" />
      <span id="time">0:00 / 0:00</span>
    </div>

    <script>
      const iframe = document.getElementById("player");
      const controls = document.getElementById("controls");
      const progress = document.getElementById("progress");
      const timeDisplay = document.getElementById("time");

      let duration = 0;
      const origin = "https://www.tella.tv";

      function formatTime(seconds) {
        const mins = Math.floor(seconds / 60);
        const secs = Math.floor(seconds % 60);
        return `${mins}:${secs.toString().padStart(2, "0")}`;
      }

      function send(message) {
        iframe.contentWindow.postMessage(message, origin);
      }

      // Listen for events from the player
      window.addEventListener("message", (event) => {
        if (event.origin !== origin) return;

        switch (event.data.type) {
          case "ready":
            controls.style.display = "block";
            break;

          case "playbackState":
          case "timeUpdate":
            duration = event.data.duration;
            const current = event.data.currentTime;
            progress.value = (current / duration) * 100;
            timeDisplay.textContent = `${formatTime(current)} / ${formatTime(
              duration,
            )}`;
            break;
        }
      });

      // Wire up controls
      document.getElementById("playBtn").onclick = () => send({ type: "play" });
      document.getElementById("pauseBtn").onclick = () =>
        send({ type: "pause" });

      progress.addEventListener("change", () => {
        const time = (progress.value / 100) * duration;
        send({ type: "seek", time });
      });
    </script>
  </body>
</html>

​
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 '*': 
// Recommended: specify the exact origin
iframe.contentWindow.postMessage({ type: "play" }, "https://www.tella.tv");

// Also works but less secure
iframe.contentWindow.postMessage({ type: "play" }, "*");

​
Embed URL Parameters

You can customize the initial embed behavior using URL parameters:
ParameterValuesDescription
autoPlaytrueAuto-play the video on load
loop1Loop the video when it ends
muted1Start the video muted
tsecondsStart playback at a specific time
<!-- Auto-play muted, starting at 30 seconds -->
<iframe
  src="https://www.tella.tv/video/ID/embed?autoPlay=true&muted=1&t=30"
></iframe>