Player v4 JavaScript API Reference

Classes

Classes

Player
MessageBus
PlayerApi
Ads
AdManagerControllerPlatform
AdManagerControllerUi
AdManagerController
Ad
Video
VideoControllerInterface

Namespaces

OO
STATE
Represents the Ooyala Player run-time states.
EVENTS
Represents the Ooyala Player events.
ERROR
Represents the Ooyala V4 Player Errors.
API
Represents the OO.ERROR.API Ooyala V4 Player Errors.
SAS
Represents the OO.ERROR.API.SAS Ooyala V4 Player Errors.
PLAYBACK
Represents the OO.ERROR.PLAYBACK Ooyala V4 Player Errors.

Events

PLAYER_CREATED

A player was created. This is the first event that is sent after player creation. This event provides the opportunity for any other modules to perform their own initialization. The handler is called with the query string parameters. The DOM has been created at this point, and plugins may make changes or additions to the DOM.

  • The element id.
  • The object containing the player page level parameters.
  • The object containing the player persistent settings.
  • The embed code.
  • The timestamp when the player was created.
  • The player url.

SET_EMBED_CODE

An attempt has been made to set the embed code. If you are developing a plugin, reset the internal state since the player is switching to a new asset. Depending on the context, the handler is called with:
  • The ID (embed code) of the asset.
  • { The object containing options for the asset:
    • [optional] isAd: (boolean) true if this asset is an Ooyala Ad.
    }

EMBED_CODE_CHANGED

The player's embed code has changed. The handler is called with two parameters:
  • The ID (embed code) of the asset.
  • The options JSON object.

AUTH_TOKEN_CHANGED

An AUTH_TOKEN_CHANGED event is triggered when an authorization token is issued by the Player Authorization API.
For example, in device registration, an authorization token is issued, as described in Device Registration. The handler is called with a new value for the authorization token.

GUID_SET

The GUID has been set. The handler is called with the GUID.

This event notifies plugin or page developers that a unique ID has been either generated or loaded for the current user's browser. This is useful for analytics.

In HTML5, Flash, and Chromecast environments, a unique user is identified by local storage or a cookie.

To generate the GUID, Flash players use the timestamp indicating when the GUID is generated, and append random data to it. The string is then converted to base64.

To generate the GUID, HTML5 players use the current time, browser information, and random data and hash it and convert it to base64.

Within the same browser on the desktop, once a GUID is set by one platform it is used for both platforms for the user. If a user clears their browser cache, that user's (device's) ID will be regenerated the next time they watch video. Incognito modes will track a user for a single session, but once the browser is closed the GUID is erased.

For more information, see unique user Glossary.

CONTENT_TREE_FETCHED

A content tree was fetched. The handler is called with a JSON object that represents the content data for the current asset.

Analytics:

Records a display event. For more information see Displays, Plays, and Play Starts.

WILL_REQUIRE_EMBED_CODE_METADATA

This event is published when embed code metadata is required.

WILL_FETCH_EMBED_CODE_METADATA

This event is published when embed code metadata will be fetched.

EMBED_CODE_METADATA_FETCHED

The embed code provider metadata, has been retrieved.

METADATA_FETCHED

The metadata, which is typically set in Backlot, has been retrieved. The handler is called with the JSON object containing all metadata associated with the current asset. The metadata includes page-level, asset-level, player-level, and account-level metadata, in addition to metadata specific to 3rd party plugins. This is typically used for ad and anlytics plugins, but can be used wherever you need specific logic based on the asset type.

THUMBNAILS_FETCHED

The thumbnail metadata needed for thumbnail previews while seeking has been fetched and will be passed through to the event handlers subscribing to this event. Thumbnail metadata will have the following structure: { data: { available_time_slices: [10], //times that have thumbnails available available_widths: [100], //widths of thumbnails available thumbnails: { 10: {100: {url: http://test.com, height: 100, width: 100}} } } }

AUTHORIZATION_FETCHED

Playback was authorized. The handler is called with an object containing the entire SAS response, and includes the value of video_bitrate.

For more information see Video Bit Rate.

UPDATE_ASSET

An attempt has been made to update current asset for cms-less player. The handler is called with:
  • The asset Object, with optional fields populated

PLAYBACK_READY

The player has indicated that it is in a playback-ready state. All preparations are complete, and the player is ready to receive playback commands such as play, seek, and so on. The default UI shows the Play button, displaying the non-clickable spinner before this point.

  • The time from player creation to when it is in the playback ready state.

INITIAL_PLAY

Play has been called for the first time.

The handler is called with the following arguments:
  • The unix timestamp of the initial playtime
  • True if the playback request was the result of an autoplay, false or undefined otherwise

PLAYHEAD_TIME_CHANGED

The playhead time changed. The handler is called with the following arguments:
  • The current time.
  • The duration.
  • The name of the buffer.
  • The seek range.
  • The id of the video (as defined by the module that controls it).
Analytics:

The first event is video start. Other instances of the event feed the % completed data points.

For more information, see Displays, Plays, and Play Starts.

BUFFERING

The player is buffering the data stream. The handler is called with the following arguments:
  • The url of the video that is buffering.
  • The playhead position.
  • The id of the video that is buffering (as defined by the module that controls it).


BUFFERED

Play resumes because the player has completed buffering. The handler is called with the URL of the stream. The handler is called with the following arguments:
  • The url of the video that has buffered.
  • The id of the video that has buffered (as defined by the module that controls it).


DOWNLOADING

The player is downloading content (it can play while downloading). The handler is called with the following arguments:
  • The current time.
  • The duration.
  • The name of the buffer.
  • The seek range.
  • The id of the video (as defined by the module that controls it).


BITRATE_INFO_AVAILABLE

Lists the available bitrate information. The handler is called with an array containing the available streams, each object must include the following and only the following:
  • 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)
If The video plugin supports automatic ABR, one stream will have an ID of "auto" and a bitrate of 0.

For more information see Video Bit Rate.

BITRATE_CHANGED

The current playing bitrate has changed. The handler is called with the stream object which includes the following and only the following:
  • 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).
If the player is using automatic ABR, it should publish a stream object with an ID of "auto" and bitrate set to 0.

For more information see Video Bit Rate.

SEND_QUALITY_CHANGE

The current playing bitrate has changed. The handler is called with the stream object

For more information see Video Bit Rate.

CLOSED_CAPTIONS_INFO_AVAILABLE

Lists the available closed caption information including languages and locale. Provide the following arguments:
  • object containing:
    • languages: (array) a list of available languages.
    • locale: (object) contains language names by id. For example, {en:"English", fr:"Français", sp:"Español"}.

SET_CLOSED_CAPTIONS_LANGUAGE

Sets the closed captions language to use. To remove captions, specify "none" as the language. Provide the following arguments:
  • string specifying the language in which the captions appear.

MULTI_AUDIO_FETCHED

Fires when a list of tracks is available and ready to be displayed. Provide the following arguments:
  • list of multiaudio data with 'multiAudio' as a key

MULTI_AUDIO_CHANGED

Fires when the current track has been changed. Provide the following arguments:
  • list of multiaudio data with 'multiAudio' as a key

SET_CURRENT_AUDIO

Fires when need to set new audio as current

MULTIAUDIO_ERROR

This stream type is not supported for multiaudio.

ASSET_DIMENSION

Raised when asset dimensions become available. Provide the following arguments in an object:
  • width: the width of the asset (number)
  • height: the height of the asset (number)
  • videoId: the id of the video (string)

SEEK

A request to perform a seek has occurred. The playhead is requested to move to a specific location, specified in milliseconds. The handler is called with the position to which to seek.

SEEKED

The player has finished seeking the main video to the requested position. The handler is called with the following arguments:
  • The current time of the video after seeking.

LIVE_BUTTON_CLICKED

A request to perform a seek to the live point has occurred. The playhead is requested to move to the live point location. The handler is called as a seek with the position to seek equal to the video duration.

PLAY

A playback request has been made. This event is called anytime the video plays, including at the video's initial play, as well as when a user resumes playback after a pause.

PAUSE

A player pause has been requested.

PAUSED

The player was paused. If a PAUSE event is fired by the Ad Manager, the "pauseForAdPlayback" parameter is included as an argument.

PLAYED

The video and asset were played. The handler is called with the arguments that were passed.

WILL_CHANGE_FULLSCREEN

This event is triggered before a change is made to the full screen setting of the player. The handler is called with true if the full screen setting will be enabled, and is called with false if the full screen setting will be disabled.

FULLSCREEN_CHANGED

The fullscreen state has changed. Depending on the context, the handler is called with:
  • isFullscreen and paused:
    • isFullscreen is set to true or false.
    • isFullscreen and paused are each set to true or false.
  • The id of the video that has entered fullscreen (as defined by the module that controls it).

SIZE_CHANGED

The screen size has changed. This event can also be triggered by a screen orientation change for handheld devices. Depending on the context, the handler is called with:
  • The width of the player.
  • The height of the player.

CHANGE_VOLUME

A request to change volume has been made. The handler is called with the following arguments:
  • The desired volume of the video element.
  • The id of the video on which to change the volume (as defined by the module that controls it). If null or undefined, all video elements volume will be changed

VOLUME_CHANGED

The volume has changed. The handler is called with the current volume, which has a value between 0 and 1, inclusive.

CHANGE_MUTE_STATE

A request to change the mute state has been made. The handler is called with the following arguments:
  • The desired mute state of the video element.
  • The id of the video on which to mute (as defined by the module that controls it). If null or undefined, all video elements volume will be changed
  • Whether or not the request was from a user action. True if it was from a user action, false otherwise.

MUTE_STATE_CHANGED

The mute state has changed. The handler is called with the following arguments:
  • The current mute state of the video element.
  • The id of the video that was muted (as defined by the module that controls it).
  • Whether or not the mute state was changed for muted autoplay. True if it was done for muted autoplay, false or undefined otherwise.

TOGGLE_STEREO

The stereo parameter has been changed. The handler is called with a new parameter, the value of the parameter can be true or false.

TOGGLE_FULLSCREEN_VR

Switch to full screen mode and back to vr360 with ios

MOVE_VR_TO_DIRECTION

The camera (the visible part of video360) can be shifted when you press the keyboard keys or a special control on the screen. This event is called when events "mousestart" or "mouseend" triggered

CLEAR_VIDEO_TYPE

Used to say skins to clear interface for vr

RECREATING_UI

To re-create skins

CHANGE_CLOSED_CAPTION_LANGUAGE

Request change to closed caption language.

ERROR

An error has occurred. The handler is called with a JSON object that always includes an error code field, and may also include other error-specific fields.

API_ERROR

An api related error has occurred. The handler is called with the following arguments:
  • The error code.
  • The error message.
  • The url requested.

BITRATE_INITIAL

Event containing the bitrate used at the start of playback. The handler is called with the following arguments:
  • The bitrate in kbps.

BITRATE_FIVE_SEC

Event containing the bitrate used five seconds into playback. The handler is called with the following arguments:
  • The bitrate in kbps.

BITRATE_STABLE

Event containing the bitrate used thirty seconds into playback. The handler is called with the following arguments:
  • The bitrate in kbps.

PLAYBACK_START_ERROR

A playback error has occurred before the video start. The handler is called with the following arguments:
  • The error code.
  • The error message.
  • The la url if DRM used.

PLAYBACK_MIDSTREAM_ERROR

A playback error has occurred midstream. The handler is called with the following arguments:
  • The error code.
  • The error message.
  • The playhead position.

PLAYBACK_MIDSTREAM_ERROR

A plugin has been loaded successfully. The handler is called with the following arguments:
  • The player core version.
  • The plugin type: ad, video, analytics, playtest, skin.
  • The plugin name.
  • The time it took to load the plugin.

SKIN_CONFIG_LOADED

A skin config has been loaded successfully. The handler is called with the following arguments:
  • The player skin config.

VC_PLUGIN_ERROR

The video plugin has sent an error message. The handler is called with the following arguments:
  • The error code.
  • The error message.

INITIAL_PLAY_STARTING

Notifies the player that the initial playback of content has started.
  • The time since the initial play request was made (number)
  • Boolean parameter. True if video was autoplayed, false otherwise (boolean)
  • Boolean parameter. True if the video had an ad play before it started. This includes midrolls that play before content due to an initial playhead time > 0. False otherwise (number)
    • (boolean)
  • The initial position of the playhead upon playback start. (number)
  • The video plugin used for playback (string)
  • The browser technology used - HTML5, Flash, Mixed, or Other (string)
  • The stream encoding type, i.e. MP4, HLS, Dash, etc. (string)
  • The URL of the content being played (string)
  • The DRM being used, none if there is no DRM (string)
  • Boolean parameter. True if a live stream is playing. False if VOD.(boolean)

REQUEST_PREVIOUS_VIDEO

Notifies the player that the user has requested to play the previous video. Depending on the plugin being used, this could either be the previous video in a playlist, or the previously played Discovery video recommendation.

REQUEST_NEXT_VIDEO

Notifies the player that the user has requested to play the next video. Depending on the plugin being used, this could either be the next video in a playlist, or the next Discovery video recommendation.

DESTROY

The player is currently being destroyed, and anything created by your module must also be deleted. After the destruction is complete, there is nothing left to send an event. Any plugin that creates or has initialized any long-living logic should listen to this event and clean up that logic.

VC_READY

Denotes that the video controller is ready for playback to be triggered.

VC_CREATE_VIDEO_ELEMENT

Commands the video controller to create a video element. Provide the following arguments:
  • videoId (string)
  • streams (object) containing:
    • Encoding type (string) as key defined in OO.VIDEO.ENCODINGS
    • Key-value pair (object) as value containing:
      • url (string): Url of the stream
      • drm (object): Denoted by type of DRM with data as value object containing:
        • Type of DRM (string) as key (ex. "widevine", "fairplay", "playready")
        • DRM specific data (object) as value
  • parentContainer of the element. This is a jquery element. (object)
  • optional params object (object) containing:
    • closedCaptions: (object) The possible closed captions available on this video. Permitted values: null (default), closedCaptions.
    • crossorigin: The crossorigin attribute value to set on the video. Permitted values: null (default), "anonymous".
    • technology: The core video technology required (string) (ex. OO.VIDEO.TECHNOLOGY.HTML5)
    • features: The video plugin features required (string) (ex. OO.VIDEO.FEATURE.CLOSED_CAPTIONS)

VC_UPDATE_ELEMENT_STREAM

A message to be interpreted by the Video Controller to update the URL of the stream for an element. The handler is called with the following arguments:
  • The name of the element who's URL is being altered
  • The new url to be used

VC_VIDEO_ELEMENT_CREATED

The Video Controller has created the desired video element, as denoted by id (string). The handler is called with the following arguments:
  • Object containing:
    • videoId: The id of the video as defined by the module that controls it.
    • encodings: The encoding types supported by the new video element.
    • parent: The parent element of the video element.
    • domId: The DOM id of the video element.
    • videoElement: The video element or its wrapper as created by the video plugin.

VC_FOCUS_VIDEO_ELEMENT

Commands the Video Controller to bring a video element into the visible range given the video element id (string). The handler is called with the following arguments:
  • The id of the video to focus (as defined by the module that controls it).

VC_VIDEO_ELEMENT_IN_FOCUS

The Video Controller has moved a video element (string) into focus. The handler is called with the following arguments:
  • The id of the video that is in focus (as defined by the module that controls it).

VC_VIDEO_ELEMENT_LOST_FOCUS

The Video Controller has removed a video element (string) from focus. The handler is called with the following arguments:
  • The id of the video that lost focus (as defined by the module that controls it).

VC_DISPOSE_VIDEO_ELEMENT

Commands the Video Controller to dispose a video element given the video element id (string).

VC_VIDEO_ELEMENT_DISPOSED

The Video Controller has disposed the denoted video element (string). The handler is called with the following arguments:
  • The id of the video that was disposed (as defined by the module that controls it).

VC_SET_VIDEO_STREAMS

Commands the video controller to set the stream for a video element. It should be given the video element name (string) and an object of streams denoted by encoding type (object).

VC_ERROR

The Video Controller has encountered an error attempting to configure video elements. The handler is called with the following arguments:
  • The id of the video that encountered the error (as defined by the module that controls it).
  • The error details (object) containing an error code.
  • The playhead position (number)

VC_SET_INITIAL_TIME

Sets the video element's initial playback time.

VC_PLAY

Commands the video element to play. The handler is called with the following arguments:
  • The id of the video to play (as defined by the module that controls it).

VC_CAN_PLAY

The video element has been initialized and deferred command to play is unblocked The handler is called with the following arguments:
  • The id of the video that is will be played (as defined by the module that controls it).

VC_WILL_PLAY

The video element has detected a command to play and will begin playback. The handler is called with the following arguments:
  • The id of the video to seek (as defined by the module that controls it).
  • The url of the video that will play.

VC_PLAYING

The video element has detected playback in progress. The handler is called with the following arguments:
  • The id of the video that is playing (as defined by the module that controls it).

VC_PLAYED

The video element has detected playback completion. The handler is called with the following arguments:
  • The id of the video that has played (as defined by the module that controls it).

VC_PLAY_FAILED

The video element has detected playback failure. The handler is called with the following arguments:
  • The id of the video that has played (as defined by the module that controls it).
  • The error code of the failure (string).

VC_PAUSE

Commands the video element to pause. The handler is called with the following arguments:
  • The id of the video to pause (as defined by the module that controls it).
  • Optional string indicating the reason for the pause. Supported values include:
    • "transition" indicates that a pause was triggered because a video is going into or out of focus.
    • null or undefined for all other cases.

VC_PAUSED

The video element has detected video state change to paused. The handler is called with the following arguments:
  • The id of the video that has paused (as defined by the module that controls it).

VC_SEEK

Commands the video element to seek. The handler is called with the following arguments:
  • The id of the video to seek (as defined by the module that controls it).
  • The time position to seek to (in seconds).

VC_SEEKING

The video element has detected seeking. The handler is called with the following arguments:
  • The id of the video that is seeking (as defined by the module that controls it).

VC_SEEKED

The video element has detected seeked. The handler is called with the following arguments:
  • The id of the video that has seeked (as defined by the module that controls it).
  • The current time of the video after seeking.

VC_PRELOAD

Commands the video element to preload.

VC_RELOAD

Commands the video element to reload.

VC_PRIME_VIDEOS

Commands the video controller to prepare all video elements for playback. This event should be called on a click event and used to enable api-control on html5-based video elements.

VC_TAG_FOUND

Notifies the player of tags (such as ID3) encountered during video playback. The handler is called with the following arguments:
  • The id of the video that has paused (as defined by the module that controls it). (string)
  • The type of metadata tag found, such as ID3. (string)
  • The metadata. (string|object)

VC_RELOAD_AND_PLAY

Initiate reload of manifest. When reload will be completed OO.EVENTS.PLAY will be fired.

VC_WILL_RELOAD_AND_PLAY

Triggered right before reloading of manifest

VC_RELOADED

Triggered right after reload of manifest completed.

SSAI_PLAY_SINGLE_AD

This event is triggered if the ad manager controller has been notified that an ssai ad break has started

SSAI_SINGLE_AD_PLAYED

This event is triggered if the ad manager controller has been notified that an ssai ad break has ended

WILL_PLAY_ADS

This event is triggered before an ad is played. Depending on the context, the handler is called with:
  • The duration of the ad.
  • The ID of the ad.
Analytics:

Ad Analytics AD_IMPRESSION event.

ADS_PLAYED

A set of ads have been played. Depending on the context, the handler is called with:
  • The duration of the ad.
  • The ID of the item to play.

ADS_ERROR

This event is triggered when an error has occurred with an ad.

ADS_CLICKED

This event is triggered when an ad has been clicked.

WILL_SHOW_COMPANION_ADS

This event is triggered before the companion ads are shown. Companion ads are displayed on a customer page and are not displayed in the player. This event notifies the page handler to display the specified ad, and is the only means by which companion ads can appear. If the page does not handle this event, companion ads will not appear. Depending on the context, the handler is called with:
  • The ID of all companion ads.
  • The ID of a single companion ad.
Analytics:

Ad Analytics AD_IMPRESSION event.

PAGE_UNLOAD_REQUESTED

The window, document, and associated resources are being unloaded. The handler is called with true if a page unload has been requested, false otherwise. This event may be required since some browsers perform asynchronous page loading while the current page is still active, meaning that the end user loads a page with the Ooyala player, plays an asset, then redirects the page to a new URL they have specified. Some browsers will start loading the new data while still displaying the player, which will result in an error since the networking has already been reset. To prevent such false errors, listen to this event and ignore any errors raised after such actions have occurred.

PLAYLISTS_READY

Denotes that the playlist plugin is ready and has configured the playlist Pod(s).

TOUCH_MOVE

Represents the mousemove event

END_VR_MOVE

Represents the endVrMove event

CHECK_VR_DIRECTION

Represents the mouseUp event

VR_DIRECTION_CHANGED

Represents a change in the direction of movement of the camera

VIDEO_TYPE_CHANGED

Says that a video type in playlist was updated

HA_ENABLED

Triggers if asset movie attributes has ha_enabled set to "true"(string)

HA_FAILOVER_NOW

Triggers manual failover. As result player should reload manifest and start playing

HA_WILL_FAILOVER

This events is triggered right before initiating failover

HA_FAILOVER_COMPLETE

This events is triggered after failover completed successfully. Usually right after OO.EVENTS.VC_WILL_PLAY

HA_FAILOVER_ERROR

This events is triggered if some error happens during attempt of failover. Usually right after OO.EVENTS.VC_WILL_PLAY

CANCEL_GEO_CHECKING

This event is triggered if you want to uncheck the geoblock. It can be called after locks by locating or in the event of a player error or the end of playback

MULTI_AUDIO_AVAILABLE

Lists the available audio. Includes id, kind, label, lang, enabled : id - id of the audio track kind - the type of the audio track (can be: "alternative", "description", "main", "translation", "commentary", or "" (empty string)) label - the label of the audio track lang - the language of the audio track enabled - the track is active (true|false)

MULTI_AUDIO_CHANGED

Fires when the current track has been changed. Provide the following arguments:
  • list of multiaudio data with 'multiAudio' as a key

SET_CURRENT_AUDIO

Fires when need to set new audio as current