This page explains the details of building JavaScript plugins for JW Player. See About JW Player Plugins for a general overview and info on embedding plugins.
Building JavaScript plugins for the JW Player requires a fairly minimal toolset. Specifically, you'll need:
We also recommend that you set up a local web server for testing. Tools like XAMPP for Windows and MAMP for Mac make this incredibly quick.
Here is a very basic example plugin, which displays some text on top of JW Player:
// Closure to prevent this code from conflicting with other scripts
(function(jwplayer){
// The initialization function, called on player setup.
var template = function(player, config, div) {
// When the player is ready, let's add some text.
player.onReady(setup);
function setup(evt) {
div.style.color = "red";
if(config.text) {
div.innerHTML = config.text;
} else {
div.innerHTML = "Hello World!";
}
};
// This function is required. Let's use it to center the text.
this.resize = function(width, height) {
div.style.position = 'absolute';
div.style.width = '100px';
div.style.height = '20px';
div.style.left = (width/2 - 50)+'px';
div.style.top = (width/2 - 10)+'px';
};
};
// This line registers above code as a 6.0 compatible plugin called "helloworld".
jwplayer().registerPlugin('helloworld', '6.0', template);
})(jwplayer);
To see this plugin in action, simply store its code as a .js file on your webserver and load it into JW Player as described in About JW Player Plugins.
First and foremost, a JavaScript plugin is a script like any other. It uses the regular JW Player JavaScript API to interact with JW Player. As part of its initialization, the plugin will get a reference to the player containing the plugin, to fire those API calls.
That said, JW Player does provide a mechanism to ease configuring the plugin, and one to place visual assets on top of the player.
Just like the player at large, plugins can have themselves tweaked using configuration options. These options are provided by publishers inside the configuration block for the plugin:
jwplayer("myElement").setup({
file: "/uploads/example.mp4",
image: "/uploads/example.jpg",
plugins: {
"/scripts/helloworld.js": {
text: 'Hello all!'
}
}
});
The player passes these configuration options forward to the plugin using with the config parameter of the initialization function. The parameter is a JavaScript object containing all options.
Every plugin has the ability to render visual assets on top of the player display. For that purpose, JW Player creates a <div> and passes that to the plugin as a parameter of the initialization function. The plugin can nest whatever HTML it wants into that div.
The -required- resize() method of a plugin is automatically called by the player whenever it gets resized. This includes the initial setup (shortly before onReady). Use this call to ensure your visuals are correctly scaled and stretched over the player display. Note the above helloworld example uses the resize() call to re-center itself over the player.
Note the player controls are also displayed on top of JW Player, possibly interfering with the plugin visuals. Plugins are z-indexed on top of the controls though, so they can obscure them if they want. If a plugin needs to be visible together with the controls, it should use the player.getSafeMargins() API call to find out which top and bottom margins are used by the player controls.
The registerPlugin() method has an interesting feature: it can be used to load an ActionScript (SWF) plugin in addition to the regular plugin JavaScript. With this feature, you can write hybrid plugins. These plugins can leverage the features and performance of Flash, but work in HTML5 mode too:
jwplayer().registerPlugin(id, target, jsPlugin, swfURL);
In Flash mode, both the JavaScript and the ActionScript plugin are instantiated. In HTML5 mode, only the JavaScript plugin is instantiated. In your plugin, you can detect which mode is active by doing a player.getRenderingMode() API call.
Since plugins are simply JavaScript, they are best tested with the debugging tools all modern browsers provide. Tracing some data to the browser console, for example, can be done with a call to console.log:
console.log("This text will appear in your browser console");
When you're happy with the functionalities of a plugin, it's time to wrap it up for release. There's a few things you should do to optimize the loading of the plugin.
We highly recommend minifying your JS using a tool like the YUI Compressor or the Google Closure Compiler. This will reduce the size of your plugin, without impacting performance.
If you're using images in your plugin, you can base64 encode and then embed them into the javascript. This will:
Many tools exist, both online and offline, to base64 encode an image. Here is an example page where you can simply upload your image and copy/paste the resulting Base64 hash.