Mux

The Mux Developer Hub

Welcome to the Mux developer hub. You'll find comprehensive guides and documentation to help you start working with Mux as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Custom Errors

Mux currently tracks fatal errors that are triggered by the player in use. However, in certain cases this may not be ideal.

Triggering Custom Errors

Certain players, such as some third-party HLS libraries for web players, may have fatal errors that occur outside of the context of the player. To handle these cases, Mux exposes a type of event that can be triggered via Javascript.

This event should only be used for fatal errors. Do not use this for "errors" that do not result in playback failure.

mux.emit('#myVideo', 'error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
player.mux.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
player.mux.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
player.mux.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
player.mux.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
player.mux.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
player.mux.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
// Available in theoplayer-mux v2.4.0 and newer.
var monitor = initTHEOplayerMux(player, options);

monitor.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
player.mux.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});
There is currently no way to fire custom error events 
for CTS PDK players. If this is necessary, reach out 
to us! [email protected]
There is currently no way to fire custom error events for Akamai Media Player. If this is necessary, reach out to us! [email protected]
var shakaPlayerMux = initShakaPlayerMux(player, options);

shakaPlayerMux.emit('error', {
  player_error_code: 100,
  player_error_message: 'Description of error'
});

When triggering an error event, it is important to provide a player_error_code and player_error_message in an object as the second parameter. The player_error_message should provide a detailed description of the error as it happened. The player_error_code must be an integer, and should provide a category of the error. If the errors match up with the HTML Media Element Error, you can use the same codes as the corresponding HTML errors. However, for custom errors, you should choose a number greater than or equal to 100. Whether all errors use the same code or you use different codes for different types of errors is up to you. In general you should not send a distinct code for each possible error message, but rather group similar errors under the same code. For instance, if your library has two different conditions for network errors, both should have the same player_error_code but different messages.

Automatic Error Tracking

In certain cases, the automatic error tracking built into Mux's SDKs may not work as expected. For instance, some players may expose error events for errors that are not fatal to playback, while others may expose unclear/incorrect information in the default error message and codes. To handle these situations, Mux exposes two options: translating each error via a custom callback, or turning off automatic error handling.

Translating Errors

Sometimes you may want to have a little bit more control over the errors that are triggered by the player, but you want to rely on the basic error tracking for the most part. In this case, the Mux SDKs support an errorTranslator callback, provided when each SDK is initialized.

This callback is a function that you provide to Mux that is called for each error. The callback will be called with a single argument, which is an object with two keys: player_error_code and player_error_message. The callback should return a new object with the updated player_error_code and player_error_message, which will be used as the code and message for the error.

var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

mux.monitor('#myVideo', {
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required
    
    // ... additional metadata
  }
});
var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

videojs('my-player', {
  plugins: {
    mux: {
      debug: false,
      errorTranslator: errorTranslator,
      data: {
        env_key: 'EXAMPLE_ENV_KEY', // required
        
        // ... additional metadata
      }
    }
  }
});
// Configuring the errorTranslator is only available
// for players instantiated in-page.
var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

player.mux({
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required

    // ... and other metadata
  }
});
var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

player.mux({
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required

    // ... and other metadata
  }
});
var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

initJWPlayerMux(player, {
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required
    
    // ... and other metadata
  }
});
var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

initBitmovinMux(player, {
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required
    
    // ... and other metadata
  }
});
var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

initOoyalaMux(player, {
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required
    
    // ... and other metadata
  }
});
var errorTranslator = function (error) {
    return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

var monitor = initTHEOplayerMux(player, {
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required
    
    // ... and other metadata
  }
});
var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

initFlowplayerMux(player, {
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required
    
    // ... and other metadata
  }
});
There is currently no way to configure a custom error 
translator for CTS PDK players. If this is necessary, 
reach out to us! [email protected]
var errorTranslator = function (error) {
  return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

akamai.amp.AMP.create("#akamai-media-player", {
  // ... other player configuration
  plugins: {
    mux: {
      resources: [
        {src: "http://src.litix.io/akamai/1/akamai-mux.js", type: "text/javascript"},
      ],
      debug : false,
      errorTranslator: errorTranslator,
      data: {
        env_key: 'EXAMPLE_ENV_KEY', // required

        // ... and other metadata
      }
    }
  }
});
var errorTranslator = function (error) {
    return {
    player_error_code: translateCode(error.player_error_code),
    player_error_message: translateMessage(error.player_error_message),
  };
}

var shakaPlayerMux = initShakaPlayerMux(player, {
  debug: false,
  errorTranslator: errorTranslator,
  data: {
    env_key: 'EXAMPLE_ENV_KEY', // required
    
    // ... and other metadata
  }
});

In the case that the error that was triggered is one that you would like to ignore, you can return false in the errorTranslator and Mux will not track that as a fatal error. Use this if you know of situations and error code/message combinations that your player will fire that are not fatal playback errors.

You should perform a little processing as possible in this callback, and i the case that an exception is raised, the original error will be used.

Disabling Automatic Error Tracking

In the case that you want full control over what errors are counted as fatal or not, you may want to consider turning off Mux's automatic error tracking completely. This can be done by passing automaticErrorTracking: false in the configuration object passed to Mux when monitoring a player.

var options = {
  debug: false,
  automaticErrorTracking: false,
  data: { ... }
}

// e.g. for HTML5
mux.monitor('#myVideo', options);

Note: This should only be utilized for players where sending custom events is possible, or the result will be no playback errors tracked at all.

Supported versions

The above options (errorTranslator and automaticErrorTracking) are available in the following Mux SDK versions:

  • HTML5 - v2.7.0+
  • videojs-mux - v2.5.0+
  • jw-mux - v2.4.0+
  • bitmovin-mux - v2.4.0+
  • ooyala-mux - v2.4.0+
  • theoplayer-mux - v2.4.0+
  • flowplayer-mux - v1.3.0+
  • cts-mux - Not supported
  • akamaimediaplayer-mux - v1.3.0+
  • shakaplayer-mux - v1.0.0+

Updated about a year ago

Custom Errors


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.