support/doc/api/embeds.md

   1 # PeerTube Embed API
   2
   3 PeerTube lets you embed videos and programmatically control their playback. This documentation covers how to interact with the PeerTube Embed API.
   4
   5 ## Playground
   6
   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`.
  10
  11 ## Quick Start
  12
  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:
  15
  16 ```
  17 yarn add @peertube/embed-api
  18 ```
  19
  20 Now just use the `PeerTubePlayer` class exported by the module:
  21
  22 ```typescript
  23 import { PeerTubePlayer } from '@peertube/embed-api'
  24
  25 ...
  26 ```
  27
  28 Or use the minified build from NPM CDN in your HTML file:
  29
  30 ```
  31 <script src="https://unpkg.com/@peertube/embed-api/build/player.min.js"></script>
  32
  33 <script>
  34   const PeerTubePlayer = window['PeerTubePlayer']
  35
  36   ...
  37 </script>
  38 ```
  39
  40 Then you can instantiate the player:
  41
  42 ```typescript
  43 let player = new PeerTubePlayer(document.querySelector('iframe'))
  44 await player.ready // wait for the player to be ready
  45
  46 // now you can use it!
  47 player.play()
  48 player.seek(32)
  49 player.pause()
  50 ```
  51
  52 ## Embed URL parameters
  53
  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`
  56
  57 ### start
  58
  59 Start the video at a specific time.
  60 Value must be raw seconds or a duration (`3m4s`)
  61
  62 ### stop
  63
  64 Stop the video at a specific time.
  65 Value must be raw seconds or a duration (`54s`)
  66
  67 ### controls
  68
  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.
  71
  72 Value must be `0` or `1`.
  73
  74 ### controlBar
  75
  76 Hide control bar when the video is played.
  77
  78 Value must be `0` or `1`.
  79
  80 ### peertubeLink
  81
  82 Hide PeerTube instance link in control bar.
  83
  84 Value must be `0` or `1`.
  85
  86 ### muted
  87
  88 Mute the video by default.
  89
  90 Value must be `0` or `1`.
  91
  92 ### loop
  93
  94 Automatically start again the video when it ends.
  95
  96 Value must be `0` or `1`.
  97
  98 ### subtitle
  99
 100 Auto select a subtitle by default.
 101
 102 Value must be a valid subtitle ISO code (`fr`, `en`, etc.).
 103
 104 ### autoplay
 105
 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
 108
 109 Value must be `0` or `1`.
 110
 111 ### title
 112
 113 Hide embed title.
 114
 115 Value must be `0` or `1`.
 116
 117 ### warningTitle
 118
 119 Hide P2P warning title.
 120
 121 Value must be `0` or `1`.
 122
 123 ### p2p
 124
 125 Disable P2P.
 126
 127 Value must be `0` or `1`.
 128
 129 ### bigPlayBackgroundColor
 130
 131 Customize big play button background color.
 132
 133 Value must be a valid color (`red` or `rgba(100, 100, 100, 0.5)`).
 134
 135 ### foregroundColor
 136
 137 Customize embed font color.
 138
 139 Value must be a valid color (`red` or `rgba(100, 100, 100, 0.5)`).
 140
 141 ### mode
 142
 143 Force a specific player engine.
 144
 145 Value must be a valid mode (`webtorrent` or `p2p-media-loader`).
 146
 147 ### api
 148
 149 Enable embed JavaScript API (see methods below).
 150
 151 Value must be `0` or `1`.
 152
 153
 154 ## Embed methods
 155
 156 ### `play() : Promise<void>`
 157
 158 Starts playback, or resumes playback if it is paused.
 159
 160 ### `pause() : Promise<void>`
 161
 162 Pauses playback.
 163
 164 ### `seek(positionInSeconds : number)`
 165
 166 Seek to the given position, as specified in seconds into the video.
 167
 168 ### `addEventListener(eventName : string, handler : Function)`
 169
 170 Add a listener for a specific event. See below for the available events.
 171
 172 ### `removeEventListener(eventName : string, handler : Function)`
 173
 174 Remove a listener.
 175
 176 ### `getResolutions() : Promise<PeerTubeResolution[]>`
 177
 178 Get the available resolutions. A `PeerTubeResolution` looks like:
 179
 180 ```json
 181 {
 182     "id": 3,
 183     "label": "720p",
 184     "height": "720",
 185     "active": true
 186 }
 187 ```
 188
 189 `active` is true if the resolution is the currently selected resolution.
 190
 191 ### `setResolution(resolutionId : number): Promise<void>`
 192
 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()`
 195
 196 ### `getPlaybackRates() : Promise<number[]>`
 197
 198 Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
 199
 200 ### `getPlaybackRates() : Promise<number>`
 201
 202 Get the current playback rate. See `getPlaybackRates()` for more information.
 203
 204 ### `setPlaybackRate(rate: number) : Promise<void>`
 205
 206 Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
 207
 208 ### `setVolume(factor: number) : Promise<void>`
 209
 210 Set the playback volume. Value should be between `0` and `1`.
 211
 212 ### `getVolume(): Promise<number>`
 213
 214 Get the playback volume. Returns a value between `0` and `1`.
 215
 216 ### `setCaption(id: string) : Promise<void>`
 217
 218 Update current caption using the caption id.
 219
 220 ### `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>`
 221
 222 Get video captions.
 223
 224 ### `playNextVideo(): Promise<void>`
 225
 226 Play next video in playlist.
 227
 228 ### `playPreviousVideo(): Promise<void>`
 229
 230 Play previous video in playlist.
 231
 232 ### `getCurrentPosition(): Promise<void>`
 233
 234 Get current position in playlist (starts from 1).
 235
 236 ## Embed events
 237
 238 You can subscribe to events by using `addEventListener()`. See above for details.
 239
 240 ### Event `playbackStatusUpdate`
 241
 242 Fired every half second to provide the current status of playback.
 243 The parameter of the callback will resemble:
 244
 245 ```json
 246 {
 247   "position": 22.3,
 248   "volume": 0.9,
 249   "duration": "171.37499",
 250   "playbackState": "playing"
 251 }
 252 ```
 253
 254 `duration` field and `ended` `playbackState` are available in PeerTube >= 2.2.
 255
 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.
 258
 259 ### Event `playbackStatusChange`
 260
 261 Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later.
 262
 263 ### Event `resolutionUpdate`
 264
 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.
 266
 267 ### Event `volumeChange`
 268
 269 Fired when the player volume changed.