Getting Started with THEOplayer 1.X

Introduction

If you are configuring THEOplayer for the first time, this page will be your first step. We will give you a quick overview about how to get started, some core set-ups and how to configure THEOplayer.

This step-by-step guide will be a quick read and is supported by multiple examples for the configuration code that you will need to implement on your page.

If you aren't using THEOplayer yet, you can start your free trial here.

Basic setup

In this user guide we will guide you through the process of setting up a simple THEOplayer video on your website. There’s only a few things you need to get started, most of which you will already have available if you are building a website.

  1. A webserver - This will host your webpages.
  2. A domain name - People will be able to find your webpages here.
  3. A THEOplayer license - This gives you access to the THEOplayer library and allows you to use it on the aforementioned domain.
  4. One or more URI's to HLS stream manifests (.m3u8) that link to the video streams that you want to show on your website.

In the continuation of this guide we will be using the following stream:

src='http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8'

This stream is hosted on our own servers and we know it will be available for anyone looking to use it as a test source.

The third and last piece of the puzzle is an HTML file that ties the previous two together and makes your HLS stream consumable through a THEOplayer instance on your website.

Step 1: Set up an HTML file

Since THEOplayer is a web video player, we will need a webpage to put the video on.

Keep in mind that whilst .html-files can easily be opened from your local computer, this will not work with THEOplayer as THEOplayer licenses are locked to a specific domain.

From this point on, you should assume that if a piece of script is shown, it is hosted on a page in the domain of the THEOplayer license that is being used.

The .html-file that we’ll start with and that we’ll keep working on, looks like this:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Getting Started</title>
    </head>
    <body>
    </body>
</html>

So far so good. Next, we’ll plug in THEOplayer.

Or more specifically, include it as a JavaScript library since we don’t like the term “plugin”.

Step 2: Including the THEOplayer library

THEOplayer is a lean, mean video machine. The easiest and simplest way to use it requires just a licensed THEOplayer library for the domain you want to use THEOplayer on.

All that you need to do then is include the following line of code on your website:

<script type='text/javascript'
    src='//cdn.theoplayer.com/latest/~yourlicense~/theoplayer.loader.js'>
</script>

The result of this is that every video element that you add on this webpage will be automatically detected by the THEOplayer library and converted into a THEOplayer instance.

Script tags are used to add code to a web page. In this case we used it to include the THEOplayer library. The two properties of the element are:

  1. src” this is the URI of the THEOplayer library that you wish to use. It should always have the same form:
    //cdn.theoplayer.com/latest/~yourlicense~/theoplayer.loader.js
    where ~yourlicense~ is a hash generated specifically for your domain.
  2. type” designates the contents of the included script to be JavaScript. While this is optional in many browsers these days, it is nonetheless advisable to put it in there anyway.

Next we’ll define a video element

Step 3: The <video> element

For THEOplayer to start playing video, it will need an HLS manifest. In this basic guide we will provide them to the library by putting them inside video elements on the .html page.

Here’s the one that we will be using as an example:

<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>

This element contains a few properties to help with instancing THEOplayer. We will list them in order of importance:

  1. src” is our video source. This is a URI where THEOplayer will go looking for the video’s master manifest to start streaming.
  2. controls” when set to “controls” the user will have access to the play and pause button as well as any other controls that are configured. In some cases you may not want your users to have this level of control.
  3. poster” is the background image that will show before the user clicks the big play button on the video player. For best results you always want this to be the same aspect ratio (and if possible, resolution) of the video source.
  4. style” contains all the styling for the video element. In this case we give the video element the full width (100%) of its parent element, which in this case will be the body element. The height is set to auto, so the player will choose its size based on the aspect ratio of the video source.

Finally we will show you the completed html page as well as an example of what it should look like on your page if you followed these steps correctly.

Step 4: The result

And here you have it. Save your .html, put it on a running web server and browse to it to see your video playing in THEOplayer.

<!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>
    </body>
</html>

With the THEOplayer library included in your html page, THEOplayer will automatically search for video elements on the page and replace them with a THEOplayer instance configured to play that source.