Player v4 JavaScript API Reference

Class: Player

OO. Player

Creates and destroys an instance of the Ooyala V4 Player.

Player(_elementId, _asset, _parameters)

Initialize an instance of the current class using the new keyword along with this constructor.
Parameters:
Name Type Description
_elementId string The DOM id of the element that wraps the player
_asset string | object The asset's Ooyala id or metadata
_parameters object The session parameters

Methods

<static> create(elementId, asset, parameters) → {Object}

Creates a player object and attaches it to the specified element. This is an asynchronous method and will return before the player is completely initialized. Listen for the PLAYBACK_READY event to determine whether the player is completely initialized.
Parameters:
Name Type Description
elementId Number The ID of the element to which to attach the player object.
asset Number The asset. The player will load the asset. Only a single video is supported.
parameters Object The player parameters. These can be used to customize player ads and behavior, and can determine player styles. For more information, see Embedded Parameters.
Returns:
The created player object.
Type
Object

isolate(targetPlayer)

Isolates the specified player for debugging. debug.ooyala.com automatically generates a valid V3 embedded player. When you call this on a player it automatically generates the corresponding debug.ooyala.com test page.
Parameters:
Name Type Description
targetPlayer String The name of the div container in which to load the player.
Returns:
url The link to the isolated player.

setEmbedCode(embedCode, options)

Sets the embed code for the current player. You may optionally specify an options object that enables you to dynamically assign an ad set or other asset-level options to the embed code. For example, you can set the initial position from which the player will start. This is an asynchronous method and may return before having completed the operation. If your logic depends on the completion of this operation, listen to the corresponding event.
Parameters:
Name Type Description
embedCode String An embed code belonging to the same provider as the ad set code.
options Object (Optional) An object containing a hash of key-value pairs representing the unique ad set code.

mute()

Sets the mute state of all player elements to muted programmatically.

unmute(fromUser)

Sets the mute state of all player elements to unmute programmatically.
Parameters:
Name Type Description
fromUser Boolean True if the unmute was from a user click, false otherwise

play()

Plays the current video and the entire asset including ads, or queues it for playback if the video is not ready. This is an asynchronous method and may return before having completed the operation. If your logic depends on the completion of this operation, listen to the corresponding event.

pause()

Pauses the current video playback. This is an asynchronous method and may return before having completed the operation. If your logic depends on the completion of this operation, listen to the corresponding event.

setPlaybackSpeed(speed) → {Boolean}

Set the speed of playback for the main video element. Must be >= 0.5 and <= 2.0. This will not override the speed of playback for ads. This will work with DVR but will return to 1.0x as soon as you get back up to the current time.
Parameters:
Name Type Description
speed Number The desired playbackrate. Must be more than 0.5 and less than 2.
Returns:
True if the speed is a valid number
Type
Boolean

seek(seconds)

Seeks to the specified number of seconds from the beginning. This is an asynchronous method and may return before having completed the operation. If your logic depends on the completion of this operation, listen to the BUFFERED event.
Parameters:
Name Type Description
seconds Number The number of seconds from the beginning at which to begin playing the video.

setVolume(volume)

Sets the current volume on a best-effort basis according to the underlying device limitations. This is an asynchronous method and may return before having completed the operation. If your logic depends on the completion of this operation, listen to the corresponding event.
Parameters:
Name Type Description
volume Number The volume. Specify a value between 0 and 1, inclusive.

destroy(callback)

Destroys the item. When this method is called, the player is removed, all activity is stopped, and any video is unloaded. This is an asynchronous method and may return before having completed the operation. If your logic depends on the completion of this operation, listen to the corresponding event.
Parameters:
Name Type Description
callback function (Optional) A function callback used to notify a web page that the destroy method has completed destroying the HTML5 player.

updateAsset(Object)

Set related media for unbundled player.
Parameters:
Name Type Description
Object Object with asset structure where id field should not be empty. Other fields will be updated if populated.

getPlayheadTime() → {Number}

Retrieves the playhead position in seconds.
Returns:
The playhead position, in seconds.
Type
Number

getDuration() → {Number}

Retrieves the total duration, in seconds, of the video. This method should not be called before the player fires the PLAYBACK_READY event. The duration is not guaranteed to be known before that point.
Returns:
The total duration of the video in seconds. The method returns a value of Infinity for all live assets, including assets that feature DVR functionality.
Type
Number

getAdDuration() → {Number}

Retrieves the total duration, in milliseconds, of the videos.
Returns:
The total duration of the ad videos in milliseconds.
Type
Number

getBufferLength() → {Number}

Retrieves the current size of the buffer in seconds.
Returns:
The current size of the buffer in seconds when buffer length is supported; returns 0 otherwise.
Type
Number

getItem() → {Object}

Retrieves an object describing the current video.
Returns:
The current video, described in an object containing the following attributes:
  • embedCode
  • title
  • description
  • time (play length in seconds)
  • lineup
  • promo
  • hostedAtURL
Type
Object

getDescription() → {String}

Retrieves the description of the current video. This function retrieves the description that was set in the the Backlot Manage Details tab or the equivalent manual setting.
Returns:
The description of the current video. For example, Season 22 Opening Game.
Type
String

getEmbedCode() → {String}

Retrieves the embed code for the current player.
Returns:
The embed code for the current player.
Type
String

getTitle() → {String}

Retrieves the title of the current video.
Returns:
The title of the current video. For example, My Snowboarding Channel.
Type
String

isFullscreen() → {Boolean}

Determines whether the player is in full screen mode.
Returns:
true if the player is in full screen mode, false otherwise.
Type
Boolean

getErrorCode() → {String}

Retrieves the current error code if it exists.
Returns:
The error code, if it exists.
Type
String

getState() → {String}

Retrieves the current player state. See OO.STATE for descriptions of the states.
Returns:
One of the following values:
  • LOADING
  • READY
  • PLAYING
  • PAUSED
  • BUFFERING
  • ERROR
  • DESTROYED
Type
String

getVolume() → {Number}

Retrieves the current volume on a best-effort basis according to underlying device limitations.
Returns:
The volume, whose value is between 0 and 1, inclusive.
Type
Number

getBitratesAvailable() → {Array}

Retrieves an array of available bitrate information object.
See:
  • getCurrentBitrate
  • setTargetBitrate
Returns:
An array of available bitrate information object. The handler is called with an array containing the available bitrates, each object includes:
  • bitrate: The bitrate in bits per second. (number)
  • height: The vertical resolution of the stream. (number)
  • width: The horizontal resolution of the stream. (number)
  • id: A unique identifier for the stream. (string)
The bitrates will be sorted in descending order by resolution and then by bitrate. If the video plugin supports automatic ABR, one stream will have an ID of "auto" and a bitrate of 0.
Type
Array

getCurrentBitrate() → {Object}

Retrieves the current bitrate information object.
See:
  • getBitratesAvailable
Returns:
The current bitrate information object. Each object includes:
  • bitrate: The bitrate in bits per second. (number|string)
  • height: The vertical resolution of the stream. (number)
  • width: The horizontal resolution of the stream. (number)
  • id: A unique identifier for the stream. (string)
Type
Object

setTargetBitrate(id)

Sets the target bitrate. You must specify the ID of an available bitrate information object. To determine which bitrates are available, call getBitratesAvailable().

NOTE: This setting does not carry over to new asset. This is an asynchronous method and may return before having completed the operation. If your logic depends on the completion of this operation, listen to the corresponding event.

Parameters:
Name Type Description
id String ID of the stream to switch to. ID should correspond to an ID property from one of the available bitrates.
See:
  • getBitratesAvailable

getCurrentItemClosedCaptionsLanguages() → {Array}

Retrieves a list of supported closed captions languages for the currently playing item. This list is derived from the closed captions XML (DFXP [now TTML]) file for this content, uploaded via Backlot. For more information about this file see Uploading and Viewing a Closed Captions File. If there is no DFXP (now TTML) file in place, this method returns an empty list. In live streaming mode, the closed caption languages are derived from the stream itself.
Returns:
A list of supported closed captions languages for the currently playing item.
Type
Array

setClosedCaptionsLanguage(language)

Sets the language of the closed captions (CC) that will be shown in the player. If you do not upload the Closed Captions file, the content will play back without closed captions. In Live streaming mode, the closed caption languages are derived from the stream itself. Note that because of the way that closed captions are supported in iOS, we are not able to add closed caption data for IOS web for remote assets.

NOTE: Because of the way that closed captions are supported in iOS, closed caption data cannot be added for IOS web for remote assets.


Parameters:
Name Type Description
language String Specify the ISO 639-1 language code. For example, specify "en", "de", or "ja" for English, German, or Japanese. Use "zh-hans" for Simplified Chinese and "zh-hant" for Traditional Chinese. To show no closed captions, set the language to "none".

subscribe(eventName, subscriber, callback)

Subscribe to a specified event.
Parameters:
Name Type Description
eventName String The name of the event.
subscriber String The name of the subscriber to which the message bus will publish the event.
callback function The function that will execute when the subscriber receives the event notification.

getVersion() → {String}

Retrieves the core player version.
Returns:
The core player version.
Type
String

getElementId() → {String}

Retrieves the ID of the DOM element the player was created inside.
Returns:
The ID of the DOM element the player was created inside.
Type
String

isPlaying() → {Boolean}

Determine if main content is currently playing
Returns:
Whether or not the player is currently playing.
Type
Boolean

isAdPlaying() → {Boolean}

Determine if an ad is currently playing
Returns:
Whether or not the player is currently playing.
Type
Boolean