Advanced Configuration

Introduction

After covering the basics of getting THEOplayer to run on our website, it’s time to dig a little bit deeper.

THEOplayer has a whole list of interesting features to improve the delivery of your audio and video content. In the continuation of this user guide we will show you how to leverage THEOplayer’s JavaScript API to configure the player.

Global Configuration

Depending on which features and where you want to configure them, there are different methods to use.

The first one we will look at is global configuration. This is what you will use when you are looking to enable or disable features for all the video players on the same webpage.

Examples of this could be social sharing or Chromecast support.

In our example we will configure THEOplayer for half-speed and double-speed playback.

As mentioned, configuring THEOplayer is done through its JavaScript API. The following snippet shows how to enable half-speed and doublespeed playback:

<script type='text/javascript'>
    var theoplayer = window.theoplayer = window.theoplayer || {};
    theoplayer.configuration = theoplayer.configuration || {};
    theoplayer.configuration.playbackRates = [0.5, 1, 2]; 
</script>
  1. window.theoplayer references the theoplayer variable created by the theoplayer library. In case the library wasn't fully loaded yet, we use an empty object that the THEOplayer library will pick up once it does get loaded.
  2. theoplayer.configuration references the configuration object of the THEOplayer library. As with window.theoplayer, if this is not yet loaded, we will put an empty object in place for the THEOplayer library to pick up later.
  3. .playbackRates is the feature that we’re setting in this part of the guide. The values between brackets are the playback speeds that we want to make available to the user: 0.5 (half speed), 1 (regular speed), 2 (double speed).

Our video element is the same one we used in the Basic Setup tutorial:

<video class="video-player"
    src="//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
    poster="//cdn.theoplayer.com/video/big_buck_bunny/poster.jpg"
    controls="controls" style="width: 100%; height: auto;">
</video>

Everything else remains the same as it was in the Basic Setup guide. Your html page should look something like this:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Getting Started</title>
        <script type='text/javascript' 
                   src='//cdn.theoplayer.com/latest/~yourlicense~/theoplayer.loader.js'>
        </script>
    </head>
    <body>
        <video class="video-player" 
            src="//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8" 
            poster="//cdn.theoplayer.com/video/big_buck_bunny/poster.jpg" 
            controls="controls" style="width: 100%; height: auto;">
        </video>

        <script type='text/javascript'>
            var theoplayer = window.theoplayer = window.theoplayer || {};
            theoplayer.configuration = theoplayer.configuration || {};
            theoplayer.configuration.playbackRates = [0.5, 1, 2]; 
        </script>
    </body>
</html>

Local Configuration

If you are looking for a little more versatility, THEOplayer can also be used with JavaScript scripting to help you get very specific and custom configurations for the videos on your website.

In this part of the tutorial we will show you how to configure an instance of THEOplayer separately.

Each instance of THEOplayer has 2 main components: a video element and a configuration.

Video element: The video element is an element in the DOM tree of the web page. Inside this element the THEOplayer instance will run. Use this to set the position of THEOplayer on your web page.

Configuration: the configuration is a list of settings for THEOplayer. Creating a THEOplayer instance with a specific configuration gives you easy control over the THEOplayer functionality for a specific player on your website.

Step 1: The Video Element

To create our custom configured instance of THEOplayer, we need access to the video element and the configuration through JavaScript.

There are a number of ways to do this. In this example we will create the element from scratch and then append it to the body of the HTML page.

<script type="text/javascript">
theoplayer.onReady = function () {
    var video = document.createElement('video');
    video.class = 'video-player';
    video.controls = 'controls';
    video.src = 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8';
    video.poster = 'http://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg';
    video.style = "width:100%; height:auto;";
    document.body.appendChild(video);

   //continued in step 2
}
</script>

This code generates the same video element that we used in earlier examples. Creating it this way shows you the versatility of configuring your elements with JavaScript.

<video class="video-player"
    src="//cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8"
    poster="//cdn.theoplayer.com/video/big_buck_bunny/poster.jpg"
    controls="controls" style="width: 100%; height: auto;">
</video>

The very first and last lines might need a little bit of an explanation:

theoplayer.onReady = function () {

            When the theoplayer library is fully loaded on your web page, it will fire off an event that it is ready. Using onReady allows you to assign a portion of JavaScript code that will run once when the theoplayer library is loaded. In this case it is the creation and appending of the video element.

Keep in mind that theoplayer is a global variable, so onReady can only map to a single function. If you were to set it twice, only the definition that is executed last by the browser will be executed when the player fires its ready event.

document.body.appendChild(video);

            This line of code gives the video element its place on the web page. In this case it will be appended as the last (and at this point only) element in the html body.

Step 2: Configuration

As we said earlier, we needed 2 parts to create a theoplayer instance. In the previous step we created the video element. Here we’ll show you how to create a theoplayer configuration with a very simple example.

In the first part of this guide (global configuration) we actually already did this. We will be reusing the same configuration settings, but this time we are assigning it to a separate variable rather than to THEOplayer itself.

<script type="text/javascript">
theoplayer.onReady = function () {
    var video = document.createElement('video');
    video.class = 'video-player';
    video.controls = 'controls';
    video.src = 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8';
    video.poster = 'http://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg';
    video.style = "width:100%; height:auto;";
    document.body.appendChild(video);

    var configuration = { playbackRates : [0.5, 1, 2] };
    var player = theoplayer(video, configuration);
}
</script>

Note that we put these lines of code inside the same onReady block as the video element that we;re creating.

For a full specification of what settings can be configured for a THEOplayer instance, check out our API.

Finally, this what the complete html page looks like after all the steps we just went through:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Getting Started</title>
        <script type='text/javascript' 
                   src='//cdn.theoplayer.com/latest/~yourlicense~/theoplayer.loader.js'></script>
    </head>
    <body>
        <script type="text/javascript">
            theoplayer.onReady = function () {
                var video = document.createElement('video');
                video.controls = 'controls';
                video.src = 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8';
                video.className = 'video-player';
                video.poster = 'http://cdn.theoplayer.com/video/big_buck_bunny/poster.jpg';
                video.preload = 'none';
                video.style = "width:100%; height:auto;";

                document.body.appendChild(video);

                var configuration = { playbackRates : [0.5, 1, 2] }; 

                var player = theoplayer(video, configuration);
            };
        </script>
    </body>
</html>