aboutsummaryrefslogtreecommitdiffhomepage
path: root/support/doc/api/embeds.md
diff options
context:
space:
mode:
Diffstat (limited to 'support/doc/api/embeds.md')
-rw-r--r--support/doc/api/embeds.md122
1 files changed, 122 insertions, 0 deletions
diff --git a/support/doc/api/embeds.md b/support/doc/api/embeds.md
new file mode 100644
index 000000000..3a35a539c
--- /dev/null
+++ b/support/doc/api/embeds.md
@@ -0,0 +1,122 @@
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
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.
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
13Given 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```
16yarn add @peertube/embed-api
17```
18
19Now just use the `PeerTubePlayer` class exported by the module:
20
21```typescript
22import { PeerTubePlayer } from '@peertube/embed-api'
23
24let player = new PeerTubePlayer(document.querySelector('iframe'))
25await player.ready // wait for the player to be ready
26
27// now you can use it!
28player.play()
29player.seek(32)
30player.stop()
31```
32
33# Methods
34
35## `play() : Promise<void>`
36
37Starts playback, or resumes playback if it is paused.
38
39## `pause() : Promise<void>`
40
41Pauses playback.
42
43## `seek(positionInSeconds : number)`
44
45Seek to the given position, as specified in seconds into the video.
46
47## `addEventListener(eventName : string, handler : Function)`
48
49Add a listener for a specific event. See below for the available events.
50
51## `getResolutions() : Promise<PeerTubeResolution[]>`
52
53Get the available resolutions. A `PeerTubeResolution` looks like:
54
55```json
56{
57 "id": 3,
58 "label": "720p",
59 "src": "//src-url-here",
60 "active": true
61}
62```
63
64`active` is true if the resolution is the currently selected resolution.
65
66## `setResolution(resolutionId : number): Promise<void>`
67
68Change the current resolution. Pass `-1` for automatic resolution (when available).
69Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
70
71## `getPlaybackRates() : Promise<number[]>`
72
73Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
74
75## `getPlaybackRates() : Promise<number>`
76
77Get the current playback rate. See `getPlaybackRates()` for more information.
78
79## `setPlaybackRate(rate : number) : Promise<void>`
80
81Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
82
83## `setVolume(factor : number) : Promise<void>`
84
85Set the playback volume. Value should be between `0` and `1`.
86
87## `getVolume(): Promise<number>`
88
89Get the playback volume. Returns a value between `0` and `1`.
90# Events
91
92You can subscribe to events by using `addEventListener()`. See above for details.
93
94## Event `play`
95
96Fired when playback begins or is resumed after pausing.
97
98## Event `pause`
99
100Fired when playback is paused.
101
102## Event `playbackStatusUpdate`
103
104Fired every half second to provide the current status of playback. The parameter of the callback will resemble:
105
106```json
107{
108 "position": 22.3,
109 "volume": 0.9,
110 "playbackState": "playing"
111}
112```
113
114The `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.
115
116## Event `playbackStatusChange`
117
118Fired when playback transitions between states, such as `pausing` and `playing`. More states may be added later.
119
120## Event `resolutionUpdate`
121
122Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information. \ No newline at end of file