Documentation

Everything you need to embed StreamVault's video player into your website. Get started in under a minute — no API key required.

Quickstart

Embed a movie or TV show into your site with a single iframe. Just replace the TMDB ID with the one you want.

Movie Embed

<iframe
  src=""
  width="100%"
  height="100%"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen; picture-in-picture"
></iframe>

TV Show Embed

<iframe
  src=""
  width="100%"
  height="100%"
  frameborder="0"
  allowfullscreen
  allow="autoplay; fullscreen; picture-in-picture"
></iframe>

Embed URL Structure

StreamVault uses a simple URL pattern based on TMDB IDs. No API keys or authentication required.

# Movie
/embed/movie/{tmdb_id}

# TV Show
/embed/tv/{tmdb_id}/{season}/{episode}

Parameters

Examples

# Fight Club (Movie)
/embed/movie/550

# Breaking Bad S1E1 (TV)
/embed/tv/1396/1/1

# The Office S3E13 (TV)
/embed/tv/2316/3/13

Iframe Setup

For the best experience, use a responsive container with a 16:9 aspect ratio.

<style>
  .player-wrap {
    position: relative;
    width: 100%;
    max-width: 960px;
    aspect-ratio: 16 / 9;
  }
  .player-wrap iframe {
    position: absolute;
    inset: 0;
    width: 100%;
    height: 100%;
    border: none;
    border-radius: 12px;
  }
</style>

<div class="player-wrap">
  <iframe
    src=""
    allowfullscreen
    allow="autoplay; fullscreen; picture-in-picture"
  ></iframe>
</div>

Permissions

Include the allow attribute on your iframe for the best player experience:

allow="autoplay; fullscreen; picture-in-picture; encrypted-media"

Responsive Design

The player automatically adapts to any container size. For responsive layouts, use CSS aspect-ratio or the padding-bottom technique:

.player {
  width: 100%;
  aspect-ratio: 16 / 9;
}
.player iframe {
  width: 100%;
  height: 100%;
  border: none;
}

.player {
  position: relative;
  width: 100%;
  padding-bottom: 56.25%; /* 16:9 */
  height: 0;
}
.player iframe {
  position: absolute;
  top: 0; left: 0;
  width: 100%; height: 100%;
  border: none;
}

API Endpoints

StreamVault also exposes REST API endpoints if you need raw stream data or metadata.

Streams API

Returns an array of available stream sources for a title.

# Movie streams
/api/streams/movie/{tmdb_id}

# TV show streams
/api/streams/tv/{tmdb_id}/{season}/{episode}

Response:

{
  "streams": [
    {
      "url": "https://cdn.example.com/stream.m3u8",
      "quality": "1080p",
      "type": "hls",
      "provider": "VidBinge"
    }
  ]
}

Metadata API

Returns TMDB metadata for a title. Requires TMDB_API_KEY to be configured on the server.

# Movie metadata
/api/meta/movie/{tmdb_id}

# TV show metadata
/api/meta/tv/{tmdb_id}

Best Practices

Use responsive containers

Always wrap the iframe in a container with aspect-ratio: 16/9 rather than using fixed pixel dimensions.

Allow required permissions

Include allow="autoplay; fullscreen; picture-in-picture" on your iframe for the full player experience.

Handle errors gracefully

If streams fail to load, the player will automatically cycle through available sources. Consider adding a fallback message below the player for users with strict ad blockers.

Lazy-load for performance

Add loading="lazy" to iframes that are below the fold to improve page load times.

<iframe src="..." loading="lazy" allowfullscreen></iframe>

Test across devices

The player is optimized for desktop, tablet, and mobile. Test your integration on all screen sizes to ensure the container scales correctly.

Stay updated

Join our Telegram group for announcements about new features, API changes, and provider updates.