]>
Commit | Line | Data |
---|---|---|
99941732 WL |
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>`, one can use the PeerTube Embed API to control it by first including the library. You can include it via Yarn with: | |
14 | ||
15 | ``` | |
16 | yarn add @peertube/embed-api | |
17 | ``` | |
18 | ||
19 | Now just use the `PeerTubePlayer` class exported by the module: | |
20 | ||
21 | ```typescript | |
22 | import { PeerTubePlayer } from '@peertube/embed-api' | |
23 | ||
03d641a0 C |
24 | ... |
25 | ``` | |
26 | ||
27 | Or use the minified build from NPM CDN in your HTML file: | |
28 | ||
29 | ``` | |
30 | <script src="https://unpkg.com/@peertube/embed-api@0.0.1/build/player.min.js"></script> | |
31 | ||
32 | <script> | |
33 | const PeerTubePlayer = window['PeerTubePlayer'] | |
34 | ||
35 | ... | |
36 | </script> | |
37 | ``` | |
38 | ||
39 | Then you can instantiate the player: | |
40 | ||
41 | ```typescript | |
99941732 WL |
42 | let player = new PeerTubePlayer(document.querySelector('iframe')) |
43 | await player.ready // wait for the player to be ready | |
44 | ||
45 | // now you can use it! | |
46 | player.play() | |
47 | player.seek(32) | |
48 | player.stop() | |
49 | ``` | |
50 | ||
51 | # Methods | |
52 | ||
53 | ## `play() : Promise<void>` | |
54 | ||
55 | Starts playback, or resumes playback if it is paused. | |
56 | ||
57 | ## `pause() : Promise<void>` | |
58 | ||
59 | Pauses playback. | |
60 | ||
61 | ## `seek(positionInSeconds : number)` | |
62 | ||
63 | Seek to the given position, as specified in seconds into the video. | |
64 | ||
65 | ## `addEventListener(eventName : string, handler : Function)` | |
66 | ||
67 | Add a listener for a specific event. See below for the available events. | |
68 | ||
69 | ## `getResolutions() : Promise<PeerTubeResolution[]>` | |
70 | ||
71 | Get the available resolutions. A `PeerTubeResolution` looks like: | |
72 | ||
73 | ```json | |
74 | { | |
75 | "id": 3, | |
76 | "label": "720p", | |
03d641a0 | 77 | "height": "720", |
99941732 WL |
78 | "active": true |
79 | } | |
80 | ``` | |
81 | ||
82 | `active` is true if the resolution is the currently selected resolution. | |
83 | ||
84 | ## `setResolution(resolutionId : number): Promise<void>` | |
85 | ||
86 | Change the current resolution. Pass `-1` for automatic resolution (when available). | |
87 | Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()` | |
88 | ||
89 | ## `getPlaybackRates() : Promise<number[]>` | |
90 | ||
91 | Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc. | |
92 | ||
93 | ## `getPlaybackRates() : Promise<number>` | |
94 | ||
95 | Get the current playback rate. See `getPlaybackRates()` for more information. | |
96 | ||
97 | ## `setPlaybackRate(rate : number) : Promise<void>` | |
98 | ||
99 | Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`. | |
100 | ||
101 | ## `setVolume(factor : number) : Promise<void>` | |
102 | ||
103 | Set the playback volume. Value should be between `0` and `1`. | |
104 | ||
105 | ## `getVolume(): Promise<number>` | |
106 | ||
107 | Get the playback volume. Returns a value between `0` and `1`. | |
03d641a0 | 108 | |
99941732 WL |
109 | # Events |
110 | ||
111 | You can subscribe to events by using `addEventListener()`. See above for details. | |
112 | ||
113 | ## Event `play` | |
114 | ||
115 | Fired when playback begins or is resumed after pausing. | |
116 | ||
117 | ## Event `pause` | |
118 | ||
119 | Fired when playback is paused. | |
120 | ||
121 | ## Event `playbackStatusUpdate` | |
122 | ||
123 | Fired every half second to provide the current status of playback. The parameter of the callback will resemble: | |
124 | ||
125 | ```json | |
126 | { | |
127 | "position": 22.3, | |
128 | "volume": 0.9, | |
129 | "playbackState": "playing" | |
130 | } | |
131 | ``` | |
132 | ||
133 | The `volume` field contains the volume from `0` (silent) to `1` (full volume). The `playbackState` can be `playing` or `paused`. More states may be added later. | |
134 | ||
135 | ## Event `playbackStatusChange` | |
136 | ||
137 | Fired when playback transitions between states, such as `pausing` and `playing`. More states may be added later. | |
138 | ||
139 | ## Event `resolutionUpdate` | |
140 | ||
478924a0 C |
141 | Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information. |
142 | ||
143 | ## Event `volumeChange` | |
144 | ||
145 | Fired when the player volume changed. |