Methods

Contents

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:

Key	Type	Value
eventType	`string`	One or more space-separated event types and optional namespaces.
handler	`function`	A 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:

Key	Type	Value
eventType	`string`	One or more space-separated event types and optional namespaces.

1.3 | load(params)

Load a clip

load( params )

Arguments:

Key	Type	Value
type	`string`	‘LoadParams’
clipId	`number`	Clip ID from the VMS
cliplistId	`number`	Cliplist ID from the VMS
xmlUrl	`string`	URL to a valid XML URL
seekTo	`number`	On what time the player should start playing (in seconds)
autoPlay	`boolean`	If the player should autoplay when loaded
token	`string`	Pass a (session) token to the loaded clip
useSession	`boolean`	If the player should use the browser session to load new clips

1.4 | play(userAction)

Play the loaded video.

play( userAction )

Arguments:

Key	Type	Value
userAction	`boolean`	True if called in response to a user action (optional)

Returns

Type	Value
`boolean`	Returns `true` on success, `false` on failure.

1.5 | pause()

Pause the video.

pause()

Returns

Type	Value
`boolean`	Returns `true` on success, `false` on failure.

1.6 | seek(positionInSeconds)

Seek the video.

seek( positionInSeconds )

Arguments:

Key	Type	Value
positionInSeconds	`number`	The time to seek to in seconds.

Returns

Type	Value
`boolean`	Returns `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:

Key	Type	Value
volume	`number`	A number between 0 and 1.

Returns

Type	Value
`boolean`	Returns `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:

Key	Type	Value
muted	`boolean`	`true` to mute the player, `false` to unmute.
userAction	`boolean`	`true` if called in response to a user action (optional)

Returns

Type	Value
`boolean`	Returns `true` on success, `false` on failure.

2.3 | setProgramVolume(volume)

Set the volume for the main video.

setProgramVolume( volume )

Arguments:

Key	Type	Value
volume	`number`	A number between 0 and 1.

Returns

Type	Value
`boolean`	Returns `true` on success, `false` on failure.

2.4 | setAsset(assetId)

Switch the asset for the current video.

setAsset( assetId )

Arguments:

Key	Type	Value
assetId	`number`	An asset ID matching one from `playerAPI.getAssets()`.

Returns

Type	Value
`boolean`	Returns `true` on success, `false` on failure.

2.5 | setFitMode(fitMode)

Fitmode settings determine how content video fits in the player when the aspect ratio of the video content differs from the player’s aspect ratio. Read more about Fitmode settings.

setFitMode( fitMode )

Arguments:

Key	Type	Value
fitMode	`string`	`FIT_SMART`,`FIT_BOTH`,`FIT_OVERSCAN`,`FIT_NATIVE`, `FIT_STRETCH`,`FIT_SMART`,`FIT_VERTICAL`,`FIT_HORIZONTAL`

Returns

Type	Value
`boolean`	Returns `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:

Key	Type	Value
key	string	Local storage key
value	string	Local storage value

Returns

Type	Value
boolean	Returns true on success, false on failure.

2.7 | setSubtitle(subtitleId)

Sets the subtitle.

setSubtitle( subtitleId )

Arguments

Key	Type	Value
subtitleId	`number`	The subtitle ID (found in the Subtitle object retrieved from `getSubtitlesList`).

2.8 | setInView(inView)

Sets in-view state.

setInView( inView )

Arguments

Key	Type	Value
inView	`boolean?`	The forced in-view state, or NULL to unforce.

2.9 | setRelatedItems(items)

Sets related items.

setRelatedItems( items )

Arguments

Key	Type	Value
items	`array?`	An array of content items, or NULL to unset.

Item Object Properties

Key	Value
id	(string) Unique identifier of the mediaclip (required)
title	(string) Mediaclip title (optional)
type	(string) Item type: “MediaClip”, “Project”, “MediaClipList” (optional)
mediatype	(string) Media type: “audio”, “video”, “interactive”, “mainroll”, “image” (optional)
length	(integer) The length in seconds (optional)
sourcetype	(string) Source type: “on_demand”, “live” (optional)
deeplink	(string) Deeplink url of item (optional)
gendeeplink	(string) Dynamically generated deeplink url of item (optional)

Example:


playerAPI.setRelatedItems([{ id: "1234567"}, {id: "9876543"}, {id: "3456789"}])

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

Type	Value
`array`	Returns 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

Key	Type	Value
start	`array`	Contains all start points in seconds.
end	`array`	Contains all end points in seconds.
length	`array`	Specifies 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

Key	Type	Value
id	`number`	The ID of the chapter.
title	`string`	The title of the chapter as set in the VMS Timeline editor.
description	`string`	The description of the chapter as set in the VMS Timeline editor.
timeOffset	`number`	The 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. We therefore recommend 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

Type	Value
`element object`	The wrapper DOM element.

3.7 | getCurrentAsset()

Returns an object containing information about the currently used asset.

getCurrentAsset()

Returns

Key	Type	Value
id	`number`	The asset ID.
mediatype	`string`	The mediatype of the asset, eg. `MP4_MAIN` or `MP4_IPOD`.
title	`string`	The title that can be used as label for a button.
bitrate	`number`	The desired position of the logo (eg. `TOPRIGHT`).
classes	`string`	A string containing classes which can be applied on a button for this asset.
width	`number`	The width of the asset.
height	`number`	The height of the asset.

3.8 | getCurrentSubtitle()

Returns an object containing information about the currently used subtitle.

getCurrentSubtitle()

Returns

Key	Type	Value
id	`number`	The ID of the subtitle.
languageid	`number`	The language ID of the subtitle.
name	`string`	The name of the subtitle (eg. `Dutch` or `German`).
languagename	`string`	The translated name of the subtitle (eg. `Nederlands` or `Deutsch`).
default	`boolean`	`true` if this is the default selected subtitle, `false` otherwise.
isocode	`string`	The ISO 639-1 code of the language of the subtitle.
status	`string`	The status of the subtitle (`published` or `draft`).
parsedData	`array`	An array containing all subtitle lines.

3.9 | getCurrentSubtitleLine()

Returns the active subtitle line.

getCurrentSubtitleLine()

Returns

Type	Value
`string`	The current (HTML formatted) subtitle line.

3.10 | getCurrentTime()

Returns the current time of the main clip.

getCurrentTime()

Returns

Type	Value
`number`	The current time in seconds.

4.0 | Getters D – L

4.1 | getDeeplink()

Returns the deep link of the current clip as specified in the VMS.

getDeeplink()

Returns

Type	Value
url	The formatted deep link 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

Type	Value
`number`	The 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

Key	Type	Value
width	`number`	The width in pixels of the player embedded with the returned embedcode.
height	`number`	The height in pixels of the player embedded with the returned embedcode.

Returns

Type	Value
string	A formatted embedcode that can be used to embed the player.

4.5 | isFullscreen()

Returns the fullscreen state of the player.

isFullscreen()

Returns

Type	Value
`boolean`	Returns `true` if the player is fullscreen, otherwise returns `false`.

4.6 | getLocalStorageItem(key)

Returns the value of LocalStorage entry key.

getLocalStorageItem( key )

Arguments

Key	Type	Value
key	`string`	The storage key.

Returns

Type	Value
mixed	The stored value, if any.

4.7 | getLogo()

Returns the logo of the active playout.

getLogo()

Returns

Key	Type	Value
position	`string`	The desired position of the logo (eg. `TOPRIGHT`).
url	`string`	The URL where the logo should link to.
src	`string`	The URL of the logo image.
id	`string`	The 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

Type	Value
`string`	One of the following modes: `static`, `commercial`, `audio`, `video`, `presentation`, `live-audio`, `live-video`, `live-presentation`.

5.2 | getMuted()

Returns the current master muted state.

getMuted()

Returns

Type	Value
`boolean`	`true` for muted, `false` for unmuted.

5.3 | getPhase()

Returns the current phase of the player.

getPhase()

Returns

Type	Value
`string`	One of the following phases: `INIT`, `PRE`, `MAIN`, `POST`, `EXIT`.

5.4 | isPlaying()

Returns the playing state of the player.

isPlaying()

Returns

Type	Value
`boolean`	Returns `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

Key	Type	Value
id	`number`	The ID of the chapter.
name	`string`	A machine readable name for the share item.
title	`string`	A human readable name for the share item.
url	`number`	A 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

Type	Value
`element object`	The 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

Type	Value
`element object`	The subtitle container DOM element.

6.4 | getSubtitlesList()

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

getSubtitlesList()

Returns

Type	Value
`array`	Returns 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

Key	Type	Value
clipId	`number`	A clip ID.
width	`number`	The desired width of the thumbnail in pixels. Defaults to the original width.
height	`number`	The desired height of the thumbnail in pixels. Defaults to the original height.

Returns

Type	Value
`string`	Returns 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

Type	Value
`number`	The 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

Type	Value
`element object`	The 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

Key	Type	Value
elementName	`string`	A valid element name.

7.2 | hideInterfaceElement(elementName)

Hides the specified element.

hideInterfaceElement( elementName )

Arguments

Key	Type	Value
elementName	`string`	A valid element name. Please refer to `showInterfaceElement`

7.3 | enableInterfaceElement(elementName)

Enables the specified element.

enableInterfaceElement( elementName )

Arguments

Key	Type	Value
elementName	`string`	A valid element name. Please refer to `showInterfaceElement`

7.4 | disableInterfaceElement(elementName)

Disables the specified element.

disableInterfaceElement( elementName )

Arguments

Key	Type	Value
elementName	`string`	A valid element name. Please refer to `showInterfaceElement`

7.5 | showCastTargetPicker(type)

Shows the cast target picker (if available).

showCastTargetPicker( type )

Arguments

Key	Type	Value
type	`string`	The 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 | playAdTag(params)

Instructs the player to request and play an ad tag.

When params.phase is set to either "PRE" or "POST" the player will request the tag the next time it enters the specified phase.

When multiple playAdTag calls are made for the PRE or POST phase the player will go through each tag in order until one fills. After filling or exhausting the tags the player will remove all tags from the specified phase.

When params.phase is set to "MAIN" the player will either:

request the tag immediately and possibly interrupt the content if it is currently in the MAIN phase and no time parameter was provided
schedule to request the tag and possibly interrupt the content when the current time offset is at or exceeds the provided time parameter
schedule to request the tag and possibly interrupt the content the moment the player starts playing if it is not currently in the MAINphase

Note:

This function does not work if the player makes use of the Ad Schedules feature, or if the player has ad units configured for the same phase as the request.

playAdTag( params )

Arguments

Key	Type	Value
params	`object`	Parameters for the request. One of `vastUrl` or `vastXml` is required.
params.phase	`string`	The phase in which the player should request the ad tag. One of `"PRE"`, `"MAIN"` or `"POST"` Defaults to `"MAIN"`.
params.time	`number`	The time offset in seconds in the `MAIN` phase where the ad should be requested.
params.vastUrl	`string`	The VAST URL of the tag to request. One of `vastUrl` or `vastXml` is required. If both are provided `vastUrl` is preferred.
params.vastXml	`string`	The VAST XML of the tag to request. One of `vastUrl` or `vastXml` is required. If both are provided `vastUrl` is preferred.

Returns trueif the request was successfully scheduled, and falseotherwise.

8.5 | destruct()

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

Was this article helpful?

Yes No

Contact Support

Can't find the answer you're looking for?

Contact Support

1.0 | Transport

1.1 | on(eventType, handler)

1.2 | off(eventType)

1.3 | load(params)

1.4 | play(userAction)

1.5 | pause()

1.6 | seek(positionInSeconds)

2.0 | Setters

2.1 | setVolume(volume)

2.2 | setMuted(muted, reserved, userAction)

2.3 | setProgramVolume(volume)

2.4 | setAsset(assetId)

2.5 | setFitMode(fitMode)

2.6 | setLocalStorageItem(key, value)

2.7 | setSubtitle(subtitleId)

2.8 | setInView(inView)

2.9 | setRelatedItems(items)

3.0 | Getters A – C

3.1 | getAssets()

3.2 | getBuffered()

3.3 | getCastSource()

3.4 | getChapterList()

3.5 | getClipData()

3.6 | getContentLayer()

3.7 | getCurrentAsset()

3.8 | getCurrentSubtitle()

3.9 | getCurrentSubtitleLine()

3.10 | getCurrentTime()

4.0 | Getters D – L

4.1 | getDeeplink()

4.2 | getDetections()

4.3 | getDuration()

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

4.5 | isFullscreen()

4.6 | getLocalStorageItem(key)

4.7 | getLogo()

5.0 | Getters M – R

5.1 | getMode()

5.2 | getMuted()

5.3 | getPhase()

5.4 | isPlaying()

5.5 | getPlayoutData()

5.6 | getProjectData()

5.7 | getRelatedClips()

6.0 | Getters S – Z

6.1 | getSharing()

6.2 | getSkinLayer()

6.3 | getSubtitleLayer()

6.4 | getSubtitlesList()

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

6.6 | getVolume()

6.7 | getWrapper()

7.0 | Interface

7.1 | showInterfaceElement(elementName)

7.2 | hideInterfaceElement(elementName)

7.3 | enableInterfaceElement(elementName)

7.4 | disableInterfaceElement(elementName)

7.5 | showCastTargetPicker(type)

8.0 | Miscellaneous

8.1 | fullscreen()

8.2 | retractFullscreen()

8.3 | toggleFullscreen()

8.4 | playAdTag(params)

8.5 | destruct()

Was this article helpful?

Related Articles