Player JavaScript APIs (Player V2 Deprecated)

Player/Player UI JavaScript APIs can be used to handle aspects of the player such as fullscreen mode, player state, volume, playhead, player volume and more.

Player and Player UI Properties

Important: Ooyala Player V2 is deprecated and is scheduled to be disabled on 2018-01-31. After that date, Player V2 will no longer play your video or audio content. Customers still using Player V2 need to migrate to Player V4 (see Player V4.

The following table describes all the JavaScript properties that are associated with a player.

Function Description

Get current player state.

Format: Read-only

Type: String

Valid Values: One of playing, paused, buffering, channel, or error.


Returns info, channels, embed or syndication if the respective panel is shown or an empty string, if not shown.

Format: read-only

Type: String


Get the description of the player source. Typically this is the description entered for a video or audio asset in Backlot. This API allows you to retrieve the entered description that was set in the Backlot Manage > Details tab or equivalent manual setting. Format: read-only

Type: String

Return Values: alphanumeric description of asset

Example: "Season 22 Opening Game"


Returns true if in fullscreen mode, false if not.

Format: Read-only

Type: Boolean

Valid Values: true | false


Find where the playhead is, or move it to a new location in seconds with millisecond accuracy.

Type: Number

Valid Values: duration in seconds


Get the current volume.

Type: Number

Valid Values: a number between 0 and 1 inclusive


When the player loads modules, pass data to the module(s) using a callback function. Use this function with the hasModuleParams query string parameter. What the hasModuleParams=1 parameter does is signal to the player that it should wait for custom data to be sent via the setModuleParams function.

Type: Object

Valid Values: a key value pair

Usage: The setModuleParams function is used with the hasModuleParams as a more efficient method of passing parameters to the player.js than by using thruParams. We recommend using setModuleParams with hasModuleParams over the use of thruParams. The setModuleParams takes an object of key-value pairs.

Example: If you want to add parameters to your script embed, you would use the hasModuleParams and a callback in the embed string, as shown in the following example:

<script src=" ... hasModuleParams=1&callback=playerAPICallback"></script>

In the following example, you set hasModuleParams to 1, while the callback can be any function. You also need to add the callback function in JavaScript elsewhere on your page. In the callback, you wait for the playerEmbedded event and call setModuleParams. The following example provides a callback function for a hasModuleParams:

// callback function
function playerAPICallback(playerId, eventName, parameters) {
  // the callback gets called when events are fired (here, wait for the playerEmbedded event)
  if (eventName == "playerEmbedded") {
      // include any module parameters as an object of key-value pairs, example below
      "doubleclick" : {
        "tagUrl" : ";dcadv=1379578;sz=0x0;ord=79879;dcmt=text/xml"
setQueryStringParameters Set the query string parameters for the current player. See the topic "Query String and Pass-Through Parameters"in this document.
setVolume Set the current volume. Type: Number Valid Values: a number between 0 and 1 inclusive

Player/Player UI Event Handling

The following table describes all the JavaScript events that are associated with a player.

Event Parameters of the third argument to callback Description


Type: Object

The Info, Embed, Share or Channel panel has been exposed or hidden.
playheadTimeChanged( )


Type: Hash

The playhead has been moved.
apiReady( ) Type: Object The player is ready to receive API requests like playMovie(), getItem(), etc. Wait for this event to be dispatched before making any API requests. This event is fired each time the player's embedCode is changed. The embed code can be changed using setEmbedCode() or setQueryStringParameters().

Note: Version 2 and onward.

fullscreenChanged( )


Type: String

Parameters: (format, source, type)

Example: (video, doubleClick, adStarted)

Full-screen state has been toggled.
loadComplete( ) Type: Object Player has been initialized. This is deprecated; use the apiReady event instead.
metadataReady( )


Type: String

Valid Values: Each name/value pair has two properties: name and value

Example: { name: "actor", value: "Johnny Depp"}

The metadata requested by the fetchMetadata() call is now ready. The metadata property is an array of name/value pairs.

playComplete( ) Type: Void

The video or channel has completed.

playerEmbedded Type: Object A player.js embedded on a web page fires this event and triggers a callback. For example,
  // the callback gets called when events are fired (here, wait for the playerEmbedded event)
  if (eventName == "playerEmbedded") {
This event is used with the hasModuleParams query string parameter, the setModuleParams function and the callback query string parameter.
ratingsApiReady( )   The ratings API has loaded and is now ready for use. This event is dispatched after loadRatingsApi() is called.
relatedMediaReady( ) relatedMedia. The relatedMedia property is an array of media items.

Each item has a title, description, time, promo, and embedCode.

The related media requested by the fetchRelatedMedia() call is now ready.

seeked( )

newPlayheadTime, oldPlayheadTime

Type: Hash

A seek event happened in the player. This event can be triggered in two ways:
  • a user moves the scrubber bar
  • The API request setPlayheadTime is made

Note: The event is registered when the user releases the scrubber bar.

stateChanged( )

state, errorCode, errorText

Type: Object

Valid Values: playing | paused | buffering | error

The state has changed between playing, paused, buffering, or error.
totalTimeChanged( )


Type: Hash

Total time of the item has changed.
volumeChanged( )


Type: Hash

The volume has changed.

Related Information

The following list provides links to Backlot documentation that provides some general information about players.