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 nameDescriptionRelated API function
loadMedia data loading started
loadeddataMedia data was loaded
loadedmetadataMedia metadata was loaded
canplayThe player is now ready to play.play()
playThe player has executed a play command.
pauseThe player is now paused.
playingThe player is now playing.
seekingThe player is now seeking.
seekedThe current playback position has changed by the player as a result of a seek action.
endedPlayback has stopped because the end of the media resource was reached.
startedThe player has started for the first time. This event only happens once before the ended event.
timeupdateThe 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()
stalledThe player is trying to fetch new media data, but is unable to retrieve it and continue playing.
unstalledThe player is able to continue playing.
progressThe buffer has been updated by the player.getBuffered()
errorThe player has encountered an error which prevents it from playing the content further.
aderrorThe advertisment provider encountered an error which prevents the ad from playing in the player.
adnotfoundThe advertisment provider did not find an ad to play in the player.
Data events
Event nameDescriptionRelated API function
loadedplayoutdataPlayout data is loaded.getPlayoutData()
changedplayoutdataPlayout data changed.getPlayoutData()
loadedclipdataClip data is loaded.getClipData()
loadedprojectdataProject data is loaded.getProjectData()
chapterlistchangeThe list of chapters has changed.getChapterList()
relatedclipschangeThe list of related clips have been loaded / changed.getRelatedList()
assetlistchangeThe list of assets has changed.getAssetList()
audiotracklistchangeThe list of audio tracks has changed.getAudioTracks()
durationchangeThe duration of the clip has changed.getDuration()
State changes
Event nameDescriptionRelated API function
modechangeThe mode has changed. The wrapper class bb-mode-{mode} has also changed.getMode()
statechangeThe state has changed. The wrapper class bb-state-{state} has also changed.getState()
phasechangeThe mode has changed. The wrapper class bb-phase-{phase} has also changed.getPhase()
flagchangeA flag has changed.getFlag(flagname)
Ad-related events
Event nameDescription
adstartedAn ad has started.
adquartile1An ad has reached its first quartile.
adquartile2An ad has reached its second quartile.
adquartile3An ad has reached its third quartile.
adfinishedAn ad has finished.
Auto Play Next events
Event nameDescription
autoplaynexttimerstartedThe AutoPlayNext timer has started.
autoplaynexttimercancelledThe AutoPlayNext timer was cancelled.
autoplaynexttimertickThe AutoPlayNext timer tick.
autoplaynexttimerfinishedThe AutoPlayNext timer has finished.
autoplaynexttimerpausedThe AutoPlayNext timer has paused.
autoplaynexttimerresumedThe AutoPlayNext timer has resumed.
General events
Event nameDescriptionRelated API function
readyThe player API is ready and functions can be called from the API.
assetselectedA different asset has been selected by the player.getCurrentAsset()
audiotrackchangeA different audio track was selected by the player.getCurrentAudiotrack()
volumechangeThe volume has changed.getVolume()
subtitlechangeThe subtitle language has changed.getCurrentSubtitle()
subtitlelinechangeThe current subtitle line has changed.getCurrentSubtitleLine()
resizedThe player size has been changed.
inviewThe player is now inside the user agents viewport.
outviewThe player is now outside the user agents viewport.
fullscreenThe player is now fullscreen.
retractfullscreenThe player is now not fullscreen.

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

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

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.

Modes
Mode nameClassDescription
staticbb-mode-staticThe player has static content loaded, like an image or an SWF object.
commercialbb-mode-commercialThe player is playing a VMS creative, VAST source or any other commercial.
audiobb-mode-audioThe player is playing audio only content. Note: The player can still display a thumbnail image that is linked to the audio clip.
videobb-mode-videoThe player is playing a video.
live-audiobb-mode-live-audioThe player is playing live-audio and some features might not be available (eg. getDuration()).
live-videobb-mode-live-videoThe 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'){
        player.setVolume(1);
}

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.

Phases
Phase nameClassDescription
INITbb-phase-initThe player has initialised and is waiting to play.
PREbb-phase-preThe player is playing a pre-content item, like a pre-roll commercial.
MAINbb-phase-mainThe main content is being played.
POSTbb-phase-postThe player is playing a post-content item, like a post-roll commercial.
EXITbb-phase-exitThe 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.

States
State name (event)ClassDescription
playing
bb-state-playingThe player is playing.
pausedbb-state-pausedThe player is paused.
errorbb-state-errorThe player has encountered an error.
loadingbb-state-loadingThe 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'){
                myErrorIcon.hide();
        }
});

Or do this directly on the error event:

player.on('error', function(){
        myErrorIcon.hide();
});

5.0 | Other useful classes

Other useful classes
NameClassDescription
fullscreen
bb-fullscreenThe player is now fullscreen.
play pendingbb-playpendingThe player has received a play call, but has not yet thrown the playing event.
stalledbb-stalledThe player has stalled due to buffering.

 

Updated on October 1, 2020

Was this article helpful?

Related Articles