Programming Bitrates and Buffering for Player V4 Using JavaScript

Ooyala provides bitrate and buffering functions and events. In addition, Ooyala uses a number of heuristics to make playback as smooth as possible.

Bitrates and buffer control on HDS, HLS, and DASH are supported in the V4 Player when using the bit_wrapper.min.js video plugin . See the example code in Information with Listeners and Method Calls.

Bitrate controls on the player UI and bitrate APIs are supported for all content types (Ooyala VOD, remote VOD, remote live, remote live DV).

The following table shows the JavaScript methods for bitrates and buffering. For detailed API docs, see http://apidocs.ooyala.com/player_v4_js/OO.Player.html.

Note: The following APIs do not apply to the mobile SDKs.
Table 1. JavaScript Methods for Bitrates
get Methods set Methods
  • getBitratesAvailable()
  • getCurrentBitrate()
  • setTargetBitrate(id)

JavaScript Console Log for setTargetBitrate

Calls to the bitrate control API setTargetBitrate supply additional information to the browser's built-in JavaScript console log. You can use this log for end user video configuration.

Determining Available Bitrates

The example below will show determining what bitrates are available and then will show what happens when you attempt to set some incorrect and correct values. This example assumes the player ID is pp. You will often see undefined in the console logs, which is normal for the bitrate API.

pp.getBitratesAvailable()
[Object > bitrate: 470000 height: 180 id: "0" width: 320_proto_: Object,
Object > bitrate: 788000 height: 360 id: "1" width: 640_proto_: Object,
Object > bitrate: 1157000 height: 360 id: "2" width: 640_proto_: Object,
Object > bitrate: 1760000height: 720id: "3"width: 1280_proto_: Object,
Object > bitrate: 2512000height: 720id: "4"width: 1280_proto_: Object,
Object > bitrate: 3986000height: 1080id: "5"width: 1920_proto_: Object,
Object > bitrate: 4657000height: 1080id: "6"width: 1920_proto_: Object,
Object > bitrate: 0height: 0id: "auto"width: 0_proto_: Object]

To set the target bitrate, use one of the id values returned from getBitratesAvailable().

Manually Setting a Bitrate

You can manually set a bitrate after the PLAYING event occurs with setTargetBitrate().

Note: Manually setting the bitrate will override ABR.
  1. Listen to the BITRATE_INFO_AVAILABLE event.
  2. Get the desired bitrate "id" (string).
  3. Listen to the PLAYING event.
  4. Once the PLAYING event is triggered, call setTargetBitrate("id").

For more information on how to use setTargetBitrate, see http://apidocs.ooyala.com/player_v4_js/OO.Player.html.

About ABR

In addition to the bitrate and buffer functions and events, Ooyala uses a number of heuristics to make playback as smooth as possible on every device, such as bandwidth estimation, content size, screen size and so forth. ABR playback (HLS, specifically) is preferred whenever available on the underlying devices.

ABR is a technology that allows the Ooyala Player to adjust/change the bitrate of the stream delivered based on the bandwidth available to the viewer as measured over a period of time. The purpose of ABR is to compensate for drops or increases in bandwidth by lowering or upgrading the stream quality. The ABR changes to the stream quality do not happen immediately. This is not an instantaneous process. To make a bitrate change to the video stream, the player:
  • Detects the change in bandwidth.
  • Waits to confirm it is permanent vs. a momentary fluctuation.
  • Sends a request to the Akamai Flash Media Server to shift to stream at the new bitrate.
  • Waits for Akamai to deliver the new bitrate stream.
  • Starts delivering the new bitrate to the viewer.
Note: ABR and bitrate selection are currently mutually exclusive. You can manually set a bitrate, but this will override ABR.
ABR takes effect only when the player has detected there is sufficient bandwidth available to support a higher bitrate and higher quality stream. To upgrade the player makes multiple checks over a period of time. If all of the checks show the viewer has the required bandwidth to support a higher stream, then it will upgrade. If any of the checks fail to show the required bandwidth, then the process is repeated. The upgrade also depends on the buffer length meeting a minimal threshold, and being stable or increasing. Dropping the bitrate of the stream being delivered is done to favor smooth and uninterrupted playback. Therefore, if the player sees the buffer size dropping, then it will start the process of downgrading the bitrate in order to have a lower bitrate stream available when the current buffer is exhausted.
Note: The current Ooyala player does not support activePanelChanged, ratingsApiReady, and relatedMediaReady events. Although the apiReady, playerCreated, loadComplete, and playerEmbedded events are not provided in the player, you can use the PLAYBACK_READY Event for equivalent functionality.

Was this article helpful?