JavaScript API Summary List (Player V2 Deprecated)

Lists and describes all Player JavaScript APIs grouped by Functions/Methods, Objects, Properties and Events.

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 tables provide a summary list of all the JavaScript APIs listed by properties, functions, events and query string pass through parameters. The individual properties are linked to topics that provide more detail. Together, the topics make up a class reference to the various JavaScript API functions, methods, properties, events, and query string pass through parameters available through the JavaScript interface. A separate topic lists example code along with a link to a live example displaying the capabilities of the JavaScript API. To enable the JavaScript API, you need to supply several parameters in the JavaScript embed snippet:
  • callback—Name of the JavaScript function that receives event notification callbacks. This function should be declared with three parameters:
  • playerId (String)- ID of player invoking the callback
  • eventName (String)—Name of the notification
  • parameters (Object) – Extra notification parameters
For example:


function receiveOoyalaEvent(playerId, eventName, eventParams) {

JavaScript Properties

Properties Description
getActivePanel Returns info, channels, embed or syndication if the respective panel is shown or an empty string if no panel is shown.
getCanRateCurrentItem Returns whether a user is allowed to assign a rating to the current item.
getCurrentItem Get an object describing the current video.

Get the average rating given to the item.

getCurrentItemClosedCaptionsLanguages Get a list of supported closed captions languages for the currently playing item.
getCurrentItemDescription Get the description of the current video.
getCurrentItemEmbedCode/ setCurrentItemEmbedCode Get/set the embedCode for the current video in a channel.
getCurrentItemRatings Get the rating distribution for the current item.
getCurrentItemTitle Get the title of the current video.
getDescription Get the description of the player source.
getEmbedCode/setEmbedCode Get/set the embedCode for the current player.
getErrorCode Get the current error code, if one exists.
getErrorText Get the current text of the error, if one exists.
getFullscreen Returns true if in fullscreen mode, false if not.
getItem Get an Object describing the embedded item.
getLineup Get an array of objects describing the current channel.
getPlayheadTime/setPlayheadTime Find where the playhead is, or move it to a new location in seconds with millisecond accuracy.
getState Get current player state. One of playing, paused, buffering, channel, or error.
getTitle Get the title of the current channel or video if no channel.
getTotalTime Get the length of the active video (in seconds with millisecond accuracy).

Get/set the current volume (a number between 0 and 1 inclusive).

setModuleParams When the player loads modules, set the embed code query string parameters using a callback function. Use this function with hasModuleParamsquery string parameter.
setQueryStringParameters Set the query string parameters for the current player.

Sets the language of the closed captions which will be shown in the player.

JavaScript Functions

Functions Description
changeCurrentItem(embedCode) Set the current video in a channel if the video is present. Returns true if accepted, false if not.
fetchMetadata(embedCode) Begins fetching the custom metadata for the given embedCode. This API is available to Professional and Enterprise accounts.
fetchRelatedMedia(embedCode, options) Begins fetching the related media for the given embedCode.
getTimedText(startTime, endTime) Returns the timed text (captions and their formatting) which appear between the startTime and endTime parameters (specified in seconds).
getPromoFor(embedCode, width, height)

Returns a promo image URL for the given embed code in a channel that will be at least the specified dimensions, or null for an embed code not present in the channel.

incrementCurrentItemRating(rating) Increments the rating for the current item.
loadRatingsApi() Loads the Ratings API.
pauseMovie() Pause the current video.
playMovie() Play the current video.
skipAd() Skip the current ad.

JavaScript Events

Event notifications delivered to callback function. Please note that inter-browser compatibility issues prevent use of standard DHTML events.
Event Parameters of 3rd Argument to Callback Description
activePanelChanged activePanel. The Info, Embed, Share or Channel panel has been exposed or hidden.
adCompleted( ) format, source, type. An ad has finished playing.
adClicked( ) format, source, type. An ad has been clicked on.
apiReady( )   The player is ready to receive API requests like playMovie(), getItem(), etc.
companionAdsReady( ) type, companionAds. One or more companion ads are ready to be displayed. Only applicable to VAST compliant ads.
currentItemEmbedCodeChanged( ) description, embedCode, hostedAtURL, lineup, promo, time (in seconds), title. Current item has changed.
embedCodeChanged( ) description, embedCode, hostedAtURL, lineup, promo. Top-level player item has changed.
fullscreenChanged( ) format, source, type. Full-screen state has been toggled.
loadComplete( )   Player has been initialized.
metadataReady ( ) metadata.

An ad has started playing.

playComplete( )   The video or channel has completed
playheadTimeChanged( ) playheadTime. The playhead has been moved.
playerEmbedded   A player is embedded on a web page. You can use this event to trigger a callback.
ratingsApiReady( )  

The ratings API has loaded and is now ready for use.

relatedMediaReady( ) relatedMedia. The related media requested by the fetchRelatedMedia() call is now ready.
seeked( ) newPlayheadTime, oldPlayheadTime. A seek event happened in the player.
stateChanged( )> relatedMedia. The state has changed.
totalTimeChanged( )> totalTime. Total time of the item has changed.
volumeChanged( )> volume. The volume has changed.

JavaScript Bitrate Selection API

To select a bitrate, you can use either of the following options:
  • select a bitrate based on its quality (auto, low, medium, or high). For example, if you set the bitrate quality to high, the player will decide which is the highest available encoding.
  • select a bitrate based on its kbps number (sum of both audio and video encodings). For example, consider a video with the following available bitrates: [600 kbps, 1000 kbps, 3000 kbps, 4000 kbps]. You can set the bitrate quality to be any of those values.

JavaScript Bitrate Selection Functions

The following table describes all the JavaScript methods (a function invoked through an object) that are associated with bitrates and buffers.

Function Description

Returns an array of strings.

getTargetBitrateQuality() Get the target bitrate quality. One of auto, low, medium or high.
setTargetBitrate(bitrate) Set the target bitrate, in kbps.
getBitratesAvailable() Returns an array with the total number of bitrates, in kbps, or an empty array when the number of encodings is not available.
getTargetBitrate() Get the target bitrate, in kbps, when target bitrate was previously set, or -1 otherwise.
getBufferLength() Returns the current size of the buffer in seconds, when buffer length is supported, or 0 otherwise.
setTargetBitrateQuality(quality) Set the target bitrate quality.

JavaScript Bitrate Selection Events

The following table describes all the JavaScript events that are associated with bitrates.
Function Description

The target bitrate quality has changed.

targetBitrateQualityChanged The target bitrate quality has changed.

JavaScript Examples

The following lists the available query string pass-through parameter examples. Click the link to see the example.