3 PeerTube lets you embed videos and programmatically control their playback. This documentation covers how to interact with the PeerTube Embed API.
7 Any PeerTube embed URL (ie `https://my-instance.example.com/videos/embed/52a10666-3a18-4e73-93da-e8d3c12c305a`) can be viewed as an embedding playground which
8 allows you to test various aspects of PeerTube embeds. Simply replace `/embed` with `/test-embed` and visit the URL in a browser.
9 For instance, the playground URL for the above embed URL is `https://my-instance.example.com/videos/test-embed/52a10666-3a18-4e73-93da-e8d3c12c305a`.
13 Given an existing PeerTube embed `<iframe>` **with API enabled** (`https://my-instance.example.com/videos/embed/52a10666-3a18-4e73-93da-e8d3c12c305a?api=1`),
14 one can use the PeerTube Embed API to control it by first including the library. You can include it via Yarn with:
17 yarn add @peertube/embed-api
20 Now just use the `PeerTubePlayer` class exported by the module:
23 import { PeerTubePlayer } from '@peertube/embed-api'
28 Or use the minified build from NPM CDN in your HTML file:
31 <script src="https://unpkg.com/@peertube/embed-api/build/player.min.js"></script>
34 const PeerTubePlayer = window['PeerTubePlayer']
40 Then you can instantiate the player:
43 let player = new PeerTubePlayer(document.querySelector('iframe'))
44 await player.ready // wait for the player to be ready
46 // now you can use it!
54 You can customize PeerTube player by specifying URL query parameters.
55 For example `https://my-instance.example.com/videos/embed/52a10666-3a18-4e73-93da-e8d3c12c305a??start=1s&stop=18s&loop=1&autoplay=1&muted=1&warningTitle=0&controlBar=0&peertubeLink=0&p2p=0`
59 Start the video at a specific time.
60 Value must be raw seconds or a duration (`3m4s`)
64 Stop the video at a specific time.
65 Value must be raw seconds or a duration (`54s`)
69 Mimics video HTML element `controls` attribute, meaning that all controls (including big play button, control bar, etc.) will be removed.
70 It can be useful if you want to have a full control of the PeerTube player.
72 Value must be `0` or `1`.
76 Hide control bar when the video is played.
78 Value must be `0` or `1`.
82 Hide PeerTube instance link in control bar.
84 Value must be `0` or `1`.
88 Mute the video by default.
90 Value must be `0` or `1`.
94 Automatically start again the video when it ends.
96 Value must be `0` or `1`.
100 Auto select a subtitle by default.
102 Value must be a valid subtitle ISO code (`fr`, `en`, etc.).
106 Try to automatically play the video.
107 Most web browsers disable video autoplay if the user did not interact with the video. You can try to bypass this limitation by muting the video
109 Value must be `0` or `1`.
115 Value must be `0` or `1`.
119 Hide P2P warning title.
121 Value must be `0` or `1`.
127 Value must be `0` or `1`.
129 ## bigPlayBackgroundColor
131 Customize big play button background color.
133 Value must be a valid color (`red` or `rgba(100, 100, 100, 0.5)`).
137 Customize embed font color.
139 Value must be a valid color (`red` or `rgba(100, 100, 100, 0.5)`).
143 Force a specific player engine.
145 Value must be a valid mode (`webtorrent` or `p2p-media-loader`).
149 Enable embed JavaScript API (see methods below).
151 Value must be `0` or `1`.
156 ## `play() : Promise<void>`
158 Starts playback, or resumes playback if it is paused.
160 ## `pause() : Promise<void>`
164 ## `seek(positionInSeconds : number)`
166 Seek to the given position, as specified in seconds into the video.
168 ## `addEventListener(eventName : string, handler : Function)`
170 Add a listener for a specific event. See below for the available events.
172 ## `getResolutions() : Promise<PeerTubeResolution[]>`
174 Get the available resolutions. A `PeerTubeResolution` looks like:
185 `active` is true if the resolution is the currently selected resolution.
187 ## `setResolution(resolutionId : number): Promise<void>`
189 Change the current resolution. Pass `-1` for automatic resolution (when available).
190 Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
192 ## `getPlaybackRates() : Promise<number[]>`
194 Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
196 ## `getPlaybackRates() : Promise<number>`
198 Get the current playback rate. See `getPlaybackRates()` for more information.
200 ## `setPlaybackRate(rate: number) : Promise<void>`
202 Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
204 ## `setVolume(factor: number) : Promise<void>`
206 Set the playback volume. Value should be between `0` and `1`.
208 ## `getVolume(): Promise<number>`
210 Get the playback volume. Returns a value between `0` and `1`.
212 ## `setCaption(id: string) : Promise<void>`
214 Update current caption using the caption id.
216 ## `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>`
220 ## `playNextVideo(): Promise<void>`
222 Play next video in playlist.
224 ## `playPreviousVideo(): Promise<void>`
226 Play previous video in playlist.
228 ## `getCurrentPosition(): Promise<void>`
230 Get current position in playlist (starts from 1).
234 You can subscribe to events by using `addEventListener()`. See above for details.
236 ## Event `playbackStatusUpdate`
238 Fired every half second to provide the current status of playback.
239 The parameter of the callback will resemble:
245 "duration": "171.37499",
246 "playbackState": "playing"
250 `duration` field and `ended` `playbackState` are available in PeerTube >= 2.2.
252 The `volume` field contains the volume from `0` (silent) to `1` (full volume).
253 The `playbackState` can be `unstarted`, `playing`, `paused` or `ended`. More states may be added later.
255 ## Event `playbackStatusChange`
257 Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later.
259 ## Event `resolutionUpdate`
261 Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.
263 ## Event `volumeChange`
265 Fired when the player volume changed.