API documentation

Everything you need to integrate the Famvault embed player into your website. Use your own domain in the iframe src so listeners on your parent page can forward progress to POST /api/watch-progress.

Simple integration

One iframe tag — point it at /embed/movie/… or /embed/tv/… on this host.

Lightning fast

Player is streamed by the upstream provider; Famvault only hosts the embed shell and APIs.

Isolated storage

Each upstream configuration uses separate storage — no cross-talk between embeds.

Full reference

Routes, query parameters, progress events, and copy-paste examples below.

Embed generator

Tune options — URLs update for your current host so you can paste into any site.

Basic

Movie TMDB ID

Colors

Custom hex (no #)

Features

Auto playStart playing automatically

Next episodeTV only — next episode control

Episode selectorTV only — season/episode menu

Embed URL

HTML

…

API routes

Replace placeholders with TMDB numeric IDs from themoviedb.org.

/embed/movie/{tmdbId}
/embed/tv/{tmdbId}/{season}/{episode}

URL parameters

Parameter	Type	Description	Example
`color`	string	Primary accent (hex without #)	`?color=ff0000`
`autoPlay`	boolean	Start playback automatically	`?autoPlay=true`
`nextEpisode`	boolean	Show next episode control (TV)	`?nextEpisode=true`
`episodeSelector`	boolean	Enable season/episode selector (TV)	`?episodeSelector=true`
`progress`	number	Start position in seconds	`?progress=120`

Watch progress tracking

The upstream player can post messages to the parent window. On Famvault-hosted embeds, we relay compatible payloads to /api/watch-progress. You can do the same on your own site if you iframe the upstream URL directly.

window.addEventListener("message", function (event) {
  if (typeof event.data !== "string") return;
  try {
    const payload = JSON.parse(event.data);
    console.log("From player:", payload);
  } catch (e) { /* ignore */ }
});

Progress updates may include: id, mediaType (movie/tv), progress (percent), currentTime, duration, season, episode.

Events (when wrapped as PLAYER_EVENT): timeupdate, play, pause, ended, seeked.

{
  "type": "PLAYER_EVENT",
  "data": {
    "event": "timeupdate",
    "currentTime": 120.5,
    "duration": 7200,
    "progress": 1.6,
    "id": "299534",
    "mediaType": "movie",
    "season": 1,
    "episode": 8,
    "timestamp": 1640995200000
  }
}

Code examples

Basic movie

<iframe
  src="https://YOUR_DOMAIN/embed/movie/1078605"
  width="100%"
  height="600"
  frameborder="0"
  allowfullscreen
  allow="encrypted-media; fullscreen">
</iframe>

TV with features + color

<iframe
  src="https://YOUR_DOMAIN/embed/tv/119051/1/8?color=e50914&autoPlay=true&nextEpisode=true&episodeSelector=true"
  width="100%"
  height="600"
  frameborder="0"
  allowfullscreen
  allow="encrypted-media; fullscreen">
</iframe>

Machine-readable URL builder

GET /api/embed-url?type=movie&id=1078605&color=0dcaf0&autoPlay=true