# PeerTube Embed API PeerTube lets you embed videos and programmatically control their playback. This documentation covers how to interact with the PeerTube Embed API. ## Playground 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 allows you to test various aspects of PeerTube embeds. Simply replace `/embed` with `/test-embed` and visit the URL in a browser. For instance, the playground URL for the above embed URL is `https://my-instance.example.com/videos/test-embed/52a10666-3a18-4e73-93da-e8d3c12c305a`. ## Quick Start Given an existing PeerTube embed `<iframe>` **with API enabled** (`https://my-instance.example.com/videos/embed/52a10666-3a18-4e73-93da-e8d3c12c305a?api=1`), one can use the PeerTube Embed API to control it by first including the library. You can include it via Yarn with: ``` yarn add @peertube/embed-api ``` Now just use the `PeerTubePlayer` class exported by the module: ```typescript import { PeerTubePlayer } from '@peertube/embed-api' ... ``` Or use the minified build from NPM CDN in your HTML file: ``` <script src="https://unpkg.com/@peertube/embed-api/build/player.min.js"></script> <script> const PeerTubePlayer = window['PeerTubePlayer'] ... </script> ``` Then you can instantiate the player: ```typescript let player = new PeerTubePlayer(document.querySelector('iframe')) await player.ready // wait for the player to be ready // now you can use it! player.play() player.seek(32) player.pause() ``` # Methods ## `play() : Promise<void>` Starts playback, or resumes playback if it is paused. ## `pause() : Promise<void>` Pauses playback. ## `seek(positionInSeconds : number)` Seek to the given position, as specified in seconds into the video. ## `addEventListener(eventName : string, handler : Function)` Add a listener for a specific event. See below for the available events. ## `getResolutions() : Promise<PeerTubeResolution[]>` Get the available resolutions. A `PeerTubeResolution` looks like: ```json { "id": 3, "label": "720p", "height": "720", "active": true } ``` `active` is true if the resolution is the currently selected resolution. ## `setResolution(resolutionId : number): Promise<void>` Change the current resolution. Pass `-1` for automatic resolution (when available). Otherwise, `resolutionId` should be the ID of an object returned by `getResolutions()` ## `getPlaybackRates() : Promise<number[]>` Get the available playback rates, where `1` represents normal speed, `0.5` is half speed, `2` is double speed, etc. ## `getPlaybackRates() : Promise<number>` Get the current playback rate. See `getPlaybackRates()` for more information. ## `setPlaybackRate(rate: number) : Promise<void>` Set the current playback rate. The passed rate should be a value as returned by `getPlaybackRates()`. ## `setVolume(factor: number) : Promise<void>` Set the playback volume. Value should be between `0` and `1`. ## `getVolume(): Promise<number>` Get the playback volume. Returns a value between `0` and `1`. ## `setCaption(id: string) : Promise<void>` Update current caption using the caption id. ## `getCaptions(): Promise<{ id: string, label: string, src: string, mode: 'disabled' | 'showing' }>` Get video captions. ## `playNextVideo(): Promise<void>` Play next video in playlist. ## `playPreviousVideo(): Promise<void>` Play previous video in playlist. ## `getCurrentPosition(): Promise<void>` Get current position in playlist (starts from 1). # Events You can subscribe to events by using `addEventListener()`. See above for details. ## Event `playbackStatusUpdate` Fired every half second to provide the current status of playback. The parameter of the callback will resemble: ```json { "position": 22.3, "volume": 0.9, "duration": "171.37499", "playbackState": "playing" } ``` `duration` field and `ended` `playbackState` are available in PeerTube >= 2.2. The `volume` field contains the volume from `0` (silent) to `1` (full volume). The `playbackState` can be `unstarted`, `playing`, `paused` or `ended`. More states may be added later. ## Event `playbackStatusChange` Fired when playback transitions between states, such as `paused` and `playing`. More states may be added later. ## Event `resolutionUpdate` Fired when the available resolutions have changed, or when the currently selected resolution has changed. Listener should call `getResolutions()` to get the updated information. ## Event `volumeChange` Fired when the player volume changed.