Video.js - HTML5 Video Player

Video.js Blog

Brandon Casey2018-02-21

videojs-vr Is Now Under The Video.js Org

Brightcove and Video.js have adopted the videojs-vr plugin as a first class plugin. It's out now with support for Video.js 6!

Where did it come from?

This plugin has a long history and has had many maintainers. It started as slawrence/videojs-vr. From there it became metacdn/videojs-vr. Then there was a private collaberation between StreamShark.io, Brightcove, and HapYak. Eventually we decided to treat this plugin like a first class citizen. So we updated it to the advanced plugin API, fixed a few long-standing issues, documented other issues along the way, and moved it to the Video.js Organization.

How do you know a video is 360/VR?

On desktop players

In a non-browser environment this question is easily answered, because there is a generally agreed upon standard. The video itself should have metadata indicating that the video is a 360/VR video and how to display it. Even outside of the browser though it is a bit tricky because most programs (even ffmpeg) don't support the insertion of this metadata. In fact a lot of them will strip said metadata as they think it is invalid. That is where a project called Spatial Media Metadata Injector comes in. Spatial Media Metadata Injector injects 360/VR metadata into the video without changing anything else. That allows players like VLC to know that a video is 360/VR.

How does videojs-vr do it?

The browser does not expose video metadata in an API so we would have to parse it ourselves, which isn't really an option. So in videojs-vr we have a projection option that can be passed in during plugin initialization.

The first and default setting for projection is 'AUTO'. Setting projection to 'AUTO' tells videojs-vr to look at player.mediainfo.projection. player.mediainfo.projection will have to be set by some external plugin/script which is told by a server that the current video is 360/VR. The player.mediainfo.projection of a video can be any of the following:

  • '360', 'Sphere', or 'equirectangular': The video is a sphere
  • 'Cube' or '360_CUBE': The video is a cube
  • 'NONE': This video is not a 360 video, the videojs-vr plugin should do nothing. this would not have to be set as it will be assumed if no projection exists.
  • '360_LR': Used for side-by-side 360 videos
  • '360_TB': Used for top-to-bottom 360 videos

Otherwise, the projection can manually be set on plugin initialization to any of the above values. The plugin can then be disposed and re-initialized for each video with a different setting.

What happens after after we know a video is 360/VR?

Using the current projection value we determine what we need to show on our three.js canvas. From there we use the polyfilled (via webvr-polyfill or real VRDisplay API to set up controls. If the device has a VIVE, Oculus, etc plugged in we use that. If not we display the video in 360 mode where the mouse/keyboard/accelerometer control the video. On mobile devies there is also a button to go into cardboard mode which will show the video as two smaller videos separated by a line. This is so that the video can be viewed using pseudo VR headsets (such as google cardboard) and a phone. While the video is playing we use animation frames to animate the VideoTexture on the three.js canvas. That allows us to show the correct portion of the video based on the controls that the user is inputting.

Why is it so huge?

We all agree that the plugin is huge, but due to the fact that all browsers do not natively support the VRDisplay API, we have to include a lot of big dependencies in our project. Mainly the size comes from the following:

  1. [three.js](https://github.com/mrdoob/three.js) which we use to create the VR/360 canvas, and implementing it on our own would be painful

  2. [webvr-polyfill](https://github.com/googlevr/webvr-polyfill) which polyfills VR features for browsers that don't currently support VR (outside of experimental flags and builds)

Debugging

Every object from three.js and webvr manager (from webvr-boilerplate) is available on the instance of the VR plugin that will is returned by player.vr().

Known Issues

  • Multiple players on the same page will share controls, panning in one video will pan in the other.

The Future

  • Implementing player level controls rather than window controls. This will allow individual videos to be controlled separately based on the current focus.
  • A menu so that multiple VR displays can be used rather than just the first one that we find.

To see the code, submit an issue, suggest a feature, or submit a pr

See the github repo videojs-vr

Gary Katsevman2017-04-03

Video.js 6.0 Release!

After months of hard work, I am proud to annouce the release of Video.js 6.0 🎉!

This release is pretty exciting. It greatly improves the accessibility of the controls and components, and we are committed to making Video.js the most accessible player we can. Video.js also provides some shiny, and awesome, new features for developers in middleware and advanced plugins. Video.js 6.0 is also the first release where Flash is unbundled from core -- though, it is still available as a plugin, if necessary.

Today's release is a pre-release and will stay that way for about a week or two before being promoted to latest. Just to make sure that any last bugs, if any, are ironed out.

Things you should know

Most things have not changed between 5.x and 6.x. In fact, in most of our work in plugins we maintain, the majority of the work was to use new methods and fallback to old methods because they were logging deprecation warnings. Those plugins would've continued working otherwise.

However, there are definitely some changes that are breaking and would require action on your part. For example, if you require Flash, that's something that would now need to be included manually.

One of the other big changes is that source selection is now asynchronous. This was necessary for middleware support and most likely won't affect users if they are waiting for the player to be ready before interacting with the player.

These are written up on our wiki. We'll make sure to update it if there's anything that we missed.

Feedback Wanted

If you are using Video.js and have comments or questions, please drop by on Slack. If you find a bug, please open an issue on GitHub, preferably with a reduced test case.

5.x Support

We're still going to be supporting the Video.js 5.x release line. This will mostly be bug fixes but features will be considered on a case-by-case basis.

If IE8 support is still required, it is probably best to stick to 5.x.

npm tags

Once Video.js 6 is promoted to latest, it'll take over the next and latest tags on npm. The 5.x release line will then be given its own set of tags: latest-5 and next-5.

Code of Condunct

We strive to be open and inclusive and so we have adopted a Code of Conduct, based on Contributor Covenant that applies to all Video.js projects.

Conclusion

We are super excited for this release! Please take it for a spin from next tag on npm or from the CDN. And please come chat with us on Slack.

Pat O'Neill2017-01-26

Feature Spotlight: Advanced Plugins

Note: Advanced plugins are being introduced in Video.js 6.0 and are only supported from that version forward.

If you've been a Video.js user for a while, you're likely familiar with the concept of plugins: functions that become methods of any player you create. If you're not familiar with Video.js plugins, we have a comprehensive plugins guide available.

These plugins - which we'll call basic plugins - are lightweight and offer complete control of the player. That's really useful and it isn't changing - existing plugins should continue to work!

But what if you want a richer set of features? Or more guidance on how to structure your plugin? Or more tools out of the box that help manage complex plugin-rich players?

Well, until Video.js 6.0, you had to figure things out on your own.

Introducing Advanced Plugins

One of Video.js' strengths is its rich ecosystem of plugins; so, in the last few months, we wanted to focus our efforts on improving the plugin author experience.

While projects like the plugin generator and videojs-spellbook make becoming a plugin author easier than ever, the Video.js team thought it was important to provide a foundational API and set of conventions on which the future of Video.js plugins could be built.

Our solution is advanced plugins.

Advanced Plugins are Component-Like

One of the design goals for advanced plugins was to provide an API that was reminiscent of the existing components system. We achieved this in a number of ways.

At the lowest level, this included a name change for the plugin registration function from videojs.plugin to videojs.registerPlugin (taking a naming cue from videojs.registerComponent and videojs.registerTech).

Beyond a simple registration method name change, advanced plugins are class-based. A trivial example of an advanced plugin might look something like this:

const Plugin = videojs.getPlugin('plugin');

class HelloWorld extends Plugin {
  constructor(player) {
    super(player);
    this.player.addClass('hello-world');
  }
}

videojs.registerPlugin('helloWorld', HelloWorld);

This plugin can be initialized in the same way as a basic plugin - via a player method whose name matches the registered name of the plugin.

In the case of advanced plugins, this method is a factory function, which instantiates the plugin class and returns an instance.

It's useful to know that the player method that is created will always be a function. If a player already has an instance of an advanced plugin, its associated method will simply return the pre-existing instance rather than re-initialize it:

const player = videojs('my-player');
const instance = player.helloWorld();

// Logs: 'true'
videojs.log(instance === player.helloWorld());

The helloWorld method will return this plugin object until it is disposed - after which it will create a new plugin instance again.

Events

Similar to components, advanced plugins can listen to and trigger events via the on, one, off, and trigger methods.

This provides a loosely coupled communication channel for plugins and other objects (components, players, etc) to manage their own state and respond to changes in the state of one another.

Additional Event Data

The Video.js event system allows additional data to be passed to listeners as a second argument when triggering events (the first argument is the event object itself).

Plugin events pass a consistent set of properties in this object (including any custom properties passed to trigger):

  • instance: The plugin instance, which triggered the event.
  • name: The name of the plugin as a string (e.g. 'helloWorld').
  • plugin: The plugin class/constructor function (e.g. HelloWorld).

For example, a listener for an event on a plugin can expect something like this:

const player = videojs('my-player');
const instance = player.helloWorld();

instance.on('some-custom-event', (e, data) => {
  videojs.log(data.instance === instance); // true
  videojs.log(data.name === 'helloWorld'); // true
  videojs.log(data.plugin === videojs.getPlugin('helloWorld')); // true
  videojs.log(data.foo); // "bar"
});

instance.trigger('some-custom-event', {foo: 'bar'});

Lifecycle

Another similarity between plugins and components is the concept of a lifecycle - more specifically, setup and teardown processes.

We get the setup feature as a side effect of normal object creation in JavaScript, but we are left to our own devices when it comes to object destruction and ensuring that references between objects are cleaned up to avoid leaking memory.

Video.js components have long had a dispose method and event that deal with removing a component from the DOM and memory. Advanced plugins have the same feature:

const player = videojs('my-player');

const firstInstance = player.helloWorld();

// Logs: 'true'
videojs.log(firstInstance === player.helloWorld());

firstInstance.on('dispose', () => videojs.log('disposing a helloWorld instance'));

// Logs: 'disposing a helloWorld instance'
firstInstance.dispose();

const secondInstance = player.helloWorld(); 

// Logs: 'false'
videojs.log(firstInstance === secondInstance);

The pluginsetup Event

Plugins do have one lifecycle feature that components do not: the pluginsetup event.

This event is triggered on a player when a plugin is initialized on it:

const player = videojs('my-player');

player.on('pluginsetup', (e, hash) => {
  if (hash.name === 'helloWorld') {
    videojs.log('A helloWorld instance was created!');
  }
});

// Logs: 'A helloWorld instance was created!'
player.helloWorld();

React-inspired Statefulness

One of the exciting additions in Video.js for both advanced plugins and components is React-inspired statefulness. Essentially, this means that all plugin objects and component objects have a state property, which is a plain object that can be used to store variable state for that object. Then, there is a setState method that updates this object and triggers a statechanged event.

This system allows plugins and components to use their evented nature to communicate in-memory state changes through a consistent API:

// A static property of the constructor can be used to pre-populate state 
// for all instances.
HelloWorld.defaultState = {color: 'red'};

const player = videojs('my-player');
const instance = player.helloWorld();

instance.on('statechanged', (e) => {
  const {color} = e.changes;

  if (color) {
    videojs.log(`The helloWorld color changed from "${color.from}" to "${color.to}"!`);
  }
});

// Logs: 'The helloWorld color changed from "red" to "blue"!'
instance.setState({color: 'blue'}); 

Player Plugin Awareness

Finally, we couldn't add new plugin infrastructure without working on one of the more pernicious problems of managing complex combinations of plugins: the player can't report which plugins it has initialized - or not. To this end, the player has two new methods: hasPlugin and usingPlugin. These methods work for both types of plugins.

The hasPlugin Method

This method reports whether a plugin matching a given name is available on the player:

const player = videojs('my-player');

// Logs: 'true'
videojs.log(player.hasPlugin('helloWorld'));

// Logs: 'false'
videojs.log(player.hasPlugin('fooBar'));

This method ignores whether or not the plugin has been initialized and merely reports whether or not it has been registered.

The usingPlugin Method

This method reports not only whether a plugin is available on a player, but whether it is currently active on the player:

const player = videojs('my-player');

// Logs: 'false'
videojs.log(player.usingPlugin('helloWorld'));

player.helloWorld();

// Logs: 'true'
videojs.log(player.usingPlugin('helloWorld'));

One caveat to note here. While this works for both types of plugins, only advanced plugins can change this value more than once. A basic plugin has no built-in lifecycle or events; so, it's not possible to determine whether one has been "disposed".

Go Forth and Code

We hope these additions and improvements to the plugin architecture will make writing Video.js plugins more pleasurable and remove some of the low-level legwork involved in ensuring plugins aren't creating memory leaks and other problems.

The design of advanced plugins is such that we can add features as 6.0 matures and we get more community feedback. As always, we strongly encourage our users to give back to the Video.js project in whatever way they can.

For a more complete discussion of plugins generally, visit the Video.js plugins guide.