How to migrate from THEOplayer 1.X to THEOplayer 2.X


THEOplayer 2.X is the successor of the THEOplayer 1.X HTML5 video player. The 2.X player has the following new features and more:

This guide describes how to upgrade your existing 1.X player to the new 2.X player.

1. Prerequirements

There are two prerequirements in order to continue with this guide:

  1. You have a THEOplayer 2.X license and library. If you don't have THEOplayer 2.X yet, you can start your free trial here or contact your THEOplayer account manager.
  2. You have some basic knowledge on how to use THEOplayer 1.X, and have read through the 2.X getting started guide.

2. Migrating

This section discussing how you swap out your 1.X license library for 2.X, and what the differences are.

Generally speaking, a migration will happen in the following order:

  1. Update JavaScript library
  2. Update CSS file
  3. Update API

Step one and two are straightforward. Step three requires a minimal understanding of the THEOplayer 2.X API. It's advised to go through the following pages:

2.1. Update JavaScript library

THEOplayer 1.X allows you to include the JavaScript library through theoplayer.js or theoplayer.loader.js.

<script type='text/javascript'

THEOplayer 2.x allows you to include the JavaScript library through THEOplayer.js.

<script type='text/javascript'

Your first action is to swap out the 1.X JavaScript file for the 2.X JavaScript file.

In order to do HLS playback on 2.X you have to correctly set the library location, as explained by section three of the getting started guide. This means that you have to upload all the THEOplayer 2.X JavaScript files (THEOplayer.js, theoplayer.d.js, theoplayer.e.js, theoplayer.p.js) to this location.

2.2. Update CSS

THEOplayer 1.X allows you to either import the CSS file automatically, specify the stylesheetURI of the THEOplayer configuration object, or include it through the HTML tag if the stylesheetURI is set to null.

THEOplayer.2X requires you to include the CSS file through the HTML tag.

<link rel="stylesheet" type="text/css" href='/path/to/ui.css'>

Your second action is to include this ui.css file, and potentially swap out old THEOplayer UI styles.

2.3. Update API

THEOplayer 1.X allows you to pick up a video element from your HTML tags and initialize your player automatically, or initialize one through the API.

THEOplayer 2.X requires you to supply a container element which the THEOplayer API will use to initialize a player. The constructed player object is the video element replacement in 2.X.

<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls">
var element = document.querySelector('.theoplayer-container'); // fetch THEOplayer container div

var player = new THEOplayer.Player(element, { // instantiates video player
libraryLocation : '/path/to/your-theoplayer-folder/' // references folder containing your THEOplayer library files (theoplayer.p.js, THEOplayer.js, ...)

// HLS
player.source = {
sources : [{
src : '//', // sets HLS source
type : 'application/x-mpegurl' // sets type to HLS

 Your third action is to change the way you set up your player.

3. THEOplayer 2.X API

The first challenge is switching out the JavaScript and CSS files, and changing your player initialization approach. Once these tasks are completed, you want to become familiar with the THEOplayer 2.X API.

The 1.X Player API and the 2.X Player API are much alike. The 2.X Player API has an almost complete backwards compatibility.

One of the bigger differences between the 1.X API and the 2.X API is that the 1.X API asks you to use controllers if you want to schedule ads, switch qualities and things alike. The 2.X allows you to use the player properties to execute similar behavior (e.g.

4. Conclusion

Although THEOplayer 1.X and 2.X are very alike, the way you start a 2.X player is a bit different. In 2.X you have to put in a bit of extra work to get your player up and running. However, you are rewarded with a reduced complexity and a better overview of the involved components.

THEOplayer 2.X has more features, among which DASH and DRM support. THEOplayer 2.X also allows you to create your own UI when using theoplayer.chromeless.js, which is useful if you want to implement your a custom theme.

Extra resources:

5. FAQ

How do controllers (e.g. Rendition Controller) function in 2.X?

THEOplayer 2.X doesn't employ controller instances to manipulate advertisements, renditions and other features, as it did in 1.X. All 2.X capabilities are accessible through the player object.

Three of the 1.X controllers have been adapted to 2.X:

  • The Rendition Controller in 1.X allows you to find the active quality and observe quality change events. In 2.X you can utilize the player.videoTracks and player.audioTracks property to access similar information.
  • The Advertising Controller in 1.X allows you to schedule ads and observe ad related events. In 2.X you can utilize the object to implement similar behavior.
  • The Chromecast Controller in 1.X allows you to manipulate a casting session. In 2.X you can utilize the player.cast object to achieve similar functionality.