3 PeerTube lets you embed videos and programmatically control their playback. This documentation covers how to interact with the PeerTube Embed API.
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`.
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:
16 yarn add @peertube/embed-api
19 Now just use the `PeerTubePlayer` class exported by the module:
22 import { PeerTubePlayer } from '@peertube/embed-api'
24 let player = new PeerTubePlayer(document.querySelector('iframe'))
25 await player.ready // wait for the player to be ready
27 // now you can use it!
35 ## `play() : Promise<void>`
37 Starts playback, or resumes playback if it is paused.
39 ## `pause() : Promise<void>`
43 ## `seek(positionInSeconds : number)`
45 Seek to the given position, as specified in seconds into the video.
47 ## `addEventListener(eventName : string, handler : Function)`
49 Add a listener for a specific event. See below for the available events.
51 ## `getResolutions() : Promise<PeerTubeResolution[]>`
53 Get the available resolutions. A `PeerTubeResolution` looks like:
59 "src": "//src-url-here",
64 `active` is true if the resolution is the currently selected resolution.
66 ## `setResolution(resolutionId : number): Promise<void>`
68 Change the current resolution. Pass `-1` for automatic resolution (when available).
69 Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()`
71 ## `getPlaybackRates() : Promise<number[]>`
73 Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc.
75 ## `getPlaybackRates() : Promise<number>`
77 Get the current playback rate. See `getPlaybackRates()` for more information.
79 ## `setPlaybackRate(rate : number) : Promise<void>`
81 Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`.
83 ## `setVolume(factor : number) : Promise<void>`
85 Set the playback volume. Value should be between `0` and `1`.
87 ## `getVolume(): Promise<number>`
89 Get the playback volume. Returns a value between `0` and `1`.
92 You can subscribe to events by using `addEventListener()`. See above for details.
96 Fired when playback begins or is resumed after pausing.
100 Fired when playback is paused.
102 ## Event `playbackStatusUpdate`
104 Fired every half second to provide the current status of playback. The parameter of the callback will resemble:
110 "playbackState": "playing"
114 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.
116 ## Event `playbackStatusChange`
118 Fired when playback transitions between states, such as `pausing` and `playing`. More states may be added later.
120 ## Event `resolutionUpdate`
122 Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information.