]>
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 | # 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 | # 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 | ## `getResolutions() : Promise<PeerTubeResolution[]>` | |
173 | ||
174 | Get the available resolutions. A `PeerTubeResolution` looks like: | |
175 | ||
176 | ```json | |
177 | { | |
178 | "id": 3, | |
179 | "label": "720p", | |
180 | "height": "720", | |
181 | "active": true | |
182 | } | |
183 | ``` | |
184 | ||
185 | `active` is true if the resolution is the currently selected resolution. | |
186 | ||
187 | ## `setResolution(resolutionId : number): Promise<void>` | |
188 | ||
189 | Change the current resolution. Pass `-1` for automatic resolution (when available). | |
190 | Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()` | |
191 | ||
192 | ## `getPlaybackRates() : Promise<number[]>` | |
193 | ||
194 | Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc. | |
195 | ||
196 | ## `getPlaybackRates() : Promise<number>` | |
197 | ||
198 | Get the current playback rate. See `getPlaybackRates()` for more information. | |
199 | ||
200 | ## `setPlaybackRate(rate: number) : Promise<void>` | |
201 | ||
202 | Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`. | |
203 | ||
204 | ## `setVolume(factor: number) : Promise<void>` | |
205 | ||
206 | Set the playback volume. Value should be between `0` and `1`. | |
207 | ||
208 | ## `getVolume(): Promise<number>` | |
209 | ||
210 | Get the playback volume. Returns a value between `0` and `1`. | |
211 | ||
212 | ## `setCaption(id: string) : Promise<void>` | |
213 | ||
214 | Update current caption using the caption id. | |
215 | ||
216 | ## `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>` | |
217 | ||
218 | Get video captions. | |
219 | ||
220 | ## `playNextVideo(): Promise<void>` | |
221 | ||
222 | Play next video in playlist. | |
223 | ||
224 | ## `playPreviousVideo(): Promise<void>` | |
225 | ||
226 | Play previous video in playlist. | |
227 | ||
228 | ## `getCurrentPosition(): Promise<void>` | |
229 | ||
230 | Get current position in playlist (starts from 1). | |
231 | ||
232 | # Events | |
233 | ||
234 | You can subscribe to events by using `addEventListener()`. See above for details. | |
235 | ||
236 | ## Event `playbackStatusUpdate` | |
237 | ||
238 | Fired every half second to provide the current status of playback. | |
239 | The parameter of the callback will resemble: | |
240 | ||
241 | ```json | |
242 | { | |
243 | "position": 22.3, | |
244 | "volume": 0.9, | |
245 | "duration": "171.37499", | |
246 | "playbackState": "playing" | |
247 | } | |
248 | ``` | |
249 | ||
250 | `duration` field and `ended` `playbackState` are available in PeerTube >= 2.2. | |
251 | ||
252 | The `volume` field contains the volume from `0` (silent) to `1` (full volume). | |
253 | The `playbackState` can be `unstarted`, `playing`, `paused` or `ended`. More states may be added later. | |
254 | ||
255 | ## Event `playbackStatusChange` | |
256 | ||
257 | Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later. | |
258 | ||
259 | ## Event `resolutionUpdate` | |
260 | ||
261 | Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information. | |
262 | ||
263 | ## Event `volumeChange` | |
264 | ||
265 | Fired when the player volume changed. |