<peertube-video>

A custom element for the PeerTube player with an API that matches the <video> API.

• 🏄‍♂️ Compatible HTMLMediaElement API
• 🕺 Seamlessly integrates with Media Chrome
• 🎞️ Rendition/quality selection via media-tracks
• 💬 Caption track support

Known limitations

These are constraints of the PeerTube embed API that affect Media Chrome integration:

• Buffer progress bar is not available — The embed API does not expose download/buffer progress, so el.buffered always returns empty. The Media Chrome time range will not show a buffered region ahead of the playhead.
• Auto quality does not enable ABR — The "Auto" option in <media-rendition-menu> only works when the PeerTube instance streams in p2p-media-loader mode (HLS). In the default web-video mode (plain MP4), adaptive bitrate is not supported and selecting Auto falls back to the highest fixed resolution. Pass config={{ mode: 'p2p-media-loader' }} to opt into HLS mode on instances that support it.

Example

<script type="module" src="https://cdn.jsdelivr.net/npm/[email protected]/+esm"></script>
<peertube-video controls src="https://video.mshparisnord.fr/w/7r2FxoQdYjun6tYWJfHUCa"></peertube-video>

Supported URL formats:

https://instance.example/videos/watch/<id>
https://instance.example/videos/embed/<id>
https://instance.example/w/<id>

Install

First install the NPM package:

npm install peertube-video-element

Import in your app javascript (e.g. src/App.js):

import 'peertube-video-element';

Optionally, you can load the script directly from a CDN using JSDelivr:

<script type="module" src="https://cdn.jsdelivr.net/npm/[email protected]/+esm"></script>

This will register the custom elements with the browser so they can be used as HTML.

Usage with Media Chrome

<script type="importmap">
  { "imports": { "media-tracks": "https://cdn.jsdelivr.net/npm/[email protected]/+esm" } }
</script>
<script type="module" src="https://cdn.jsdelivr.net/npm/[email protected]/+esm"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/+esm"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/media-chrome@4/menu/+esm"></script>

<media-controller>
  <peertube-video slot="media" src="https://video.mshparisnord.fr/w/7r2FxoQdYjun6tYWJfHUCa"></peertube-video>
  <media-captions-menu hidden anchor="auto"></media-captions-menu>
  <media-rendition-menu anchor="auto" hidden>
    <div slot="header">Quality</div>
  </media-rendition-menu>
  <media-control-bar>
    <media-play-button></media-play-button>
    <media-mute-button></media-mute-button>
    <media-volume-range></media-volume-range>
    <media-time-range></media-time-range>
    <media-time-display show-duration></media-time-display>
    <media-captions-menu-button></media-captions-menu-button>
    <media-rendition-menu-button></media-rendition-menu-button>
    <media-fullscreen-button></media-fullscreen-button>
  </media-control-bar>
</media-controller>

config prop

Pass PeerTube embed URL parameters via the config property to customize player behavior:

const player = document.querySelector('peertube-video');
player.config = {
  p2p: 0,             // disable P2P
  mode: 'web-video',  // 'web-video' (MP4) or 'p2p-media-loader' (HLS/ABR)
  subtitle: 'en',     // auto-select caption language on load
  playbackRate: 1.5,  // initial playback speed
};

| Option | Type | Description | | ------ | ---- | ----------- | | p2p | 0 \| 1 | Enable/disable P2P (default: 1) | | mode | 'web-video' \| 'p2p-media-loader' | Player engine. Use p2p-media-loader for HLS and adaptive bitrate | | subtitle | string | ISO language code to auto-select on load (e.g. 'en', 'fr') | | playbackRate | number | Initial playback speed (e.g. 0.75, 1.5) | | playlistPosition | number | Starting position in a playlist (1-based) | | waitPasswordFromEmbedAPI | 0 \| 1 | Delay load until password is supplied via api.setVideoPassword() | | peertubeLink | 0 \| 1 | Show/hide the PeerTube instance link | | title | 0 \| 1 | Show/hide the video title overlay | | warningTitle | 0 \| 1 | Show/hide the P2P warning | | controlBar | 0 \| 1 | Show/hide the native control bar during playback | | start | number | Start time in seconds | | stop | number | Stop time in seconds | | bigPlayBackgroundColor | string | Play button background color | | foregroundColor | string | Text/icon foreground color |

Related

• Media Chrome Your media player's dancing suit. 🕺
• <youtube-video> A custom element for the YouTube player.
• <spotify-audio> A custom element for the Spotify player.
• <jwplayer-video> A custom element for the JW player.
• <videojs-video> A custom element for Video.js.
• <wistia-video> A custom element for the Wistia player.
• <cloudflare-video> A custom element for the Cloudflare player.
• <hls-video> A custom element for playing HTTP Live Streaming (HLS) videos.
• castable-video Cast your video element to the big screen with ease!
• <mux-player> The official Mux-flavored video player custom element.
• <mux-video> A Mux-flavored HTML5 video element w/ hls.js and Mux data builtin.