1. Home
  2. Developers
  3. Player API
  4. Events, Modes and Phases

Events, Modes and Phases

The player communicates its current state through various events and keeps track of assorted modes and phases. Events can be caught in any Javascript event described below and the modes and phases can be requested via functions in the API. Should you have any questions after reading this guide, please contact our Support Team: support@bluebillywig.com

1.0 | Events

Events indicate every action the player makes, like play, pause or switch to full screen. Events can be used in combination with commands as callback functionality, or with data attributes to obtain certain information (like the time played). These events can be caught with the on() function in the player API.

Media events
Event name Description Related API function
load Media data loading started
loadeddata Media data was loaded
loadedmetadata Media metadata was loaded
canplay The player is now ready to play. play()
play The player has executed a play command.
pause The player is now paused.
playing The player is now playing.
seeking The player is now seeking.
seeked The current playback position has changed by the player as a result of a seek action.
ended Playback has stopped because the end of the media resource was reached.
started (LEGACY) The player has started for the first time. This event only happens once before the ended event.
timeupdate The time has been updated by the player. Note: The time reported by the player changes between timeupdate events. The rate of this event is throttled due to performance reasons. getCurrentTime()
stalled The player is trying to fetch new media data, but is unable to retrieve it and continue playing.
unstalled The player is able to continue playing.
progress The buffer has been updated by the player. getBuffered()
error The player has encountered an error which prevents it from playing the content further.
aderror The advertisment provider encountered an error which prevents the ad from playing in the player.
adnotfound The advertisment provider did not find an ad to play in the player.
Data events
Event name Description Related API function
loadedplayoutdata Playout data is loaded. getPlayoutData()
changedplayoutdata Playout data changed. getPlayoutData()
loadclipdata Clip data is loaded. getClipData()
loadedprojectdata Project data is loaded. getProjectData()
chapterlistchange The list of chapters has changed. getChapterList()
relatedclipschange The list of related clips have been loaded / changed. getRelatedList()
assetlistchange The list of assets has changed. getAssetList()
audiotracklistchange The list of audio tracks has changed. getAudioTracks()
durationchange The duration of the clip has changed. getDuration()
State changes
Event name Description Related API function
modechange The mode has changed. The wrapper class bb-mode-{mode} has also changed. getMode()
statechange The state has changed. The wrapper class bb-state-{state} has also changed. getState()
phasechange The mode has changed. The wrapper class bb-phase-{phase} has also changed. getPhase()
flagchange A flag has changed. getFlag(flagname)
Ad-related events
Event name Description
adstarted An ad has started.
adquartile1 An ad has reached its first quartile.
adquartile2 An ad has reached its second quartile.
adquartile3 An ad has reached its third quartile.
adfinished An ad has finished.
Auto Play Next events
Event name Description
autoplaynexttimerstarted The AutoPlayNext timer has started.
autoplaynexttimercancelled The AutoPlayNext timer was cancelled.
autoplaynexttimertick The AutoPlayNext timer tick.
autoplaynexttimerfinished The AutoPlayNext timer has finished.
autoplaynexttimerpaused The AutoPlayNext timer has paused.
autoplaynexttimerresumed The AutoPlayNext timer has resumed.
General events
Event name Description Related API function
ready The player API is ready and functions can be called from the API.
assetselected A different asset has been selected by the player. getCurrentAsset()
audiotrackchange A different audio track was selected by the player. getCurrentAudiotrack()
volumechange The volume has changed. getVolume()
subtitlechange The subtitle language has changed. getCurrentSubtitle()
subtitlelinechange The current subtitle line has changed. getCurrentSubtitleLine()
resized The player size has been changed.
inview The player is now inside the user agents viewport.
outview The player is now outside the user agents viewport.
fullscreen The player is now fullscreen.
retractfullscreen The player is now not fullscreen.

Example: Play the player when the canplay event is fired.

player.on('canplay.bbskin', onCanPlay);
function onCanPlay(){

2.0 | Modes

The player runs in different modes dependent on the current media type. For example, the player has a different mode for live content than is has for commercial content. The current mode can be retrieved by calling getMode(). The event modechange is thrown when the mode changes.

Mode name Class Description
static bb-mode-static The player has static content loaded, like an image or an SWF object.
commercial bb-mode-commercial The player is playing a VMS creative, VAST source or any other commercial.
audio bb-mode-audio The player is playing audio only content. Note: The player can still display a thumbnail image that is linked to the audio clip.
video bb-mode-video The player is playing a video.
live-audio bb-mode-live-audio The player is playing live-audio and some features might not be available (eg. getDuration()).
live-video bb-mode-live-video The player is playing live-video and some features might not be available (eg. getDuration()).

Example: If the mode is audio, set the volume to 100%.

if(player.getMode() == 'audio'){

3.0 | Phases

In the process of playing content, the player goes through different phases. The current phase can be retrieved by calling getPhase(). The event phasechange is thrown when the phase is changed.

Phase name Class Description
INIT bb-phase-init The player has initialised and is waiting to play.
PRE bb-phase-pre The player is playing a pre-content item, like a pre-roll commercial.
MAIN bb-phase-main The main content is being played.
POST bb-phase-post The player is playing a post-content item, like a post-roll commercial.
EXIT bb-phase-exit The player has finished playing all content and has arrived in the exit phase. The exit screen can be shown here.

Example: If the phase is EXIT, retract from fullscreen.

if(player.getPhase() == 'EXIT'){
        player. retractFullscreen();

4.0 | States

States describe the current condition of the video content.  These states be retrieved by calling the getState() function. The statechange event is thrown when the state changes, along with the related state event described below.

State name (event) Class Description
bb-state-playing The player is playing.
paused bb-state-paused The player is paused.
error bb-state-error The player has encountered an error.
loading bb-state-loading The player is loading and is.

Example: If the player has encountered an error, display an error element.

player.on('statechange', function(){
        if(player.getState() == 'error'){

Or do this directly on the error event:

player.on('error', function(){

5.0 | Other useful classes

Other useful classes
Name Class Description
bb-fullscreen The player is now fullscreen.
play pending bb-playpending The player has received a play call, but has not yet thrown the playing event.
stalled bb-stalled The player has stalled due to buffering.


Updated on August 25, 2020

Was this article helpful?

Related Articles