Selecting Dynamic Delivery Renditions

Multi-bitrate streaming is a feature that enables you to deliver videos with the resolution and bit rate that best matches the viewer's connection speed. The videos in your Media Library can include one or more renditions encoded at different bit rates and sizes. This topic describes how to use the Player API to select which of the available renditions of a video to play in the player. For an introduction to multi-bitrate streaming, see Using multi-bitrate streaming.

The VideoPlayer Module in the Player API includes a method named setRenditionSelectionCallback that you can use to specify which of the available multi-bitrate streaming renditions to play in the player. The signature of the setRenditionSelectionCallback method is:

setRenditionSelectionCallback(callback:Function):void

The function that you pass in setRenditionSelectionCallback will be called any time the player decides a new rendition could be selected, which occurs when a new video is selected and starts to play (not on load of the player or when cueVideo() is called) and, for streaming, when the screen size changes or there are multiple buffering events.

The function is passed a context object that contains the following properties:

The context object contains the information your callback function needs in order to select a rendition; the logic of which rendition to select is completely up to viewer. The examples work through three common scenarios. You just need to be sure that your function returns the index of the rendition to play.

Rendition selection examples

You can download a zip file that includes a set of examples showing how to select a multi-bitrate streaming rendition:

• SelectHighestRendition – select the highest bit rate rendition
• SelectLowestRendition – select the lowest bit rate rendition
• SelectOptimalRendition – select the rendition that best matches the viewer's download bandwidth and video screen size.

The zip file includes both ActionScript and JavaScript examples. To use these examples with a player:

If you are using JavaScript, include the JavaScript file in your player publishing code, along with APIModules_all.js. Make sure that your player is API-enabled. For example, include lines like these in your JavaScript player publishing code:

<script src="http://admin.brightcove.com/js/APIModules_all.js"> </script>
<script src="http://www.example.com/js/SelectOptimalRendition.js"> </script>

There are alerts in the file to tell you which rendition is being selected.

If you are using ActionScript, put your compiled SWF on your server and include a reference to the SWF in your BEML player template, using a Modules element, such as:

<Modules>
  <Module file="http://example.com/selectHighestRendition.swf" />
</Modules>

There are traces in the SWF that will be traced to your flashlog, or if you use the ActionScript publishing code to load the player, you should see traces in Flex Builder or Flash.

While the player is playing, you can use the debug window in the player to confirm which rendition is being played. To open the player debug window, right-click on the video screen and select Show Debug Info.

Here's the rendition selection function from the SelectLowestRendition.js example:

function selectRendition(context) {
    var renditions = context.renditions;
    var renditionIndex = -1;
    var size = Number.MAX_VALUE;
    for (var i = 0; i < renditions.length; i++) {
        // set the rendition index for the rendition with the smallest size
        if (renditions[i].size < size) {
           size = renditions[i].size;
           renditionIndex = i;
        }
    }
    return renditionIndex;
}

The selectRendition function is passed the context object, from which it uses only the renditions array. Note how the function identifies the smallest rendition and sets the renditionIndex accordingly.

For a more complex example, let's look at SelectOptimalRendition.js. First, see how the example uses two constants to control how closely the selected rendition needs to match the available screen height and bandwidth:

// How far in percent a rendition can be above the video screen height.
var FRAME_HEIGHT_TOLERANCE = 1.2;
// The percent amount the detected bandwidth is reduced when checking against
// encoding. Generally, you want a rendition to be encoded less than the 
// available bandwidth in order to ensure smooth playback.
var ENCODING_RATE_TOLERANCE = 0.70

You can adjust the values in these constants to meet your requirements. This example uses both the detectedBandwidth and the screenHeight from the context object and uses them to select the best match from the renditions.