[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()
```

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

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

# 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	# Methods
	53
	54	## `play() : Promise<void>`
	55
	56	Starts playback, or resumes playback if it is paused.
	57
	58	## `pause() : Promise<void>`
	59
	60	Pauses playback.
	61
	62	## `seek(positionInSeconds : number)`
	63
	64	Seek to the given position, as specified in seconds into the video.
	65
	66	## `addEventListener(eventName : string, handler : Function)`
	67
	68	Add a listener for a specific event. See below for the available events.
	69
	70	## `getResolutions() : Promise<PeerTubeResolution[]>`
	71
	72	Get the available resolutions. A `PeerTubeResolution` looks like:
	73
	74	```json
	75	{
	76	"id": 3,
	77	"label": "720p",
	78	"height": "720",
	79	"active": true
	80	}
	81	```
	82
	83	`active` is true if the resolution is the currently selected resolution.
	84
	85	## `setResolution(resolutionId : number): Promise<void>`
	86
	87	Change the current resolution. Pass `-1` for automatic resolution (when available).
	88	Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
	89
	90	## `getPlaybackRates() : Promise<number[]>`
	91
	92	Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
	93
	94	## `getPlaybackRates() : Promise<number>`
	95
	96	Get the current playback rate. See `getPlaybackRates()` for more information.
	97
	98	## `setPlaybackRate(rate: number) : Promise<void>`
	99
	100	Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
	101
	102	## `setVolume(factor: number) : Promise<void>`
	103
	104	Set the playback volume. Value should be between `0` and `1`.
	105
	106	## `getVolume(): Promise<number>`
	107
	108	Get the playback volume. Returns a value between `0` and `1`.
	109
	110	## `setCaption(id: string) : Promise<void>`
	111
	112	Update current caption using the caption id.
	113
	114	## `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' \| 'showing' }>`
	115
	116	Get video captions.
	117
	118	# Events
	119
	120	You can subscribe to events by using `addEventListener()`. See above for details.
	121
	122	## Event `playbackStatusUpdate`
	123
	124	Fired every half second to provide the current status of playback.
	125	The parameter of the callback will resemble:
	126
	127	```json
	128	{
	129	"position": 22.3,
	130	"volume": 0.9,
	131	"duration": "171.37499",
	132	"playbackState": "playing"
	133	}
	134	```
	135
	136	`duration` field and `ended` `playbackState` are available in PeerTube >= 2.2.
	137
	138	The `volume` field contains the volume from `0` (silent) to `1` (full volume).
	139	The `playbackState` can be `unstarted`, `playing`, `paused` or `ended`. More states may be added later.
	140
	141	## Event `playbackStatusChange`
	142
	143	Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later.
	144
	145	## Event `resolutionUpdate`
	146
	147	Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.
	148
	149	## Event `volumeChange`
	150
	151	Fired when the player volume changed.