13 KiB
Video.js Plugins
One of the great strengths of Video.js is its ecosystem of plugins that allow authors from all over the world to share their video player customizations. This includes everything from the simplest UI tweaks to new playback technologies and source handlers!
Because we view plugins as such an important part of Video.js, the organization is committed to maintaining a robust set of tools for plugin authorship:
-
A Yeoman generator for scaffolding a Video.js plugin project. Additionally, it offers a set of conventions for plugin authorship that, if followed, make authorship, contribution, and usage consistent and predictable.
In short, the generator sets up plugin authors to focus on writing their plugin - not messing with tools.
Writing a Basic Plugin
If you've written a Video.js plugin before, the basic plugin concept should be familiar. It's similar to a jQuery plugin in that the core idea is that you're adding a method to the player.
Write a JavaScript Function
A basic plugin is a plain JavaScript function:
function examplePlugin(options) {
if (options.customClass) {
this.addClass(options.customClass);
}
this.on('playing', function() {
videojs.log('playback began!');
});
}
By convention, plugins are passed an options
object; however, you can realistically accept whatever arguments you want. This example plugin will add a custom class (whatever is passed in as options.customClass
) and, whenever playback begins, it will log a message to the browser console.
Note: The value of
this
in the plugin function is the player instance; so, you have access to its complete API.
Register a Basic Plugin
Now that we have a function that does something with a player, all that's left is to register the plugin with Video.js:
videojs.registerPlugin('examplePlugin', examplePlugin);
After that, any player will automatically have an examplePlugin
method on its prototype!
Note: The only stipulation with the name of the plugin is that it cannot conflict with any existing plugin or player method.
Writing an Advanced Plugin
Video.js 6 introduced advanced plugins: these are plugins that share a similar API with basic plugins, but are class-based and offer a range of extra features out of the box.
While reading the following sections, you may want to refer to the Plugin API docs for more detail.
Write a JavaScript Class/Constructor
If you're familiar with creating components, this process is similar. An advanced plugin starts with a JavaScript class (a.k.a. a constructor function).
If you're using ES6 already, you can use that syntax with your transpiler/language of choice (Babel, TypeScript, etc):
const Plugin = videojs.getPlugin('plugin');
class ExamplePlugin extends Plugin {
constructor(player, options) {
super(player, options);
if (options.customClass) {
player.addClass(options.customClass);
}
player.on('playing', function() {
videojs.log('playback began!');
});
}
}
Or with ES5:
var Plugin = videojs.getPlugin('plugin');
var ExamplePlugin = videojs.extend(Plugin, {
constructor: function(player, options) {
Plugin.call(this, player, options);
if (options.customClass) {
player.addClass(options.customClass);
}
player.on('playing', function() {
videojs.log('playback began!');
});
}
});
For now, this example advanced plugin does the exact same thing as the basic plugin described above - not to worry, we will make it more interesting as we continue!
Register an Advanced Plugin
The registration process for advanced plugins is identical to the process for basic plugins.
videojs.registerPlugin('examplePlugin', ExamplePlugin);
Note: Because ES6 classes are syntactic sugar on top of existing constructor function and prototype architecture in JavaScript, in all cases
registerPlugin
's second argument is a function.
Key Differences from Basic Plugins
Advanced plugins have two key differences from basic plugins that are important to understand before describing their advanced features.
The Value of this
With basic plugins, the value of this
in the plugin function will be the player.
With advanced plugins, the value of this
is the instance of the plugin class. The player is passed to the plugin constructor as its first argument (and is automatically applied to the plugin instance as the player
property) and any further arguments are passed after that.
The Player Plugin Name Property
Both basic plugins and advanced plugins are set up by calling a method on a player with a name matching the plugin (e.g., player.examplePlugin()
).
However, with advanced plugins, this method acts like a factory function and it is replaced for the current player by a new function which returns the plugin instance:
// `examplePlugin` has not been called, so it is a factory function.
player.examplePlugin();
// `examplePlugin` is now a function that returns the same instance of
// `ExamplePlugin` that was generated by the previous call.
player.examplePlugin().someMethodName();
With basic plugins, the method does not change - it is always the same function. It is up to the authors of basic plugins to deal with multiple calls to their plugin function.
Features of Advanced Plugins
Up to this point, our example advanced plugin is functionally identical to our example basic plugin. However, advanced plugins bring with them a great deal of benefit that is not built into basic plugins.
Events
Like components, advanced plugins offer an implementation of events. This includes:
-
The ability to listen for events on the plugin instance using
on
orone
:player.examplePlugin().on('example-event', function() { videojs.log('example plugin received an example-event'); });
-
The ability to
trigger
custom events on a plugin instance:player.examplePlugin().trigger('example-event');
-
The ability to stop listening to custom events on a plugin instance using
off
:player.examplePlugin().off('example-event');
By offering a built-in events system, advanced plugins offer a wider range of options for code structure with a pattern familiar to most web developers.
Extra Event Data
All events triggered by plugins include an additional data object as a second argument. This object has three properties:
name
: The name of the plugin (e.g."examplePlugin"
) as a string.plugin
: The plugin constructor (e.g.ExamplePlugin
).instance
: The plugin constructor instance.
Statefulness
A new concept introduced for advanced plugins is statefulness. This is similar to React components' state
property and setState
method.
Advanced plugin instances each have a state
property, which is a plain JavaScript object - it can contain any keys and values the plugin author wants.
A default state
can be provided by adding a static property to a plugin constructor:
ExamplePlugin.defaultState = {
customClass: 'default-custom-class'
};
When the state
is updated via the setState
method, the plugin instance fires a "statechanged"
event, but only if something changed! This event can be used as a signal to update the DOM or perform some other action. The event object passed to listeners for this event includes, an object describing the changes that occurred on the state
property:
player.examplePlugin().on('statechanged', function(e) {
if (e.changes && e.changes.customClass) {
this.player
.removeClass(e.changes.customClass.from)
.addClass(e.changes.customClass.to);
}
});
player.examplePlugin().setState({customClass: 'another-custom-class'});
Lifecycle
Like components, advanced plugins have a lifecycle. They can be created with their factory function and they can be destroyed using their dispose
method:
// set up a example plugin instance
player.examplePlugin();
// dispose of it anytime thereafter
player.examplePlugin().dispose();
The dispose
method has several effects:
- Triggers a
"dispose"
event on the plugin instance. - Cleans up all event listeners on the plugin instance, which helps avoid errors caused by events being triggered after an object is cleaned up.
- Removes plugin state and references to the player to avoid memory leaks.
- Reverts the player's named property (e.g.
player.examplePlugin
) back to the original factory function, so the plugin can be set up again.
In addition, if the player is disposed, the disposal of all its advanced plugin instances will be triggered as well.
Version
Adding a version number to a plugin is done by defining a VERSION
property on the plugin before registering it:
ExamplePlugin.VERSION = '1.0.1';
videojs.registerPlugin('examplePlugin', ExamplePlugin);
Retrieve it using videojs.getPluginVersion
:
var version = videojs.getPluginVersion('examplePlugin');
console.log(version); // 1.0.1
Note that the plugin generator already takes care of adding a version number for you.
Logging
By default, each advanced plugin instance has its own log
property much like videojs
and Player
instances do. The log messages will be prefixed with the player's ID and the plugin's name:
player.examplePlugin().log('hello world!');
The above will log the following:
VIDEOJS: $PLAYER_ID: examplePlugin: hello world!
The log
function will also have all the methods/properties of the default videojs.log
; such as, error()
, warn()
, level()
, etc.
NOTE: This method is added in the constructor and it will not override any predefined
log
property of the plugin's prototype.
Advanced Example Advanced Plugin
What follows is a complete ES6 advanced plugin that logs a custom message when the player's state changes between playing and pause. It uses all the described advanced features:
import videojs from 'video.js';
const Plugin = videojs.getPlugin('plugin');
class Advanced extends Plugin {
constructor(player, options) {
super(player, options);
// Whenever the player emits a playing or pause event, we update the
// state if necessary.
this.on(player, ['playing', 'pause'], this.updateState);
this.on('statechanged', this.logState);
}
dispose() {
super.dispose();
videojs.log('the advanced plugin is being disposed');
}
updateState() {
this.setState({playing: !this.player.paused()});
}
logState(changed) {
videojs.log(`the player is now ${this.state.playing ? 'playing' : 'paused'}`);
}
}
videojs.registerPlugin('advanced', Advanced);
const player = videojs('example-player');
player.advanced();
// This will begin playback, which will trigger a "playing" event, which will
// update the state of the plugin, which will cause a message to be logged.
player.play();
// This will pause playback, which will trigger a "paused" event, which will
// update the state of the plugin, which will cause a message to be logged.
player.pause();
player.advanced().dispose();
// This will begin playback, but the plugin has been disposed, so it will not
// log any messages.
player.play();
This example may be a bit pointless in reality, but it demonstrates the sort of flexibility offered by advanced plugins over basic plugins.
Setting up a Plugin
There are two ways to set up (or initialize) a plugin on a player. Both ways work identically for both basic and advanced plugins.
The first way is during creation of the player. Using the plugins
option, a plugin can be automatically set up on a player:
videojs('example-player', {
plugins: {
examplePlugin: {
customClass: 'example-class'
}
}
});
Otherwise, a plugin can be manually set up:
var player = videojs('example-player');
player.examplePlugin({customClass: 'example-class'});
These two methods are functionally identical - use whichever you prefer!
Plugin Setup Events
Occasionally, a use-case arises where some code needs to wait for a plugin to be initialized. As of Video.js 6, this can be achieved by listening for pluginsetup
events on the player.
For any given plugin initialization, there are four events to be aware of:
beforepluginsetup
: Triggered immediately before any plugin is initialized.beforepluginsetup:examplePlugin
Triggered immediately before theexamplePlugin
is initialized.pluginsetup
: Triggered after any plugin is initialized.pluginsetup:examplePlugin
: Triggered after heexamplePlugin
is initialized.
These events work for both basic and advanced plugins. They are triggered on the player and each includes an object of extra event data as a second argument to its listeners.