Programming Bitrates and Buffering for Flash Player V3 Using JavaScript (Deprecated)

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

Note: Ooyala Player V3 has been deprecated and is scheduled to be disabled. For details and alternatives, see the OVP Release Notes.
Bitrates and buffer control for Flash (RTMP, HDS, Akamai HD2) are supported in the Flash Player V3. See the example code in Information with Listeners and Method Calls.

End users can use a bitrate selector in the Flash player UI to select from bitrate options. To enable the bitrate selector for a Flash player, enable user controls for the player in Backlot.

Bitrate controls on the player UI and bitrate APIs are supported on Flash 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, please see http://apidocs.ooyala.com/player_js/OO.Player.html#getBitrateInfo.

Note: The following APIs do not apply to the HTML5 player or mobile SDKs.
Table 1. JavaScript Methods for Bitrates and Buffering
get Methods set Methods
  • getBitratesAvailable()
  • getBitrateQualitiesAvailable()
  • getTargetBitrate()
  • getTargetBitrateQuality()
  • getBufferLength()
  • getBitrateInfo()
  • setTargetBitrate(bitrate)
  • setTargetBitrateQuality()

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.

See the table below for the possible input values for your_player_ID.setTargetBitrate(X) and their corresponding JavaScript console log outputs. When the entered value in invalid, the actual targetBitrate value is adjusted to match the reported possible value.

your_player_ID.setTargetBitrate(X) JavaScript Console Log Output
X is equal to one of the available stream bitrates "targetBitrate set to: X"
X is not equal to any available stream bitrate but is higher than one of the available stream bitrates, Y (Y is chosen as the closest bitrate below X) "Desired targetBitrate of X is invalid. Setting targetBitrate to nearby value of Y"
0 < X < the lowest available stream, Y (X is between 0 and the lowest stream, Y) "Desired targetBitrate of X is invalid. Setting targetBitrate to nearby value of Y"
X <= 0 "Negative or zero-value targetBitrate attempted, using targetBitrate of -1 to set bitrate to auto."
X is an invalid value, such as a non-numerical value "Invalid targetBitrate attempted, using targetBitrate of -1 to set bitrate to auto."
Manual bitrate setting cannot be done "Manual targetBitrate setting has not been enabled, using targetBitrate of -1 to set bitrate to auto."

Example

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. These examples crop out items in the console log that are not relevant to the example.

Determining Available Bitrates

pp.getBitratesAvailable()
Array [ 198, 364, 728, 1328, 2328, 4528 ]

Setting the Bitrate Where 0<Bitrate<Minimum Available Bitrate

Setting a value above 0 but lower than the minimum available bitrate is a special case that rounds up to the lowest available bitrate, and changes the 'targetBitrate' to that value.

pp.setTargetBitrate(20)
undefined
Desired targetBitrate of 20 is invalid. Setting targetBitrate to nearby value of 198

pp.getTargetBitrate()
198

pp.getTargetBitrateQuality()
"low" 

Setting a Non-Number Bitrate

Any non-number is always treated as an attempt to flip ABR back on. The API uses '-1' as a placeholder for ABR being on, so the 'targetBitrate' is adjusted to '-1'.

pp.setTargetBitrate("hello there")
Invalid targetBitrate attempted, using targetBitrate of -1 to set bitrate to auto.

pp.getTargetBitrate()
-1

pp.getTargetBitrateQuality()
"auto"
   

Setting the Bitrate to 0

Attempts to set bitrates to zero also flip ABR back on, and move the targetBitrate to the placeholder value of '-1'.

pp.setTargetBitrate(0)
Negative or zero-value targetBitrate attempted, using targetBitrate of -1 to set bitrate to auto.

pp.getTargetBitrate()
-1

pp.getTargetBitrateQuality()
"auto"

Setting the Bitrate to a Value <0

Any negative value is always treated as an attempt to flip ABR back on. Again the 'targetBitrate' value is then moved to the '-1' placeholder value.

pp.setTargetBitrate(-501)
Negative or zero-value targetBitrate attempted, using targetBitrate of -1 to set bitrate to auto.

pp.getTargetBitrate()
-1

pp.getTargetBitrateQuality()
"auto"

Setting the Bitrate to -1

Actually using '-1' of course flips on ABR, and keeps the targetBitrate at '-1' as the ABR placeholder. Using '-1' is the proper way to use the manual API to flip the auto 'ABR' system back on.

pp.setTargetBitrate(-1)
Negative or zero-value targetBitrate attempted, using targetBitrate of -1 to set bitrate to auto.

pp.getTargetBitrate()
-1

Setting the Bitrate to a Value One Below a Valid Value

Even though this is only 1 below the next value up, the API always rounds down. So here it rounds down to 364.

pp.setTargetBitrate(727)
Desired targetBitrate of 727 is invalid. Setting targetBitrate to nearby value of 364

pp.getTargetBitrate()
364

pp.getTargetBitrateQuality()
"low"

Setting the Bitrate to an Existing Value

Setting an existing value simply tells you the value is set.

pp.setTargetBitrate(728)
targetBitrate set to: 728

pp.getTargetBitrate()
728

pp.getTargetBitrateQuality()
"medium"

Setting the Bitrate to a Value One Above a Valid Value

Again the API always rounds down, so this attempt of 729 is treated as 728.

pp.setTargetBitrate(729)
Desired targetBitrate of 729 is invalid. Setting targetBitrate to nearby value of 728

pp.getTargetBitrate()
728

Setting the Bitrate to an Existing Value

Setting an existing value simply tells you the value is set.

pp.setTargetBitrate(4528)
targetBitrate set to: 4528

pp.getTargetBitrate()
4528

pp.getTargetBitrateQuality()
"high"

Setting the Bitrate to a Value Above the Maximum Bitrate

Setting any value above the maximum available bitrate rounds down to the maximum, changing the 'targetBitrate' to that maximum value.

pp.setTargetBitrate(9000000000528)
Desired targetBitrate of 9000000000528 is invalid. Setting targetBitrate to nearby value of 4528

pp.getTargetBitrate()
4528

pp.getTargetBitrateQuality()
"high"

Setting the Bitrate Quality

Setting quality picks a targetBitrate. Low will pick the lowest, high the highest, and medium rounds up to a valid value near the middle on an even number of streams, or the middle on an odd number of streams. Available qualities are always low, medium, high, and auto unless the stream has less than 3 available bitrates.

pp.getBitrateQualitiesAvailable()
Array [ "high", "medium", "low", "auto" ]

pp.setTargetBitrateQuality("low")
pp.getTargetBitrate()
198

pp.setTargetBitrateQuality("medium")
pp.getTargetBitrate()
1328

pp.setTargetBitrateQuality("high")
pp.getTargetBitrate()
4528

pp.setTargetBitrateQuality("auto")
pp.getTargetBitrate()
-1

Setting a Misspelled Target Bitrate Quality

Setting targetBitrateQuality will not report an error back to the console if it is misspelled. getBitrateInfo is a generalized summary of your current status with the bitrate API:

pp.setTargetBitrateQuality("auto")

pp.getBitrateInfo()
Object { bitrateQualities: Array[4], bitrates: Array[6], targetBitrateQuality: "auto", targetBitrate: -1 }

pp.setTargetBitrate(728)
pp.getBitrateInfo()
Object { bitrateQualities: Array[4], bitrates: Array[6], targetBitrateQuality: "medium", targetBitrate: 728 }

As the example contained 6 valid bitrates, this returns an array of 6 bitrates, and 4 qualities.

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 stands for Adaptive Bite Rate. This 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.
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.

해당 내용이 도움 되었습니까?