]> git.immae.eu Git - github/Chocobozzz/PeerTube.git/blame - support/doc/api/embeds.md
Translated using Weblate (Polish)
[github/Chocobozzz/PeerTube.git] / support / doc / api / embeds.md
CommitLineData
99941732
WL
1# PeerTube Embed API
2
3PeerTube lets you embed videos and programmatically control their playback. This documentation covers how to interact with the PeerTube Embed API.
4
5## Playground
6
1151f521
C
7Any PeerTube embed URL (ie `https://my-instance.example.com/videos/embed/52a10666-3a18-4e73-93da-e8d3c12c305a`) can be viewed as an embedding playground which
8allows you to test various aspects of PeerTube embeds. Simply replace `/embed` with `/test-embed` and visit the URL in a browser.
99941732
WL
9For 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
9a207a71
C
13Given an existing PeerTube embed `<iframe>` **with API enabled** (`https://my-instance.example.com/videos/embed/52a10666-3a18-4e73-93da-e8d3c12c305a?api=1`),
14one can use the PeerTube Embed API to control it by first including the library. You can include it via Yarn with:
99941732
WL
15
16```
17yarn add @peertube/embed-api
18```
19
20Now just use the `PeerTubePlayer` class exported by the module:
21
22```typescript
23import { PeerTubePlayer } from '@peertube/embed-api'
24
03d641a0
C
25...
26```
27
28Or use the minified build from NPM CDN in your HTML file:
29
30```
afd1a6ed 31<script src="https://unpkg.com/@peertube/embed-api/build/player.min.js"></script>
03d641a0
C
32
33<script>
34 const PeerTubePlayer = window['PeerTubePlayer']
35
36 ...
37</script>
38```
39
40Then you can instantiate the player:
41
42```typescript
99941732
WL
43let player = new PeerTubePlayer(document.querySelector('iframe'))
44await player.ready // wait for the player to be ready
45
46// now you can use it!
47player.play()
48player.seek(32)
b2b0ce8a 49player.pause()
99941732
WL
50```
51
52# Methods
53
54## `play() : Promise<void>`
55
56Starts playback, or resumes playback if it is paused.
57
58## `pause() : Promise<void>`
59
60Pauses playback.
61
62## `seek(positionInSeconds : number)`
63
64Seek to the given position, as specified in seconds into the video.
65
66## `addEventListener(eventName : string, handler : Function)`
67
68Add a listener for a specific event. See below for the available events.
69
70## `getResolutions() : Promise<PeerTubeResolution[]>`
71
72Get the available resolutions. A `PeerTubeResolution` looks like:
73
74```json
75{
76 "id": 3,
77 "label": "720p",
03d641a0 78 "height": "720",
99941732
WL
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
87Change the current resolution. Pass `-1` for automatic resolution (when available).
88Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
89
90## `getPlaybackRates() : Promise<number[]>`
91
92Get 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
96Get the current playback rate. See `getPlaybackRates()` for more information.
97
1151f521 98## `setPlaybackRate(rate: number) : Promise<void>`
99941732
WL
99
100Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
101
1151f521 102## `setVolume(factor: number) : Promise<void>`
99941732
WL
103
104Set the playback volume. Value should be between `0` and `1`.
105
106## `getVolume(): Promise<number>`
107
108Get the playback volume. Returns a value between `0` and `1`.
03d641a0 109
1151f521
C
110## `setCaption(id: string) : Promise<void>`
111
112Update current caption using the caption id.
113
114## `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>`
115
116Get video captions.
117
9054a8b6
C
118## `playNextVideo(): Promise<void>`
119
120Play next video in playlist.
121
122## `playPreviousVideo(): Promise<void>`
123
124Play previous video in playlist.
125
126## `getCurrentPosition(): Promise<void>`
127
128Get current position in playlist (starts from 1).
129
99941732
WL
130# Events
131
132You can subscribe to events by using `addEventListener()`. See above for details.
133
99941732
WL
134## Event `playbackStatusUpdate`
135
1151f521 136Fired every half second to provide the current status of playback.
6ccdf9d5 137The parameter of the callback will resemble:
99941732
WL
138
139```json
140{
141 "position": 22.3,
142 "volume": 0.9,
6ccdf9d5 143 "duration": "171.37499",
99941732
WL
144 "playbackState": "playing"
145}
146```
147
624a0221
C
148`duration` field and `ended` `playbackState` are available in PeerTube >= 2.2.
149
96aae68c
C
150The `volume` field contains the volume from `0` (silent) to `1` (full volume).
151The `playbackState` can be `unstarted`, `playing`, `paused` or `ended`. More states may be added later.
99941732
WL
152
153## Event `playbackStatusChange`
154
5ab994fe 155Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later.
99941732
WL
156
157## Event `resolutionUpdate`
158
478924a0
C
159Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.
160
161## Event `volumeChange`
162
163Fired when the player volume changed.