Nebula Embed API

Quickstart

Embed the player into your site using an iframe. Point src to a Nebula embed URL with a TMDB ID.

<iframe
  src="https://nebuladb.pages.dev/embed?movie={tmdb_id}"
  width="100%" height="100%"
  frameborder="0" allowfullscreen
  allow="autoplay; fullscreen; picture-in-picture"
></iframe>

<iframe
  src="https://nebuladb.pages.dev/embed?tv={tmdb_id}&s={season}&e={episode}"
  width="100%" height="100%"
  frameborder="0" allowfullscreen
  allow="autoplay; fullscreen; picture-in-picture"
></iframe>

URL Structure

All content is identified by TMDB IDs. Find any ID on themoviedb.org — it's in the URL when you view a title.

URL Customization

Customize player behavior with URL parameters:

<iframe src="https://nebuladb.pages.dev/embed?tv=31132&s=1&e=1&seek=15&autoplay=true&color=ff5722&autoskip=true"></iframe>

Player Events

Listen for events via postMessage to sync your application with the player.

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://nebuladb.pages.dev') return;
  
  const { type, ...data } = event.data;
  
  switch (type) {
    case 'nebula:ready':
      console.log('Player ready');
      break;
    case 'nebula:timeupdate':
      console.log(data.currentTime, '/', data.duration);
      break;
  }
});

Player Methods

Control the player programmatically by sending commands via postMessage.

const iframe = document.querySelector('iframe');

function sendCommand(command, args = []) {
  iframe.contentWindow.postMessage({
    type: 'nebula:command',
    command,
    args
  }, 'https://nebuladb.pages.dev');
}

// Examples
sendCommand('play');
sendCommand('pause');
sendCommand('seek', [120]);
sendCommand('setVolume', [0.5]);

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://nebuladb.pages.dev') return;
  if (event.data.type !== 'nebula:response') return;

  switch (event.data.command) {
    case 'getCurrentTime':
      console.log('Current time:', event.data.result);
      break;
  }
});

Content Parameters

Advanced Usage

For fully responsive embeds, wrap the iframe in a container with a fixed aspect ratio.

<div style="aspect-ratio: 16 / 9; width: 100%;">
  <iframe
    src="https://nebuladb.pages.dev/embed?movie=550"
    style="width: 100%; height: 100%; border: none;"
    allowfullscreen
    allow="autoplay; fullscreen; picture-in-picture"
  ></iframe>
</div>

Player Features

Notes