v 1.x

This guide explains to you how to install and use a self-hosted NPM player to play back THEOlive streams on your web page. This is an alternative to using the embed script. The NPM player has the advantage of letting you access the player itself, so you can further customize it through an elementary player API and CSS.

🚧
Don't forget to make regular updates!
Using the self-hosted NPM player means that you will need to host the .js files yourself, and periodically update these to the latest version. These updates are automatically made available when using the embed script.

NPM page

https://www.npmjs.com/package/@theolive/player

Installation

Install using your favorite package manager for Node (such as npm or yarn):

npm install @theolive/player

Files

THEOLivePlayer.js
Contains the video player and channel logic.

THEOLive.sw.js
This is a Service Worker that allows playback of THEOlive streams on iOS Safari. It is important that this file is hosted on the same domain as the webpage over https.

🚧
Service worker deployment
In order to use THEOlive on iOS Browser, we need the THEOlive serviceworker to be active. This implies the following rules :

HTTPS is required

the THEOLive.sw.js file needs to be on the same domain and path as the page initiating the player

Usage

First you should add the THEOlive player to your HTML page:

<script type="text/javascript" src="url/to/THEOLivePlayer.js"></script>

Make sure you replace url/to with the correct path to your THEOLivePlayer.js file. For example, if you installed the player in the same folder as your current HTML page, the full value of the src attribute should be node_modules/@theolive/player/dist/THEOLivePlayer.js.

Next, we should add a script to check if the player requires a service worker to play:

<script type="text/javascript">
    if (THEOLivePlayer.requiresServiceWorker()) {
        navigator.serviceWorker.register("THEOLive.sw.js")
    }
</script>

Finally, you should create the player with the channel-id for your channel:

<script type="text/javascript">
    const player = new THEOLivePlayer('<your-channel-id>');
    document.body.append(player);
</script>

This will add the player to the page as a Custom Element, and you can access it with:
document.querySelector('theo-live-player');

Example

This example page assumes you have completed the getting started tutorial and your channel is up and running. This is a minimal page that creates a THEOlive player:

<!DOCTYPE html>
<html>
    <head>
        <title>Example</title>
        <script type="text/javascript" src="THEOLivePlayer.js"></script>
    </head>
    <body>
        <script type="text/javascript">
            // Check if the player needs a service worker and register it if needed.
            if (THEOLivePlayer.requiresServiceWorker()) {
                navigator.serviceWorker.register("THEOLive.sw.js")
            }
            // Create the player.
            const player = new THEOLivePlayer('<your-channel-id>');
            // Add the player to the page at your desired location:
            document.body.append(player);
        </script>
    </body>
</html>

Make sure to replace <your-channel-id> with your actual channel-id.

Player API

A basic player API is made available in the THEOlive NPM player:

Properties

Property	Type	Description
muted	boolean	Returns or sets whether the audio is muted.
paused	boolean	Returns whether the player is paused.
volume	number	Returns or sets the current volume percentage as a floating point value between 0 and 1.

Methods

Method	Description
destroy()	Destroy the player. This stops playback and releases all resources associated with this player.
pause()	Pause playback.
play()	Start or resume playback
requestFullscreen(options)	Display element in fullscreen mode. The optional parameter options controls the transition to fullscreen mode. Possible parameter values: "hide", "show", "auto". More info available here.

Customization examples

At this point, you have a working self-hosted player and knowledge about the API. Making use of some additional HTML, CSS and JavaScript we can modify the aspect and tap into the player with the aid of the available API. Let's dive into some specific examples of player customization.

📘
Standard customizations available
The standard customization options available for the embedded player (e.g. adding poster image, switching on/off autoplay, tailoring the colors, etc.), are also possible for the self-hosted player. Use the THEOlive console or the THEOlive API for this. For more information, see Customize your THEOlive player.

Example 1 - Change the big play button with CSS

It’s possible to customize the big play button, to give it your own look and feel. There are many things you can do here, but we’ll share a few ideas to get you started.

1.1 - Make the big play button more lively / interactive
In order to do this, you can add a transition that increases the button size when hovering it:

.theoplayer-skin .vjs-big-play-button:hover {
   background: none;
   -webkit-transition-duration: 0.2s;
   -moz-transition-duration: 0.2s;
   transition-duration: 0.2s;
   transform: translate(-50%, -50%) scale(1.2);
   transition: transform 0.2s;
}

1.2 - Use another image
You might want to use another image for your big play button. In the following example, we remove the current svg and replace it with another image.

.theo-big-play-button-svg-container svg {
   display: none;
}

.theoplayer-skin .vjs-big-play-button {
   content: "";
   background: url("data:image/svg+xml;base64,PD94bWwgd…vc3ZnPg==")
   no-repeat 0 0!important;
   /* background: url('http://i.stack.imgur.com/LT3WE.png') no-repeat 0 0; */ /* Use image instead */
   background-size: 100%!important;
   display: block;
}

1.3 - Change the spotlight
You might want to remove or alter the spotlight that currently appears around the button, on focus (hovering the player).

.theoplayer-skin:hover .vjs-big-play-button:after,
.theoplayer-skin .vjs-big-play-button:focus:after {
   opacity: 1!important; /* make the spotlight always visible */
   /*opacity: 0!important;*/ /* hide it */
   color:lawngreen; /* give it a color */
}

Example 2 - Change the control bar

In addition to changing control bar colors, which is possible via the THEOlive API and console, it is possible to customize the control bar further via the THEOlive NPM player. This section provides a number of examples.

2.1 - Always show/hide the control bar
A typical use case for hiding the control bar is if you don’t want your viewer to have control over the video (e.g.: pause, fullscreen). In other cases, you might want to avoid the control bar disappearing.

.vjs-control-bar {
	opacity:0!important; 
	display:none!important
}

.vjs-user-inactive .vjs-control-bar {
	opacity:1!important
}

2.2 - Customize single buttons
Through the THEOlive API and the console, you can change the colors of the control bar. However, you can’t act on single buttons. In the following example, we are hiding the fullscreen button, moving the mute button and changing the color of the play button.

.vjs-mute-control {
	order:9!important
}

.vjs-play-control {
  color:lime!important
}

.vjs-fullscreen-control {
  display: none!important
}

Example 3 - Customize the player

You can also further customize the player itself by changing shape, colors and so on.

3.1 - Fill completely a container element
As is, the player will fill its container element depending only on its width and maintain the optimal shape for a 16:9 video. You can give it a specific size or have it completely fill a container element. The video element will maintain its own aspect ratio, therefore the images won’t be altered.

<div id="containerDiv" style="width:1000px;height:400px"></div>

.video-js {
   width: 100% !important;
   height: 100% !important;
   padding: 0 !important;
}

// Add the player to the page at your desired location:
/*document.body.append(player);*/
document.querySelector('#containerDiv').append(player);

3.2 - Change the background color
Currently the player’s background is black. It can be changed as follows:

.video-js .theo-player-wrapper {
   background-color: darkblue;
}

Example 4 - Show elements based on the player API

4.1 - Add a warning
If playback starts muted, warn the viewer and give the possibility to unmute it by clicking the warning

<div id="mutedNotice">
   <h3>Your player is muted</h3>
   <p>Click here to unmute your player</p>
</div>

#mutedNotice {
   text-align:center;
   border-radius:1em;
   border:1px solid #ccc;
   padding: 1em 2em;
   display:none;
   width:max-content;
   margin:1em auto;
   background-color:rgba(255,255,0,.1);
   position:relative;
   box-shadow: 2px 2px 5px #ccc;
   cursor: pointer;
}

// Make the notice appear if the player is muted on
let mutedNotice = document.querySelector('#mutedNotice');
let myInterval = setInterval(showMutedNotice, 500);

function showMutedNotice() {
   if (!player.paused) {
       if (player.muted) {
           mutedNotice.style.display = "block";
       }
       clearInterval(myInterval);
   }
}

// make the notice unmute the player and disappear when clicked
mutedNotice.addEventListener('click', ()=>{
   player.muted = false;
   mutedNotice.style.display = "none";
});

v 1.x

🚧
Don't forget to make regular updates!

NPM page

Installation

Files

🚧
Service worker deployment

Usage

Example

Player API

Customization examples

📘
Standard customizations available

Example 1 - Change the big play button with CSS

Example 2 - Change the control bar

Example 3 - Customize the player

Example 4 - Show elements based on the player API

🚧Don't forget to make regular updates!

NPM page

Installation

Files

🚧Service worker deployment

Usage

Example

Player API

Customization examples

📘Standard customizations available

Example 1 - Change the big play button with CSS

Example 2 - Change the control bar

Example 3 - Customize the player

Example 4 - Show elements based on the player API

🚧
Don't forget to make regular updates!

🚧
Service worker deployment

📘
Standard customizations available