api.video player SDK

api.video is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app.

Table of contents
Project description
Getting started
- Installation
Documentation

Project description

SDK to control and interact with the api.video HTML5 Player

Getting started

Installation

Method #1: requirejs

If you use requirejs you can add the SDK as a dependency to your project with

$ npm install --save @api.video/player-sdk

You can then use the SDK in your script:

var { PlayerSdk } = require('@api.video/player-sdk');

var sdk = new PlayerSdk("#target", {
    id: "<VIDEO_ID>", 
    // ... other optional options
});

Method #2: typescript

If you use Typescript you can add the SDK as a dependency to your project with

$ npm install --save @api.video/player-sdk

You can then use the SDK in your script:

import { PlayerSdk } from '@api.video/player-sdk'

const sdk = new PlayerSdk("#target", {
    id: "<VIDEO_ID>", 
    // ... other optional options
});

Method #2: simple include in a javascript project

Include the SDK in your HTML file like so:

<head>
    ...
    <script src="https://unpkg.com/@api.video/player-sdk" defer></script>
</head>

Then, once the window.onload event has been triggered, create your player using new PlayerSdk():

<script type="text/javascript">
    window.player = new PlayerSdk("#target", { 
        id: "<VIDEO_ID>", 
        // ... other optional options 
    });
</script>

Documentation

Instanciation

The PlayerSdk constructor takes 2 parameters:

targetSelector: string | Element a CSS selector targeting the DOM element in which you want to create the player (eg. "#target"), or the DOM element itself
options: SdkOptions an object containing the player options. The available options are the following:

Option name	Mandatory	Type	Description
id	yes	string	the id of the video (videoId or liveStreamId)
token	yes for private video	string	the private video url token
live	no (default: false)	boolean	indicate that the video is a live one
autoplay	no (default: false)	boolean	start playing the video as soon as it is loaded
muted	no (default: false)	boolean	the video is muted
metadata	no (default: empty)	object	object containing metadata (see Full example below)
hideControls	no (default: false)	boolean	the controls are hidden (except unmute button if the video starts muted)
chromeless	no (default: false)	boolean	chromeless mode: all controls are hidden
hideTitle	no (default: false)	boolean	the video title is hidden
hidePoster	no (default: false)	boolean	the poster image isn't displayed
showSubtitles	no (default: false)	boolean	the video subtitles are shown by default
loop	no (default: false)	boolean	once the video is finished it automatically starts again
playbackRate	no (default: 1)	number	the playback rate of the video: 1 for normal, 2 for x2, etc.

The sdk instance can be used to control the video playback, and to listen to player events.

Methods

The sdk instance has the following methods:

`loadConfig(options: SdkOptions)`

Load a new video in the same instance of the player. Available options are the same as the ones passed to the SDK constructor (see available).

Example:
   player.loadConfig({
      id: "<VIDEO_ID>",
      hideTitle: true,
      hideControls: true,
   });

`play()`

Start playing the video.

`pause()`

Pause the video playback.

`mute()`

Mute the video.

`unmute()`

Unmute the video.

`hideControls(controls?: ControlName[])`

Hide the player controls.

controls parameter type definition:
type ControlName = "play" | "seekBackward" | "seekForward" | "playbackRate"
   | "volume" | "fullscreen" | "subtitles" | "chapters"
   | "pictureInPicture" | "progressBar" | "chromecast" | "download" | "more";
If no value is provided for the "controls" parameter, all controls will be hidden.

Note: the only control that can still be visible is the unmute button if the video as started muted. To hide all controls, including this one, use the setChromeless() method

Example:
    player.hideControls();
If a list of control names if provided, the associated controls will be hidden.

Example:
    player.showControls();                          // display all controls ...
    player.hideControls(["download", "subtitles"]); // ... except "download" and "subtitles"

`showControls(controls?: ControlName[])`

Show the player controls.

controls parameter type definition:

type ControlName = "play" | "seekBackward" | "seekForward" | "playbackRate"
   | "volume" | "fullscreen" | "subtitles" | "chapters"
   | "pictureInPicture" | "progressBar" | "chromecast" | "download" | "more";

If no value is provided for the "controls" parameter, all controls will be displayed.

Example:

    player.showControls();

If a list of control names if provided, the associated controls will be displayed.

Example:

    player.hideControls();                          // hide all controls ...
    player.showControls(["download", "subtitles"]); // ... except "download" and "subtitles" ...
    // ...
    player.showControls(["progressBar"]);           // ... and the progress bar

`setChromeless(chromeless: boolean)`

Define if the player should be in chromeless mode (all controls hidden).

`hideSubtitles()`

Hide the player subtitles.

`showSubtitles()`

Show the player subtitles.

`hideTitles()`

Hide the video title at the top of the video.

`showTitles()`

Show the video title at the top of the video.

`setLoop(loop: boolean)`

Define if the video should be played in loop.

`setAutoplay(autoplay: boolean)`

Define if the video should start playing as soon as it is loaded

`seek(time: number)`

Add/substract the given number of seconds to/from the playback time.

`setPlaybackRate(rate: number)`

Set the current playback rate. Example:
   player.setPlaybackRate(2); // Play at 2x rate

`setCurrentTime(time: number)`

Set the current playback time (seconds).

Example:
   player.setCurrentTime(24); // Go the 24th second

`setVolume(volume: number)`

Change the audio volume to the given value. From 0 to 1 (0 = muted, 1 = 100%).

Example:
    player.setVolume(0.75); // Set the volume to 75% 

`setVideoStyleObjectFit(value: "contain" | "cover" | "fill" | "none" | "scale-down")`

Change the object-fit CSS value of the video tag.

Example:

    player.setVideoStyleObjectFit("cover"); // Set the object-fit to cover

`setVideoStyleTransform(value: string)`

Change the transform CSS value of the video tag.

Example:

    player.setVideoStyleTransform("rotateY(180deg)"); // Apply a 180deg rotation around the Y axis (mirroring)

`setTheme(theme: PlayerTheme)`

Change the appearance of the player.

theme parameter type definition:

type PlayerTheme = {
    text?: string;
    link?: string;
    linkHover?: string;
    trackPlayed?: string;
    trackUnplayed?: string;
    trackBackground?: string;
    backgroundTop?: string;
    backgroundBottom?: string;
    backgroundText?: string;
    linkActive?: string;
}

Example:

    player.setTheme({
        link: "red",
        linkHover: "rgba(0, 255, 0, 1)",
        backgroundBottom: "#0000ff",
    });

`requestFullscreen()`

Request fullscreen mode (this may not work in some cases depending on browser restrictions)

`exitFullscreen()`

Leave fullscreen mode

`requestPictureInPicture()`

Request picture in picture mode (this may not work in some cases depending on browser restrictions)

`exitPictureInPicture()`

Leave picture in picture mode

`getPaused(callback?: (paused: boolean) => void): Promise<boolean>`

Check weither the video is paused.

`getPlaying(callback?: (playing: boolean) => void): Promise<boolean>`

Check weither the video is playing.

`getMuted(callback?: (muted: boolean) => void): Promise<boolean>`

Check weither the video is muted.

`getDuration(callback?: (duration: number) => void): Promise<number>`

Retrieve the duration of the video.

`getCurrentTime(callback?: (currentTime: number) => void): Promise<number>`

Retrieve the current playback time of the video.

`getVolume(callback?: (volume: number) => void): Promise<number>`

Retrieve the current volume.

`getLoop(callback?: (loop: boolean) => void): Promise<boolean>`

Check whether the video is in loop mode.

`getPlaybackRate(callback?: (rate: number) => void): Promise<number>`

Retrieve the playback rate.

`destroy()`

Destroy the player instance.

`addEventListener(event: string, callback: () => void)`

Define a callback function that will be called when the given event is triggered by the player.

Available events are the following:

Event name Description Parameter

controlsdisabled Controls are now disabled -

controlsenabled Controls are now enabled -

ended The playback as reached the ended of the video -

error An error occured -

firstplay The video started to play for the first time -

fullscreenchange The player goes to (or goes back from) full screen -

mouseenter The user's mouse entered the player area -

mouseleave The user's mouse leaved the player area -

pause The video has been paused -

play The video started to play (for the first time or after having been paused) -

playerresize The player size has changed -

qualitychange The video quality has changed { resolution: { height: number, width: number } }

ratechange The playback rate has changed -

ready The player is ready to play -

resize The video size has changed

seeking The player is seeking -

timeupdate The playback time has changed { currentTime: number }

useractive The user is active -

userinactive The user is inactive -

volumechange The volume has changed { volume: number }

Examples:
  // listen to the 'play' event
  player.addEventListener('play', function() { 
      console.log('play event received'); 
  });

  player.addEventListener('qualitychange', function(ev) { 
      console.log(`quality has changed: ${ev.resolution.width}x${ev.resolution.height}`); 
  });

Event name	Description	Parameter
controlsdisabled	Controls are now disabled	-
controlsenabled	Controls are now enabled	-
ended	The playback as reached the ended of the video	-
error	An error occured	-
firstplay	The video started to play for the first time	-
fullscreenchange	The player goes to (or goes back from) full screen	-
mouseenter	The user's mouse entered the player area	-
mouseleave	The user's mouse leaved the player area	-
pause	The video has been paused	-
play	The video started to play (for the first time or after having been paused)	-
playerresize	The player size has changed	-
qualitychange	The video quality has changed	`{ resolution: { height: number, width: number } }`
ratechange	The playback rate has changed	-
ready	The player is ready to play	-
resize	The video size has changed
seeking	The player is seeking	-
timeupdate	The playback time has changed	`{ currentTime: number }`
useractive	The user is active	-
userinactive	The user is inactive	-
volumechange	The volume has changed	`{ volume: number }`

Full example

<html>
    <head>
        ...
        <script src="/index.js" defer></script>
    </head>

    <body>
        <div id="target"></div>

        <!-- buttons that call player methods to control the video playback -->
        <button onclick="javascript:player.play()"  id="play-btn">play</button>
        <button onclick="javascript:player.pause()" id="pause-btn" disabled>pause</button>
        <button onclick="javascript:player.mute()">mute</button>
        <button onclick="javascript:player.unmute()">unmute</button>
    </body>

    <script type="text/javascript">
        window.onload = function() {
            // create the player in the #target element
            window.player = new PlayerSdk("#target", {
                id: "123456",
                metadata: {
                    dogcat: "dog"
                }
            });

            // when the 'play' event is received, disable the 'play' button and enable the 'pause' button
            player.addEventListener('play', function() {
                document.getElementById('play-btn').disabled = true;
                document.getElementById('pause-btn').disabled = false;
            });

            // when the 'pause' event is received, disable the 'pause' button and enable the 'play' button
            player.addEventListener('pause', function() {
                document.getElementById('play-btn').disabled = false;
                document.getElementById('pause-btn').disabled = true;
            });
        };
    </script>
</html>

Control an existing embedded player using the SDK

It's also possible to integrate the SDK in a page that already contains an embedded player in order to control it and to listen to its events. Let's consider the following page :

<html>
    <head>
        ...
    </head>

    <body>
        ...
        <!-- my embedded player -->
        <iframe src="//embed.api.video/vod/vi54sj9dAakOHJXKrUycCQZp" width="100%" height="100%" frameborder="0" allowfullscreen></iframe>
        ...
    </body>
</html>

To attach the SDK to this player, you'll have to make the following changed in your page:

import the sdk.js script in your page,
create a PlayerSdk instance once the page is loaded.

Here is how the page will look like with these changes :

<html>
    <head>
        ...
        <script src="/index.js" defer></script>
    </head>

    <body>
        ...
        <!-- my embedded player -->
        <iframe id="myPlayer" src="//embed.api.video/vod/vi54sj9dAakOHJXKrUycCQZp" width="100%" height="100%" frameborder="0" allowfullscreen></iframe>
        ...
    </body>

    <script type="text/javascript">
        window.onload = function() {
            // attach the sdk to the existing player
            window.player = new PlayerSdk("#myPlayer");

            // window.player can now be used to control the player as described above
        };
    </script>
</html>

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

apivideo / api.video-player-sdk

Programming Languages

Labels

Projects that are alternatives of or similar to api.video-player-sdk

api.video player SDK

Table of contents

Project description

Getting started

Installation

Method #1: requirejs

Method #2: typescript

Method #2: simple include in a javascript project

Documentation

Instanciation

Methods

loadConfig(options: SdkOptions)

play()

pause()

mute()

unmute()

hideControls(controls?: ControlName[])

showControls(controls?: ControlName[])

setChromeless(chromeless: boolean)

hideSubtitles()

showSubtitles()

hideTitles()

showTitles()

setLoop(loop: boolean)

setAutoplay(autoplay: boolean)

seek(time: number)

setPlaybackRate(rate: number)

setCurrentTime(time: number)

setVolume(volume: number)

setVideoStyleObjectFit(value: "contain" | "cover" | "fill" | "none" | "scale-down")

setVideoStyleTransform(value: string)

setTheme(theme: PlayerTheme)

requestFullscreen()

exitFullscreen()

requestPictureInPicture()

exitPictureInPicture()

getPaused(callback?: (paused: boolean) => void): Promise<boolean>

getPlaying(callback?: (playing: boolean) => void): Promise<boolean>

getMuted(callback?: (muted: boolean) => void): Promise<boolean>

getDuration(callback?: (duration: number) => void): Promise<number>

getCurrentTime(callback?: (currentTime: number) => void): Promise<number>

getVolume(callback?: (volume: number) => void): Promise<number>

getLoop(callback?: (loop: boolean) => void): Promise<boolean>

getPlaybackRate(callback?: (rate: number) => void): Promise<number>

destroy()

addEventListener(event: string, callback: () => void)

Full example

Control an existing embedded player using the SDK

`loadConfig(options: SdkOptions)`

`play()`

`pause()`

`mute()`

`unmute()`

`hideControls(controls?: ControlName[])`

`showControls(controls?: ControlName[])`

`setChromeless(chromeless: boolean)`

`hideSubtitles()`

`showSubtitles()`

`hideTitles()`

`showTitles()`

`setLoop(loop: boolean)`

`setAutoplay(autoplay: boolean)`

`seek(time: number)`

`setPlaybackRate(rate: number)`

`setCurrentTime(time: number)`

`setVolume(volume: number)`

`setVideoStyleObjectFit(value: "contain" | "cover" | "fill" | "none" | "scale-down")`

`setVideoStyleTransform(value: string)`

`setTheme(theme: PlayerTheme)`

`requestFullscreen()`

`exitFullscreen()`

`requestPictureInPicture()`

`exitPictureInPicture()`

`getPaused(callback?: (paused: boolean) => void): Promise<boolean>`

`getPlaying(callback?: (playing: boolean) => void): Promise<boolean>`

`getMuted(callback?: (muted: boolean) => void): Promise<boolean>`

`getDuration(callback?: (duration: number) => void): Promise<number>`

`getCurrentTime(callback?: (currentTime: number) => void): Promise<number>`

`getVolume(callback?: (volume: number) => void): Promise<number>`

`getLoop(callback?: (loop: boolean) => void): Promise<boolean>`

`getPlaybackRate(callback?: (rate: number) => void): Promise<number>`

`destroy()`

`addEventListener(event: string, callback: () => void)`