Player API MediaEvents

Applies to Roles
Developer
Version
Brightcove 4
Modules
Player API
Edition
Express, Pro, Enterprise

This topic describes the model for the events dispatched by the VideoPlayer and VideoDisplay components. With the Brightcove 3.2 release, we have deprecated the events formerly dispatched by the VideoPlayer and VideoDisplay components (though these deprecated events will still available to ensure backwards compatibility). Instead, Brightcove provides new MediaEvents. The MediaEvents have been put in place to provide consistency in the event behavior of progressive download and streaming content. Just like the deprecated VideoEvents, MediaEvents contain position and duration properties as well as a media property that holds a reference to the MediaDTO for which the event was dispatched. We encourage you to use these new events instead of the old video events going forward.

For more information about changes in the Player API in Brightcove 3.2, see Brightcove Player API Changes. For reference information about events in the Player API, see the API Reference. For a list of the deprecated events, see Deprecated events below.

Media Events

string type constant in Player API SWC
constant in JavaScript API		 description
"mediaChange" MediaEvent.CHANGE
BCMediaEvent.CHANGE		 Dispatched when new media is loaded or cued in the video player.
"mediaBegin" MediaEvent.BEGIN
BCMediaEvent.BEGIN		 Dispatched when the media begins playing the first time, post buffer. This is the equivalent to the old "streamStart" and should be used for any tracking purposes. It will only be dispatched once for a media object, so not on replay (unless the media is loaded a second time after another piece of media is played in between).
"mediaComplete" MediaEvent.COMPLETE
BCMediaEvent.COMPLETE		 Dispatched with the media completes playback. This will only be fired once per piece of media (unless the media is loaded and completed a second time after another piece of media is played in between).
"mediaPlay" MediaEvent.PLAY
BCMediaEvent.PLAY		 Dispatched whenever media playback is begun initially or resumed after pause.
"mediaStop" MediaEvent.STOP
BCMediaEvent.STOP		 Dispatched whenever media is paused, and upon final completion of the media if the media has been previously completed (in which case, COMPLETE is not fired a second time).
"mediaBufferBegin" MediaEvent.BUFFER_BEGIN
BCMediaEvent.BUFFER_BEGIN		 Dispatched whenever the media pauses to buffer.
"mediaBufferComplete" MediaEvent.BUFFER_COMPLETE
BCMediaEvent.BUFFER_COMPLETE		 Dispatched whenever the media completes buffering. This will always be paired with a BUFFER_BEGIN event with no events in between.
"mediaSeek" MediaEvent.SEEK
BCMediaEvent.SEEK		 Dispatched whenever media is sent to a new position through the API's seek() method or because the user dragged the playhead.
"mediaProgress" MediaEvent.PROGRESS
BCMediaEvent.PROGRESS		 Dispatched every frame while the media is playing.
"mediaError" MediaEvent.ERROR
BCMediaEvent.ERROR		 Dispatched if there is an error connecting to or loading media.
"mediaVolumeChange" MediaEvent.VOLUME_CHANGE
BCMediaEvent.VOLUME_CHANGE		 Dispatched whenever the volume of the media is changed, through either the API's setVolume() method or through the user dragging a volume control.
"mediaMuteChange" MediaEvent.MUTE_CHANGE
BCMediaEvent.MUTE_CHANGE		 Dispatched whenever the mute setting of the player changes (muted or unmuted), through either the API's mute() method or through the user clicking the mute control.

Event behavior

The MediaEvents have the following expected behaviors:

  • The first event fired will always be CHANGE to notify when new media has been loaded into the player. To receive the first CHANGE event, a listener must be added in the TEMPLATE_LOADED handler as the first CHANGE fires before TEMPLATE_READY.
  • When playback is initiated, PLAY will be fired. This will occur whether the play was initiated through autostart, automatic advancing, the API or user action.
  • If there is an error connecting to or loading the media, an ERROR event will fire after PLAY.
  • If the media can be connected to, a BUFFER_BEGIN event will be dispatched.
  • After the initial buffering is completed, a BUFFER_COMPLETE event will be dispatched.
  • BEGIN will fire post-buffer and signifies that the media is connected to and playing. This will only fire once for the media playback.
  • While the media plays back, PROGRESS events will be fired every frame. These will only begin firing after BEGIN has been dispatched.
  • If there is no further buffering or pausing or seeking initiated by the user or API, the media will complete with a COMPLETE event. This will be preceded by a STOP event. There are no further events dispatched after COMPLETE unless further action is taken by the user, or initiated through the API.
  • If the user replays the media, a PLAY event is fired. There is no BEGIN event dispatched on replay. There will be no buffer events between PLAY and the constant PROGRESS events that follow.
  • If the media completes a second time, only the STOP event is dispatched. There is no COMPLETE event dispatched on replay.
  • VOLUME_CHANGE and MUTE_CHANGE events are fired whenever the events take place through either user action or API interaction. These are completely independent of the events dealing with media playback.

Exceptional behavior

There are only a few known exceptions to the consistency of events for the different types of media and media playback.

  • When dragging the playhead for streaming content while the media is currently playing, a STOP will first be dispatched as the media is paused, followed by the SEEK events as the playhead is dragged, followed by a final PLAY event as playback is resumed. For progressive download content, the media continues to play during the drag action, so the STOP/PLAY events do not fire.
  • Buffering events will always appear slightly different in different scenarios due to inconsistency in bandwidth, connections, media bitrate, etc. Sometimes there will need to be buffering after seeking, sometimes not. The player bubbles up the buffering events as they occur in the underlying media controller classes in the Flash Player, only ensuring that there are no oddities like a BUFFER_COMPLETE firing without a BUFFER_BEGIN preceding it.
  • Events have a duration attribute, which generally returns the duration of the media in seconds. CHANGE, however, reports duration in milliseconds.

Deprecated events

The following events in the VideoPlayer Module have been deprecated. Use the new MediaEvents instead.

     videoChange
     videoLoad
     streamStart
     videoComplete
     videoStart
     videoStop
     startBuffering
     endBuffering
     seek
     videoProgress
     volumeChange
     mute

 

Tags
events