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 ## `removeEventListener(eventName : string, handler : Function)`
176 ## `getResolutions() : Promise<PeerTubeResolution[]>`
178 Get the available resolutions. A `PeerTubeResolution` looks like:
189 `active` is true if the resolution is the currently selected resolution.
191 ## `setResolution(resolutionId : number): Promise<void>`
193 Change the current resolution. Pass `-1` for automatic resolution (when available).
194 Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
196 ## `getPlaybackRates() : Promise<number[]>`
198 Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
200 ## `getPlaybackRates() : Promise<number>`
202 Get the current playback rate. See `getPlaybackRates()` for more information.
204 ## `setPlaybackRate(rate: number) : Promise<void>`
206 Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
208 ## `setVolume(factor: number) : Promise<void>`
210 Set the playback volume. Value should be between `0` and `1`.
212 ## `getVolume(): Promise<number>`
214 Get the playback volume. Returns a value between `0` and `1`.
216 ## `setCaption(id: string) : Promise<void>`
218 Update current caption using the caption id.
220 ## `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>`
224 ## `playNextVideo(): Promise<void>`
226 Play next video in playlist.
228 ## `playPreviousVideo(): Promise<void>`
230 Play previous video in playlist.
232 ## `getCurrentPosition(): Promise<void>`
234 Get current position in playlist (starts from 1).
238 You can subscribe to events by using `addEventListener()`. See above for details.
240 ## Event `playbackStatusUpdate`
242 Fired every half second to provide the current status of playback.
243 The parameter of the callback will resemble:
249 "duration": "171.37499",
250 "playbackState": "playing"
254 `duration` field and `ended` `playbackState` are available in PeerTube >= 2.2.
256 The `volume` field contains the volume from `0` (silent) to `1` (full volume).
257 The `playbackState` can be `unstarted`, `playing`, `paused` or `ended`. More states may be added later.
259 ## Event `playbackStatusChange`
261 Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later.
263 ## Event `resolutionUpdate`
265 Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.
267 ## Event `volumeChange`
269 Fired when the player volume changed.