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 # 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 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
 105 # Methods
 106
 107 ## `play() : Promise<void>`
 108
 109 Starts playback, or resumes playback if it is paused.
 110
 111 ## `pause() : Promise<void>`
 112
 113 Pauses playback.
 114
 115 ## `seek(positionInSeconds : number)`
 116
 117 Seek to the given position, as specified in seconds into the video.
 118
 119 ## `addEventListener(eventName : string, handler : Function)`
 120
 121 Add a listener for a specific event. See below for the available events.
 122
 123 ## `getResolutions() : Promise<PeerTubeResolution[]>`
 124
 125 Get the available resolutions. A `PeerTubeResolution` looks like:
 126
 127 ```json
 128 {
 129     "id": 3,
 130     "label": "720p",
 131     "height": "720",
 132     "active": true
 133 }
 134 ```
 135
 136 `active` is true if the resolution is the currently selected resolution.
 137
 138 ## `setResolution(resolutionId : number): Promise<void>`
 139
 140 Change the current resolution. Pass `-1` for automatic resolution (when available).
 141 Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
 142
 143 ## `getPlaybackRates() : Promise<number[]>`
 144
 145 Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
 146
 147 ## `getPlaybackRates() : Promise<number>`
 148
 149 Get the current playback rate. See `getPlaybackRates()` for more information.
 150
 151 ## `setPlaybackRate(rate: number) : Promise<void>`
 152
 153 Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
 154
 155 ## `setVolume(factor: number) : Promise<void>`
 156
 157 Set the playback volume. Value should be between `0` and `1`.
 158
 159 ## `getVolume(): Promise<number>`
 160
 161 Get the playback volume. Returns a value between `0` and `1`.
 162
 163 ## `setCaption(id: string) : Promise<void>`
 164
 165 Update current caption using the caption id.
 166
 167 ## `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>`
 168
 169 Get video captions.
 170
 171 ## `playNextVideo(): Promise<void>`
 172
 173 Play next video in playlist.
 174
 175 ## `playPreviousVideo(): Promise<void>`
 176
 177 Play previous video in playlist.
 178
 179 ## `getCurrentPosition(): Promise<void>`
 180
 181 Get current position in playlist (starts from 1).
 182
 183 # Events
 184
 185 You can subscribe to events by using `addEventListener()`. See above for details.
 186
 187 ## Event `playbackStatusUpdate`
 188
 189 Fired every half second to provide the current status of playback.
 190 The parameter of the callback will resemble:
 191
 192 ```json
 193 {
 194   "position": 22.3,
 195   "volume": 0.9,
 196   "duration": "171.37499",
 197   "playbackState": "playing"
 198 }
 199 ```
 200
 201 `duration` field and `ended` `playbackState` are available in PeerTube >= 2.2.
 202
 203 The `volume` field contains the volume from `0` (silent) to `1` (full volume).
 204 The `playbackState` can be `unstarted`, `playing`, `paused` or `ended`. More states may be added later.
 205
 206 ## Event `playbackStatusChange`
 207
 208 Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later.
 209
 210 ## Event `resolutionUpdate`
 211
 212 Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.
 213
 214 ## Event `volumeChange`
 215
 216 Fired when the player volume changed.