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>`, one can use the PeerTube Embed API to control it by first including the library. You can include it via Yarn with:
  14
  15 ```
  16 yarn add @peertube/embed-api
  17 ```
  18
  19 Now just use the `PeerTubePlayer` class exported by the module:
  20
  21 ```typescript
  22 import { PeerTubePlayer } from '@peertube/embed-api'
  23
  24 ...
  25 ```
  26
  27 Or use the minified build from NPM CDN in your HTML file:
  28
  29 ```
  30 <script src="https://unpkg.com/@peertube/embed-api@0.0.1/build/player.min.js"></script>
  31
  32 <script>
  33   const PeerTubePlayer = window['PeerTubePlayer']
  34
  35   ...
  36 </script>
  37 ```
  38
  39 Then you can instantiate the player:
  40
  41 ```typescript
  42 let player = new PeerTubePlayer(document.querySelector('iframe'))
  43 await player.ready // wait for the player to be ready
  44
  45 // now you can use it!
  46 player.play()
  47 player.seek(32)
  48 player.stop()
  49 ```
  50
  51 # Methods
  52
  53 ## `play() : Promise<void>`
  54
  55 Starts playback, or resumes playback if it is paused.
  56
  57 ## `pause() : Promise<void>`
  58
  59 Pauses playback.
  60
  61 ## `seek(positionInSeconds : number)`
  62
  63 Seek to the given position, as specified in seconds into the video.
  64
  65 ## `addEventListener(eventName : string, handler : Function)`
  66
  67 Add a listener for a specific event. See below for the available events.
  68
  69 ## `getResolutions() : Promise<PeerTubeResolution[]>`
  70
  71 Get the available resolutions. A `PeerTubeResolution` looks like:
  72
  73 ```json
  74 {
  75     "id": 3,
  76     "label": "720p",
  77     "height": "720",
  78     "active": true
  79 }
  80 ```
  81
  82 `active` is true if the resolution is the currently selected resolution.
  83
  84 ## `setResolution(resolutionId : number): Promise<void>`
  85
  86 Change the current resolution. Pass `-1` for automatic resolution (when available).
  87 Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
  88
  89 ## `getPlaybackRates() : Promise<number[]>`
  90
  91 Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
  92
  93 ## `getPlaybackRates() : Promise<number>`
  94
  95 Get the current playback rate. See `getPlaybackRates()` for more information.
  96
  97 ## `setPlaybackRate(rate : number) : Promise<void>`
  98
  99 Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
 100
 101 ## `setVolume(factor : number) : Promise<void>`
 102
 103 Set the playback volume. Value should be between `0` and `1`.
 104
 105 ## `getVolume(): Promise<number>`
 106
 107 Get the playback volume. Returns a value between `0` and `1`.
 108
 109 # Events
 110
 111 You can subscribe to events by using `addEventListener()`. See above for details.
 112
 113 ## Event `play`
 114
 115 Fired when playback begins or is resumed after pausing.
 116
 117 ## Event `pause`
 118
 119 Fired when playback is paused.
 120
 121 ## Event `playbackStatusUpdate`
 122
 123 Fired every half second to provide the current status of playback. The parameter of the callback will resemble:
 124
 125 ```json
 126 {
 127   "position": 22.3,
 128   "volume": 0.9,
 129   "playbackState": "playing"
 130 }
 131 ```
 132
 133 The `volume` field contains the volume from `0` (silent) to `1` (full volume). The `playbackState` can be `playing` or `paused`. More states may be added later.
 134
 135 ## Event `playbackStatusChange`
 136
 137 Fired when playback transitions between states, such as `pausing` and `playing`. More states may be added later.
 138
 139 ## Event `resolutionUpdate`
 140
 141 Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.
 142
 143 ## Event `volumeChange`
 144
 145 Fired when the player volume changed.