2018-07-10 17:47:56 +02:00
# PeerTube Embed API
PeerTube lets you embed videos and programmatically control their playback. This documentation covers how to interact with the PeerTube Embed API.
## Playground
2020-05-06 11:54:33 +02:00
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
allows you to test various aspects of PeerTube embeds. Simply replace `/embed` with `/test-embed` and visit the URL in a browser.
2018-07-10 17:47:56 +02:00
For instance, the playground URL for the above embed URL is `https://my-instance.example.com/videos/test-embed/52a10666-3a18-4e73-93da-e8d3c12c305a` .
## Quick Start
2020-02-28 14:01:17 +01:00
Given an existing PeerTube embed `<iframe>` **with API enabled** (`https://my-instance.example.com/videos/embed/52a10666-3a18-4e73-93da-e8d3c12c305a?api=1`),
one can use the PeerTube Embed API to control it by first including the library. You can include it via Yarn with:
2018-07-10 17:47:56 +02:00
```
yarn add @peertube/embed -api
```
Now just use the `PeerTubePlayer` class exported by the module:
```typescript
import { PeerTubePlayer } from '@peertube/embed-api'
2019-12-17 16:17:22 +01:00
...
```
Or use the minified build from NPM CDN in your HTML file:
```
2020-04-08 14:44:25 +02:00
< script src = "https://unpkg.com/@peertube/embed-api/build/player.min.js" > < / script >
2019-12-17 16:17:22 +01:00
< script >
const PeerTubePlayer = window['PeerTubePlayer']
...
< / script >
```
Then you can instantiate the player:
```typescript
2018-07-10 17:47:56 +02:00
let player = new PeerTubePlayer(document.querySelector('iframe'))
await player.ready // wait for the player to be ready
// now you can use it!
player.play()
player.seek(32)
2020-03-25 13:32:29 +01:00
player.pause()
2018-07-10 17:47:56 +02:00
```
2023-02-22 16:06:25 +01:00
## Embed URL parameters
2022-05-20 09:59:53 +02:00
You can customize PeerTube player by specifying URL query parameters.
2023-06-19 09:05:20 +02:00
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`
2022-05-20 09:59:53 +02:00
2023-02-22 16:06:25 +01:00
### start
2022-05-20 09:59:53 +02:00
Start the video at a specific time.
Value must be raw seconds or a duration (`3m4s`)
2023-02-22 16:06:25 +01:00
### stop
2022-05-20 09:59:53 +02:00
Stop the video at a specific time.
Value must be raw seconds or a duration (`54s`)
2023-02-22 16:06:25 +01:00
### controls
2022-05-20 09:59:53 +02:00
Mimics video HTML element `controls` attribute, meaning that all controls (including big play button, control bar, etc.) will be removed.
It can be useful if you want to have a full control of the PeerTube player.
Value must be `0` or `1` .
2023-02-22 16:06:25 +01:00
### controlBar
2022-05-20 09:59:53 +02:00
Hide control bar when the video is played.
Value must be `0` or `1` .
2023-02-22 16:06:25 +01:00
### peertubeLink
2022-05-20 09:59:53 +02:00
2022-06-28 14:49:05 +02:00
Hide PeerTube instance link in control bar.
2022-05-20 09:59:53 +02:00
Value must be `0` or `1` .
2023-02-22 16:06:25 +01:00
### muted
2022-05-20 09:59:53 +02:00
Mute the video by default.
Value must be `0` or `1` .
2023-02-22 16:06:25 +01:00
### loop
2022-05-20 09:59:53 +02:00
Automatically start again the video when it ends.
Value must be `0` or `1` .
2023-02-22 16:06:25 +01:00
### subtitle
2022-05-20 09:59:53 +02:00
Auto select a subtitle by default.
Value must be a valid subtitle ISO code (`fr`, `en` , etc.).
2023-02-22 16:06:25 +01:00
### autoplay
2022-06-28 14:49:05 +02:00
Try to automatically play the video.
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
Value must be `0` or `1` .
2023-06-19 09:05:20 +02:00
### playbackRate
Force the default playback rate (`0.75`, `1.5` etc).
2023-02-22 16:06:25 +01:00
### title
2022-06-28 14:49:05 +02:00
Hide embed title.
Value must be `0` or `1` .
2023-02-22 16:06:25 +01:00
### warningTitle
2022-06-28 14:49:05 +02:00
Hide P2P warning title.
Value must be `0` or `1` .
2023-02-22 16:06:25 +01:00
### p2p
2022-06-28 14:49:05 +02:00
Disable P2P.
Value must be `0` or `1` .
2023-02-22 16:06:25 +01:00
### bigPlayBackgroundColor
2022-06-28 14:49:05 +02:00
Customize big play button background color.
Value must be a valid color (`red` or `rgba(100, 100, 100, 0.5)` ).
2023-02-22 16:06:25 +01:00
### foregroundColor
2022-06-28 14:49:05 +02:00
Customize embed font color.
Value must be a valid color (`red` or `rgba(100, 100, 100, 0.5)` ).
2023-02-22 16:06:25 +01:00
### mode
2022-06-28 14:49:05 +02:00
Force a specific player engine.
Value must be a valid mode (`webtorrent` or `p2p-media-loader` ).
2023-02-22 16:06:25 +01:00
### api
2022-06-28 14:49:05 +02:00
Enable embed JavaScript API (see methods below).
Value must be `0` or `1` .
2022-05-20 09:59:53 +02:00
2023-02-22 16:06:25 +01:00
## Embed methods
2018-07-10 17:47:56 +02:00
2023-02-22 16:06:25 +01:00
### `play() : Promise<void>`
2018-07-10 17:47:56 +02:00
Starts playback, or resumes playback if it is paused.
2023-02-22 16:06:25 +01:00
### `pause() : Promise<void>`
2018-07-10 17:47:56 +02:00
Pauses playback.
2023-02-22 16:06:25 +01:00
### `seek(positionInSeconds : number)`
2018-07-10 17:47:56 +02:00
Seek to the given position, as specified in seconds into the video.
2023-02-22 16:06:25 +01:00
### `addEventListener(eventName : string, handler : Function)`
2018-07-10 17:47:56 +02:00
Add a listener for a specific event. See below for the available events.
2023-02-22 16:06:25 +01:00
### `removeEventListener(eventName : string, handler : Function)`
2022-09-09 11:40:14 +02:00
Remove a listener.
2023-02-22 16:06:25 +01:00
### `getResolutions() : Promise<PeerTubeResolution[]>`
2018-07-10 17:47:56 +02:00
Get the available resolutions. A `PeerTubeResolution` looks like:
```json
{
"id": 3,
"label": "720p",
2019-12-17 16:17:22 +01:00
"height": "720",
2018-07-10 17:47:56 +02:00
"active": true
}
```
`active` is true if the resolution is the currently selected resolution.
2023-02-22 16:06:25 +01:00
### `setResolution(resolutionId : number): Promise<void>`
2018-07-10 17:47:56 +02:00
Change the current resolution. Pass `-1` for automatic resolution (when available).
Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
2023-02-22 16:06:25 +01:00
### `getPlaybackRates() : Promise<number[]>`
2018-07-10 17:47:56 +02:00
Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
2023-02-22 16:06:25 +01:00
### `getPlaybackRates() : Promise<number>`
2018-07-10 17:47:56 +02:00
Get the current playback rate. See `getPlaybackRates()` for more information.
2023-02-22 16:06:25 +01:00
### `setPlaybackRate(rate: number) : Promise<void>`
2018-07-10 17:47:56 +02:00
Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()` .
2023-02-22 16:06:25 +01:00
### `setVolume(factor: number) : Promise<void>`
2018-07-10 17:47:56 +02:00
Set the playback volume. Value should be between `0` and `1` .
2023-02-22 16:06:25 +01:00
### `getVolume(): Promise<number>`
2018-07-10 17:47:56 +02:00
Get the playback volume. Returns a value between `0` and `1` .
2019-12-17 16:17:22 +01:00
2023-02-22 16:06:25 +01:00
### `setCaption(id: string) : Promise<void>`
2020-05-06 11:54:33 +02:00
Update current caption using the caption id.
2023-02-22 16:06:25 +01:00
### `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>`
2020-05-06 11:54:33 +02:00
Get video captions.
2023-02-22 16:06:25 +01:00
### `playNextVideo(): Promise<void>`
2020-08-05 14:16:39 +02:00
Play next video in playlist.
2023-02-22 16:06:25 +01:00
### `playPreviousVideo(): Promise<void>`
2020-08-05 14:16:39 +02:00
Play previous video in playlist.
2023-02-22 16:06:25 +01:00
### `getCurrentPosition(): Promise<void>`
2020-08-05 14:16:39 +02:00
Get current position in playlist (starts from 1).
2023-02-22 16:06:25 +01:00
## Embed events
2018-07-10 17:47:56 +02:00
You can subscribe to events by using `addEventListener()` . See above for details.
2023-02-22 16:06:25 +01:00
### Event `playbackStatusUpdate`
2018-07-10 17:47:56 +02:00
2020-05-06 11:54:33 +02:00
Fired every half second to provide the current status of playback.
2020-04-08 14:51:44 +02:00
The parameter of the callback will resemble:
2018-07-10 17:47:56 +02:00
```json
{
"position": 22.3,
"volume": 0.9,
2020-04-08 14:51:44 +02:00
"duration": "171.37499",
2018-07-10 17:47:56 +02:00
"playbackState": "playing"
}
```
2020-04-14 09:02:44 +02:00
`duration` field and `ended` `playbackState` are available in PeerTube >= 2.2.
2020-04-08 14:39:31 +02:00
The `volume` field contains the volume from `0` (silent) to `1` (full volume).
The `playbackState` can be `unstarted` , `playing` , `paused` or `ended` . More states may be added later.
2018-07-10 17:47:56 +02:00
2023-02-22 16:06:25 +01:00
### Event `playbackStatusChange`
2018-07-10 17:47:56 +02:00
2020-03-20 15:04:02 +01:00
Fired when playback transitions between states, such as `paused` and `playing` . More states may be added later.
2018-07-10 17:47:56 +02:00
2023-02-22 16:06:25 +01:00
### Event `resolutionUpdate`
2018-07-10 17:47:56 +02:00
2019-12-17 15:19:42 +01:00
Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.
2023-02-22 16:06:25 +01:00
### Event `volumeChange`
2019-12-17 15:19:42 +01:00
Fired when the player volume changed.