Video.js 6 Migration Guide

There are some backwards-incompatible changes in Video.js 6, but we believe they will be invisible to the vast majority of plugins and integrations. Even so, the rest of this document is dedicated to explaining these changes and how they may affect your code.

Method Chaining Removed

One of the relatively unknown features of Video.js is that some player methods could be chained off of each other, jQuery-style:

player.on('play', handlePlay).play();

The problem with this was it made the return values of some functions unpredictable (e.g. src(), currentTime(), etc). Sometimes they would return a value, sometimes the player itself. With 6.0.0, we have removed method chaining support; so, the above example would become:

player.on('play', handlePlay);
player.play();

The src() Function

In Video.js 5, the player’s src() function would return the source being played back in the video element.

This could cause problems with certain formats like HLS where it could return a “blob” URL. These kinds of URLs are virtually useless to users, who usually wanted to know the source that had been originally set on the player (i.e., an m3u8 file for HLS sources).

The src() function will now return the source object determined by the middleware-driven source setting procedure. In other words, if you set the source to an m3u8 file, this method will return a source object similar to this:

{type: 'application/x-mpegURL', src: 'https://.../url/to/manifest.m3u8'}

Note: This change and the currentSrc() function should work for the vast majority of use-cases. In rare cases where you need access to the actual source being played in the video element, this can be retrieved from the playback tech directly:

player.tech(true).src();

The true value is passed to the tech() function in order to avoid a warning message in the console.

Asynchronous Source Selection

In Video.js 5, calling src() and passing in a value would kick off a synchronous source selection algorithm. This meant that any subsequent calls to src() would return the source that was selected by the last call:

player.src({type: 'video/mp4', src: 'foo.mp4'});
videojs.log(player.src().src); // 'foo.mp4'

However, because middleware assumes asynchrony in order to support advanced workflows - like making server calls for custom source selection - Video.js cannot guarantee the above code to work.

Another common pattern we've seen when people call src() is to call another method like play() immediately after:

player.src({type: 'video/mp4', src: 'foo.mp4'});
player.play();

This might not work in Video.js 6. Code like this should be migrated to use a one-off player.ready() callback:

player.src({type: 'video/mp4', src: 'foo.mp4'});
player.ready(player.play);

UI and Accessibility Changes

The UI and accessibility changes that were made in Video.js 6 mean that the HTML and CSS may have changed along with them. Some key components that have changed markup:

• Volume controls
• Combined captions and subtitles menu
• Progress bar time tooltips

Custom skins with a lot of customization may have to adjust for these changes.

Deprecations

Several methods from Video.js 5 were deprecated.

As always, deprecated methods will log warnings in the browser console with a suggestion as to how to avoid them, if desired. Some of the key deprecations are below, along with examples of how to avoid them and support both Video.js 5 and 6 simultaneously:

videojs.plugin()

Avoid by switching to videojs.registerPlugin() or become cross-compatible with:

var registerPlugin = videojs.registerPlugin || videojs.plugin;

registerPlugin('myPlugin', function() {
  // ...
});

DOM Methods

All DOM methods that were attached directly to videojs - such as addClass(), hasClass(), createEl(), etc. - are being moved to a sub-object: videojs.dom. Each will log an appropriate warning, but continue functioning for the lifetime of Video.js 6. For cross-compatibility, one potential shortcut is:

var vjsDom = videojs.dom || videojs;

vjsDom.addClass(el, 'my-class');

Removals

Some methods (but not all) that were deprecated in 5 are removed in 6. These will now cause errors to be thrown.

Component.extend

Instead of calling Component.extend() to create new components, use videojs.extend() or ES6 classes:

var MyComponent = videojs.extend(Component, {...});

videojs.registerComponent('MyComponent', MyComponent);

or

class MyComponent extends Component {...};

videojs.registerComponent('MyComponent', MyComponent);