hooks

Hooks

Hooks exist so that users can globally hook into certain Video.js lifecycle moments.

Table of Contents

Current Hooks

Currently, the following hooks are available:

beforesetup

beforesetup occurs just before a player is created. This allows:

  • Modification of the options passed to the Video.js function (e.g., videojs('some-id, options)).
  • Modification of the DOM video element that will be used for the player that will be created.

beforesetup hook functions should:

  • Take two arguments:
    1. videoEl: DOM <video> element that Video.js is going to use to create a player.
    2. options: The options object that Video.js was called with and will be passed to the player during creation.
  • Return an options object that will be merged with the originally provided options.

Example

videojs.hook('beforesetup', function(videoEl, options) {

  // videoEl will be the video element with id="some-id" since that
  // gets passed to videojs() below. On subsequent calls, it will be
  // different.

  videoEl.className += ' some-super-class';

  // autoplay will be true here, since we passed it as such.
  if (options.autoplay) {
    options.autoplay = false
  }

  // Options that are returned here will be merged with old options.
  //
  // In this example options will now be:
  //   {autoplay: false, controls: true}
  //
  // This has the practical effect of always disabling autoplay no matter
  // what options are passed to videojs().
  return options;
});

// Create a new player.
videojs('some-id', {autoplay: true, controls: true});

setup

setup occurs just after a player is created. This allows:

  • Plugins or other custom functionality to initialize on the player.
  • Changes to the player object itself.

setup hook functions:

  • Take one argument:
    1. player: the player that Video.js created
  • Don't have to return anything

Example

videojs.registerPlugin('foo', function() {

  // This basic plugin will add the "some-super-class" class to a player.
  this.addClass('some-super-class');
});

videojs.hook('setup', function(player) {

  // Initialize the foo plugin after any player is created.
  player.foo();
});

// Create a new player.
videojs('some-id', {autoplay: true, controls: true});

beforeerror

beforeerror occurs just as we get an error on the player. This allows plugins or other custom code to intercept the error and modify it to be something else. error can be one of multiple things, most commonly an object with a code property or null which means that the current error should be cleared.

beforeerror hook functions:

  • Take two arguments:
    1. The player that the error is happening on.
    2. The error object that was passed in.
  • Return an error object that should replace the error

Example

videojs.hook('beforeerror', function(player, err) {
  const error = player.error();

  // prevent current error from being cleared out
  if (err === null) {
    return error;
  }

  // but allow changing to a new error
  return err;
});

error

error occurs after the player has errored out, after beforeerror has allowed updating the error, and after an error event has been triggered on the player in question. It is purely an informative event which allows you to get all errors from all players.

error hook functions:

  • Take two arguments:
    1. player: the player that the error occurred on
    2. error: the Error object that was resolved with the beforeerror hooks
  • Don't have to return anything

Example

videojs.hook('error', function(player, err) {
  console.log(`player ${player.id()} has errored out with code ${err.code} ${err.message}`);
});

Usage

Adding

Hooks can be added using videojs.hook(<name>, function) before running the videojs() function.

Example

videojs.hook('beforesetup', function(videoEl, options) {
  // This hook will be called twice. Once for "vid1" and once for "vid2".
  // The options will match what is passed to videojs() for each of them.
});

videojs.hook('setup', function(player) {
  // This hook will be called twice. Once for "vid1" and once for "vid2".
  // The player value will be the player that is created for each element.
});

videojs('vid1', {autoplay: false});
videojs('vid2', {autoplay: true});

After adding your hooks, they will automatically be run at the correct time in the Video.js lifecycle.

Adding Once

In some cases, you may only want your hook to run once. In these cases, use videojs.hookOnce(<name>, function) before running the videojs() function.

Example

videojs.hookOnce('beforesetup', function(videoEl, options) {
  // This hook will be called once for "vid1", but not for "vid2".
  // The options will match what is passed to videojs().
});

videojs.hookOnce('setup', function(player) {
  // This hook will be called once for "vid1", but not for "vid2".
  // The player value will be the player that is created for each element.
});

videojs('vid1', {autoplay: false});
videojs('vid2', {autoplay: true});

Getting

To access the array of functions that currently exists for any hook, use the videojs.hooks function.

Example

// Get an array of all the 'beforesetup' hooks.
var beforeSetupHooks = videojs.hooks('beforesetup');

// Get an array of all the 'setup' hooks.
var setupHooks = videojs.hooks('setup');

Removing

To stop hooks from being executed during any future Video.js lifecycles you can remove them using videojs.removeHook.

Example

var beforeSetup = function(videoEl, options) {};

// Add the hook.
videojs.hook('beforesetup', beforeSetup);

// Remove the same hook.
videojs.removeHook('beforesetup', beforeSetup);