Namespace: EVENTS

OO. EVENTS

The Ooyala Player events are default events that are published by the event bus.Your modules can subscribe to any and all of these events. Use message bus events to subscribe to or publish player events from video to ad playback. For more information, see Player Message Bus Events.

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.

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 ID (embed code) of the asset, with options.

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.

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.

INITIAL_PLAY

Play has been called for the first time.

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 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.

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_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.

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.

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)

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).