Methods


The Blue Billywig Player API has many functionalities. The list below shows all the methods that can be called on by the player API object.

1.0 | Transport

1.1 | on(eventType, handler)

Attach an event handler method on events thrown by the player, in the same way as jQuery’s .on() does.

on( eventType , handler )

Arguments:

KeyTypeValue
eventTypestringOne or more space-separated event types and optional namespaces.
handlerfunctionA method to execute when the event is triggered.
Note:

As noted in the jQuery documentation, it is possible to add a namespace to eventType, and we encourage you to do so. This will prevent accidental detaching of event handlers by other applications using the same player API.

1.2 | off(eventType)

Detach an event handler method from events thrown by the player. Please refer to the jQuery documentation for more information.

off( eventType )

Arguments:

KeyTypeValue
eventTypestringOne or more space-separated event types and optional namespaces.

1.3 | load(params)

Load a clip

load( params )

Arguments:

KeyTypeValue
typestring‘LoadParams’
clipIdnumberClip ID from the VMS
cliplistIdnumberCliplist ID from the VMS
xmlUrlstringURL to a valid XML URL
seekTonumberOn what time the player should start playing (in seconds)
autoPlaybooleanIf the player should autoplay when loaded
tokenstringPass a (session) token to the loaded clip
useSessionbooleanIf the player should use the browser session to load new clips

1.4 | play(userAction)

Play the loaded video.

play( userAction )

Arguments:

KeyTypeValue
userActionbooleanTrue if called in response to a user action (optional)

Returns

TypeValue
booleanReturns true on success, false on failure.

1.5 | pause()

Pause the video.

pause()

Returns

TypeValue
booleanReturns true on success, false on failure.

1.6 | seek(positionInSeconds)

Seek the video.

seek( positionInSeconds )

Arguments:

KeyTypeValue
positionInSecondsnumberThe time to seek to in seconds.

Returns

TypeValue
booleanReturns true on success, false on failure.

2.0 | Setters

2.1 | setVolume(volume)

Set the master volume (including timeline Picture in picture widgets).

setVolume( volume )

Arguments:

KeyTypeValue
volumenumberA number between 0 and 1.

Returns

TypeValue
booleanReturns true on success, false on failure.

2.2 | setMuted(muted, reserved, userAction)

Set the master mute state (including timeline Picture in picture widgets).

setMuted( muted, reserved, userAction )

Arguments:

KeyTypeValue
mutedbooleantrue to mute the player, false to unmute.
userActionbooleantrue if called in response to a user action (optional)

Returns

TypeValue
booleanReturns true on success, false on failure.

2.3 | setProgramVolume(volume)

Set the volume for the main video.

setProgramVolume( volume )

Arguments:

KeyTypeValue
volumenumberA number between 0 and 1.

Returns

TypeValue
booleanReturns true on success, false on failure.

2.4 | setAsset(assetId)

Switch the asset for the current video.

setAsset( assetId )

Arguments:

KeyTypeValue
assetIdnumberAn asset ID matching one from playerAPI.getAssets().

Returns

TypeValue
booleanReturns true on success, false on failure.

2.5 | setFitMode(fitMode)

Change the way video is fitted inside the player.

setFitMode( fitMode )

Arguments:

KeyTypeValue
fitModestringFIT_SMART,FIT_BOTH,FIT_OVERSCAN,FIT_NATIVE,
FIT_STRETCH,FIT_SMART,FIT_VERTICAL,FIT_HORIZONTAL

Returns

TypeValue
booleanReturns true on success, false on failure.

2.6 | setLocalStorageItem(key, value)

Change an entry in LocalStorage, if permitted by cookie settings

setLocalStorageItem( key, value )

Arguments:

KeyTypeValue
keystring
valuestring

Returns

TypeValue
booleanReturns true on success, false on failure.

2.7 | setSubtitle(subtitleId)

Sets the subtitle.

setSubtitle( subtitleId )

Arguments

KeyTypeValue
subtitleIdnumberThe subtitle ID (found in the Subtitle object retrieved from getSubtitlesList).

3.0 | Getters A – C

3.1 | getAssets()

Returns an array containing (multiple) asset objects which can be used on the current device.

getAssets()

Returns

TypeValue
arrayReturns an array of objects containing asset data, please refer to getCurrentAsset().

3.2 | getBuffered()

Returns the buffered parts of the main clip. Different parts of the video can be buffered as a result of seeking.

getBuffered()

Returns

KeyTypeValue
startarrayContains all start points in seconds.
endarrayContains all end points in seconds.
lengtharraySpecifies the number of buffered parts.

Example

var buffered = playerAPI.getBuffered();
// Loop through all the buffered parts
for (i=0; i < buffered.length; i++) {
        var start = buffered.start[i];
        var end = buffered.end[i];
}

3.3 | getCastSource()

Returns the source url for casting.

3.4 | getChapterList()

Returns an array of chapter objects set for the current clip in the Timeline.

getChapterList()

Returns

KeyTypeValue
idnumberThe ID of the chapter.
titlestringThe title of the chapter as set in the VMS Timeline editor.
descriptionstringThe description of the chapter as set in the VMS Timeline editor.
timeOffsetnumberThe time on which the chapter is set in seconds.

3.5 | getClipData()

Returns all the data for the current clip. Please refer to the actual Player API to view the returned contents, this can be done with the following lines of Javascript and the Firefox / Chrome Developer Console:

console.log(playerAPI.getClipData());
Note:

Please be advised that the returned object is subject to change, and thus we suggest to check all variables inside the object before using them.

if(typeof clipdata.title != 'undefined'){
        setTitle(clipdata.title);
}

3.6 | getContentLayer()

Returns the content layer. This can be useful when you want to resize the content (video + timeline + subtitles) inside the player to show a description or related clips.

getContentLayer()

Returns

TypeValue
element objectThe wrapper DOM element.

3.7 | getCurrentAsset()

Returns an object containing information about the currently used asset.

getCurrentAsset()

Returns

KeyTypeValue
idnumberThe asset ID.
mediatypestringThe mediatype of the asset, eg. MP4_MAIN or MP4_IPOD.
titlestringThe title that can be used as label for a button.
bitratenumberThe desired position of the logo (eg. TOPRIGHT).
classesstringA string containing classes which can be applied on a button for this asset.
widthnumberThe width of the asset.
heightnumberThe height of the asset.

3.8 | getCurrentSubtitle()

Returns an object containing information about the currently used subtitle.

getCurrentSubtitle()

Returns

KeyTypeValue
idnumberThe ID of the subtitle.
languageidnumberThe language ID of the subtitle.
namestringThe name of the subtitle (eg. Dutch or German).
languagenamestringThe translated name of the subtitle (eg. Nederlands or Deutsch).
defaultbooleantrue if this is the default selected subtitle, false otherwise.
isocodestringThe ISO 639-1 code of the language of the subtitle.
statusstringThe status of the subtitle (published or draft).
parsedDataarrayAn array containing all subtitle lines.

3.9 | getCurrentSubtitleLine()

Returns the active subtitle line.

getCurrentSubtitleLine()

Returns

TypeValue
stringThe current (HTML formatted) subtitle line.

3.10 | getCurrentTime()

Returns the current time of the main clip.

getCurrentTime()

Returns

TypeValue
numberThe current time in seconds.

4.0 | Getters D – L

Returns the deeplink of the current clip as specified in the VMS.

getDeeplink()

Returns

TypeValue
urlThe formatted deeplink URL matching the settings specified in the VMS.

4.2 | getDetections()

Please refer to the detections documentation for available commands and variables.

4.3 | getDuration()

Returns the duration of the main clip.

getDuration()

Returns

TypeValue
numberThe duration of the main clip in seconds. Returns null for static clips.

4.4 | getEmbedcode([width], [height])

Returns the embedcode with an optionally specified width and height to override the playout width and height.

getEmbedcode()

Arguments

KeyTypeValue
widthnumberThe width in pixels of the player embedded with the returned embedcode.
heightnumberThe height in pixels of the player embedded with the returned embedcode.

Returns

TypeValue
stringA formatted embedcode that can be used to embed the player.

4.5 | isFullscreen()

Returns the fullscreen state of the player.

isFullscreen()

Returns

TypeValue
booleanReturns true if the player is fullscreen, otherwise returns false.

4.6 | getLocalStorageItem(key)

Returns the value of LocalStorage entry key.

getLocalStorageItem( key )

Arguments

KeyTypeValue
keystringThe storage key.

Returns

TypeValue
mixedThe stored value, if any.

Returns the logo of the active playout.

getLogo()

Returns

KeyTypeValue
positionstringThe desired position of the logo (eg. TOPRIGHT).
urlstringThe URL where the logo should link to.
srcstringThe URL of the logo image.
idstringThe ID of the clip used as logo.

5.0 | Getters M – R

5.1 | getMode()

Returns the current mode of the player. The following modes are possible:

getMode()

Returns

TypeValue
stringOne of the following modes: staticcommercialaudiovideopresentationlive-audiolive-videolive-presentation.

5.2 | getMuted()

Returns the current master muted state.

getMuted()

Returns

TypeValue
booleantrue for muted, false for unmuted.

5.3 | getPhase()

Returns the current phase of the player.

getPhase()

Returns

TypeValue
stringOne of the following phases: INITPREMAINPOSTEXIT.

5.4 | isPlaying()

Returns the playing state of the player.

isPlaying()

Returns

TypeValue
booleanReturns true if the player is not playing, otherwise returns false.

5.5 | getPlayoutData()

Returns all the playout settings from the VMS. The operation of this method is similar to the getClipData() method, but returns a different set of data.

5.6 | getProjectData()

Returns all the project meta data. The operation of this method is similar to the getClipData() method, but returns a different set of data.

5.7 | getRelatedClips()

Returns an array of clip objects related to the active clip.

Note:

This method only returns data when the relatedclipschange has been fired by the player.

6.0 | Getters S – Z

6.1 | getSharing()

Returns an array with objects containing social sharing details.

getSharing()

Returns

KeyTypeValue
idnumberThe ID of the chapter.
namestringA machine readable name for the share item.
titlestringA human readable name for the share item.
urlnumberA formatted URL which directs to a share page of the social network.

6.2 | getSkinLayer()

Get the skin layer. This can be useful to find HTML DOM elements.

getSkinLayer()

Returns

TypeValue
element objectThe skin container DOM element.

6.3 | getSubtitleLayer()

Returns the subtitle layer. This can be useful when custom subtitles are implemented in the skin.

getSubtitleLayer()

Returns

TypeValue
element objectThe subtitle container DOM element.

6.4 | getSubtitlesList()

Returns an array containing (multiple) subtitle objects related to the current clip.

getSubtitlesList()

Returns

TypeValue
arrayReturns an array of objects containing subtitle data, please refer to getCurrentSubtitle().

6.5 | getThumbnail(clipId ,[width] ,[height])

Returns a URL to the thumbnail for the specified clip with specified dimensions.

getThumbnail()

Arguments

KeyTypeValue
clipIdnumberA clip ID.
widthnumberThe desired width of the thumbnail in pixels. Defaults to the original width.
heightnumberThe desired height of the thumbnail in pixels. Defaults to the original height.

Returns

TypeValue
stringReturns the URL of the thumbnail.

6.6 | getVolume()

Returns the current master volume. This method can be used when the volumechange event is fired to get the current player volume.

getVolume()

Returns

TypeValue
numberThe master volume between 0 and 1.

Example

Get the volume after a volume change:

playerAPI.on('volumechange', onVolumeChange);
playerAPI.setVolume(0.5);
 
function onVolumeChange(ev){
        var volume = playerAPI.getVolume();
}

6.7 | getWrapper()

Pause the video

getWrapper()

Returns

TypeValue
element objectThe wrapper DOM element.

7.0 | Interface

7.1 | showInterfaceElement(elementName)

Shows the specified element. Available elements are:

  • controlBar
  • playPauseButton
  • progressBar
  • timeDisplay
  • muteButton
  • volumeSlider
  • languageButton
  • hdButton
  • fullscreenButton
  • shareButton
showInterfaceElement( elementName )

Arguments

KeyTypeValue
elementNamestringA valid element name.

7.2 | hideInterfaceElement(elementName)

Hides the specified element.

hideInterfaceElement( elementName )

Arguments

KeyTypeValue
elementNamestringA valid element name. Please refer to showInterfaceElement

7.3 | enableInterfaceElement(elementName)

Enables the specified element.

enableInterfaceElement( elementName )

Arguments

KeyTypeValue
elementNamestringA valid element name. Please refer to showInterfaceElement

7.4 | disableInterfaceElement(elementName)

Disables the specified element.

disableInterfaceElement( elementName )

Arguments

KeyTypeValue
elementNamestringA valid element name. Please refer to showInterfaceElement

7.5 | showCastTargetPicker(type)

Shows the cast target picker (if available).

showCastTargetPicker( type )

Arguments

KeyTypeValue
typestringThe cast type; either ‘AirPlay’ (default) or ‘ChromeCast’.

8.0 | Miscellaneous

8.1 | fullscreen()

Enter fullscreen mode

8.2 | retractFullscreen()

Exit fullscreen mode.

8.3 | toggleFullscreen()

Enters fullscreen mode when the player is not fullscreen, and exits fullscreen mode when the player is fullscreen.

8.4 | increaseSizerRate()

A 100% width and height player automaticly resizes to the parent element, but needs to manually poll the size of the parent element. To achieve a smoother animation when resizing the parent element, this method can be called before the animation.

Note:

This is not required when the player gets resized due to a window resize.

8.5 | decreaseSizerRate()

Decrease the rate of the sizer described above. Decreasing the rate improves the overall performance of Javascript on the page.

8.6 | destruct()

Destructs the player, freeing up memory and removing its elements from the DOM

Updated on August 19, 2020

Was this article helpful?

Related Articles