Player Events

Overview

The Brightcove Player has many events for you to control video playback. This topic provides an overview about the different types of events.

A complete list of Brightcove Player events can be found in the Player Methods/Events API reference document. This document reflects the events that are part of the actual code that makes up the player.

Media events

The HTML Living Standard document is a great resource for information about the development of HTML and the APIs needed for web applications. This is a "living" document that is kept current by the Web Hypertext Application Technology Working Group (WHATWG), which is a growing community of people interested in evolving the web.

The Brightcove Player runs on top of the HTML framework, which triggers the following Media Events.

Here are some terms associated with events in this document:

blocked

A MediaController is considered blocked if playback has been paused. A media element is blocked if its controller is a blocked media controller.

MediaController

A MediaController is an object that coordinates the playback of multiple media elements.

media element

A media element presents audio data, or video and audio data, to the user.

slaved

By default each media element has no MediaController. When media elements are associated with a MediaController, they are said to be slaved to the controller. The controller modifies the playback rate and volume of each of the media elements slaved to it. If one of the slaved elements stalls unexpectedly, the controller will stop the other slaved elements.

Buffering and QoS events

Here is a subset of events related to buffering and quality of service (QoS):

Startup events

There are a number of events that occur when the player is initialized and prepares to play a video. They are listed here in the order they will be dispatched:

• loadstart: Dispatched when the player is initialized, and if it’s re-initialized in the case of giving it a new source to play

• loadedmetadata: Dispatched when the player has initial duration and dimension information, in other words, when the first segment is downloaded. For live videos the loadedmetadata event won't be dispatched until the user clicks play. This is because live videos don't start downloading segments until the user clicks play.
• loadeddata: Dispatched when the player has downloaded data at the current playback position

The following CodePen shows the startup events being listened for and dispatched. Note that if you mouse over the CodePen, you can click the RERUN button located in the bottom-right to see the events dispatch again. If you wish to experiment with the code, click the Edit on CODEPEN link in the header to move to the editing environment. You can click the JS button to see the JavaScript that add the event listeners.

See the Pen Startup Events Demo by Brightcove Learning Services (@bcls) on CodePen.

ready() method

The ready() method has a dual personality in that it seems like an event, but you use it like a method. This method/event means the player is ready to receive commands.

The ready() method differs from event listeners in that if the ready event has already happened it will trigger the ready() method immediately. You will often see the method used as follows to provide the starting point for development with Brightcove Player:

videojs.getPlayer('myPlayerID').ready(function(){
  var myPlayer = this;
});

ready() vs. on('loadedmetadata',...)

Note that using ready() functions correctly if you wish to interact with the player, for instance programmatically add a plugin. If you wish to immediately interact with the video, for instance use play(), the code snippet above will not always work correctly. A better approach would be to listen for the loadedmetadata to interact with the video, for instance:

videojs.getPlayer('myPlayerID').on('loadedmetadata',function(){
  var myPlayer = this;
  myPlayer.play();
});

In summary, to interact with the player you can use this:

videojs.getPlayer('myPlayerID').ready()

If you wish to immediately interact with the video in the player use this:

videojs.getPlayer('myPlayerID').on('loadedmetadata',function(){})

Ad events

To include advertisement libraries and functionality to your player, you can use the IMA3 Plugin or the FreeWheel Plugin. This is built on top of the videojs ads framework (videojs-contrib-ads). Both of these advertising plugins can dispatch the ad events shown in the following table. Each also have specific events particular to the implementation.

bc-catalog-error event

It is possible that handling errors in the normal ready() section in the script block can cause issues. For instance, it can happen that the bc-catalog-error event could be dispatched before the player is ready, and if you listen for the error in the ready() section, you will not be able to handle the error. This issue can occur when using geo-filtering, a video is unpublished, a video is out of scheduling range, or in a different account. For a complete discussion and examples handling the bc-catalog-error event, see the Player Catalog document.

progress and timeupdate

Confusion can occur about the differences between the progress and timeupdate events. The Brightcove Player builds on top of HTML5 video, and in that standard the progress event is dispatched when the browser is downloading data. The timeupdate event is dispatched when the current playback position has changed.

This can be confusing to users of Brightcove's Smart Player, as in that API the progress event does what timeupdate does in the Brightcove Player API.

Caution removing timeupdate listeners

In some cases you might want to remove an event listener you have added to the timeupdate event. A use case is shown in the Brightcove Player Sample: Registering to Play after Preview document. In this situation, you want the player to pause in some time range, and you are using timeupdate for the time check, then use an anonymous event handler function definition. You only want to pause once, so you need to remove the event listener. You do NOT want to simply do:

myPlayer.off('timeupdate');

Of course, this removes ALL event listeners to timeupdate, and among other issues doing this will prevent the time scrubber from advancing. What needs to be done is create a function using normal function definition syntax (a function declaration), then remove JUST the one event listener. The abbreviated code is shown here:

 // Add the event handler
myPlayer.on('timeupdate', timeupdateHandler);

// Handle the event then remove JUST this event listener on timeupdate
function timeupdateHandler(evt) {
  ...
  myPlayer.off('timeupdate', timeupdateHandler);
}

Analytics events

An event is triggered each time a beacon is sent to the Analytics data collector. You can listen for any beacon or specific ones.

Listen for all beacons

You can track all analytics beacons sent by listening for the analytics-beacon event:

player.on('analytics-beacon', function(e) {
  videojs.log('sent a(n) ' + e.params.event + ' beacon!', e.params);
});

Listen for specific beacons

You can track specific analytics beacons sent by listening for the analytics-beacon-{beacon_name} event.

{beacon_name} is the name of any of the player events that are sent to the data collector. For a complete list of these events, see the Data Collection API Reference.

Example

player.on('analytics-beacon-video-impression', function(e) {
  videojs.log('sent an impression beacon!', e.params);
});

No support for method chaining

As of version 6 of Brightcove Player method chaining with events is no longer supported. This means you CANNOT do this:

player.on(event, function () {})
.on(event, function () {})
.on(event, function () {})
.on(event, function () {});