[github/Chocobozzz/PeerTube.git] / support / doc / api / embeds.md

# 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

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.
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

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:

```
yarn add @peertube/embed-api
```

Now just use the `PeerTubePlayer` class exported by the module:

```typescript
import { PeerTubePlayer } from '@peertube/embed-api'

...
```

Or use the minified build from NPM CDN in your HTML file:

```
<script src="https://unpkg.com/@peertube/embed-api/build/player.min.js"></script>

<script>
  const PeerTubePlayer = window['PeerTubePlayer']

  ...
</script>
```

Then you can instantiate the player:

```typescript
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)
player.pause()
```

## Embed URL parameters

You can customize PeerTube player by specifying URL query parameters.
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`

### start

Start the video at a specific time.
Value must be raw seconds or a duration (`3m4s`)

### stop

Stop the video at a specific time.
Value must be raw seconds or a duration (`54s`)

### controls

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`.

### controlBar

Hide control bar when the video is played.

Value must be `0` or `1`.

### peertubeLink

Hide PeerTube instance link in control bar.

Value must be `0` or `1`.

### muted

Mute the video by default.

Value must be `0` or `1`.

### loop

Automatically start again the video when it ends.

Value must be `0` or `1`.

### subtitle

Auto select a subtitle by default.

Value must be a valid subtitle ISO code (`fr`, `en`, etc.).

### autoplay

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`.

### title

Hide embed title.

Value must be `0` or `1`.

### warningTitle

Hide P2P warning title.

Value must be `0` or `1`.

### p2p

Disable P2P.

Value must be `0` or `1`.

### bigPlayBackgroundColor

Customize big play button background color.

Value must be a valid color (`red` or `rgba(100, 100, 100, 0.5)`).

### foregroundColor

Customize embed font color.

Value must be a valid color (`red` or `rgba(100, 100, 100, 0.5)`).

### mode

Force a specific player engine.

Value must be a valid mode (`webtorrent` or `p2p-media-loader`).

### api

Enable embed JavaScript API (see methods below).

Value must be `0` or `1`.


## Embed methods

### `play() : Promise<void>`

Starts playback, or resumes playback if it is paused.

### `pause() : Promise<void>`

Pauses playback.

### `seek(positionInSeconds : number)`

Seek to the given position, as specified in seconds into the video.

### `addEventListener(eventName : string, handler : Function)`

Add a listener for a specific event. See below for the available events.

### `removeEventListener(eventName : string, handler : Function)`

Remove a listener.

### `getResolutions() : Promise<PeerTubeResolution[]>`

Get the available resolutions. A `PeerTubeResolution` looks like:

```json
{
    "id": 3,
    "label": "720p",
    "height": "720",
    "active": true
}
```

`active` is true if the resolution is the currently selected resolution.

### `setResolution(resolutionId : number): Promise<void>`

Change the current resolution. Pass `-1` for automatic resolution (when available).
Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`

### `getPlaybackRates() : Promise<number[]>`

Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.

### `getPlaybackRates() : Promise<number>`

Get the current playback rate. See `getPlaybackRates()` for more information.

### `setPlaybackRate(rate: number) : Promise<void>`

Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.

### `setVolume(factor: number) : Promise<void>`

Set the playback volume. Value should be between `0` and `1`.

### `getVolume(): Promise<number>`

Get the playback volume. Returns a value between `0` and `1`.

### `setCaption(id: string) : Promise<void>`

Update current caption using the caption id.

### `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>`

Get video captions.

### `playNextVideo(): Promise<void>`

Play next video in playlist.

### `playPreviousVideo(): Promise<void>`

Play previous video in playlist.

### `getCurrentPosition(): Promise<void>`

Get current position in playlist (starts from 1).

## Embed events

You can subscribe to events by using `addEventListener()`. See above for details.

### Event `playbackStatusUpdate`

Fired every half second to provide the current status of playback.
The parameter of the callback will resemble:

```json
{
  "position": 22.3,
  "volume": 0.9,
  "duration": "171.37499",
  "playbackState": "playing"
}
```

`duration` field and `ended` `playbackState` are available in PeerTube >= 2.2.

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.

### Event `playbackStatusChange`

Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later.

### Event `resolutionUpdate`

Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.

### Event `volumeChange`

Fired when the player volume changed.
Commit	Line	Data
	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.