This is a message.

Offer the best viewing experience

The Bandwidth detection plugin monitors the bandwidth that is available and selects the stream or file that is best suited.

The player shown above uses dynamic stream switching with Amazon CloudFront. Here is a tutorial about configuring Amazon CloudFront streaming using Flowplayer.

People with fast connections are served with HD content; people with slow connections are served with smaller files (i.e. lower bitrate). Playback needs to be uninterrupted while maintaining the best possible video quality. Video files are encoded with several different bitrates so that good matches are available for the connection speeds that are being targeted.

Quality Of Service monitoring makes sure that playback continues uninterrupted using the best possible quality. The plugin continuously monitors and calculates the following metrics: available maximum bandwidth, number of dropped video frames, the amount of data currently buffered and the available video screen size. Based on these factors, it determines the optimal bitrate. If needed the stream is dynamically switched during playback (requires Wowza 2.2.4 and above or Adobe Flash Media Server 3). Continuous monitoring and control is required to ensure good results as the available bandwidth fluctuates.

The player dimensions are considered when selecting the appropriate file. The plugin never selects a file that has dimensions larger than the player's screen. Selecting too large a file would waste bandwidth. When going fullscreen, the player switches to a larger file if available bandwidth permits.

Recommendations For Dynamic Stream Switching

Flash Media Server and Wowza Media Server require consistant encoding specifications to obtain smooth video switching. It is recommended a keyframe interval of 5 seconds to make smooth switching fast, and required to be the same for all multi-rate videos. The same audio samplerate and frame size is also recommended for smooth switching.

More Information:

Features

  • Quality Of Service monitoring and dynamic stream switching.
  • Support for progressive download, pseudostreaming (except for php-pseudostreaming), and RTMP.
  • Manual selection of the bitrate. Users can be offered the option to select their preferred bitrate.

Flowplayer configuration

Here is the configuration for this demo. Check the commented code. The bitrates array is used to specify the video files corresponding to the different bitrates. The bwcheck plugin is simple to configure. Use the dynamic property to enable dynamic switching and quality of service monitoring. 

flowplayer("player", "http://releases.flowplayer.org/swf/flowplayer-3.2.11.swf", {
    clip: {
 
       urlResolvers: 'bwcheck',
       provider: 'rtmp',
       autoPlay: false,
       scaling: 'fit',
 
       // available bitrates and the corresponding files. We specify also the video width
       // here, so that the player does not use a too large file. It switches to a
       // file/stream with larger dimensions when going fullscreen if the available bandwidth permits.
       bitrates: [
         {
            url: "mp4:bbb-800", width: 480, bitrate: 800,
            // this is the default bitrate, the playback kicks off with this and after that
            // Quality Of Service monitoring adjusts to the most appropriate bitrate
            isDefault: true
         },
         { url: "mp4:bbb-1200", width: 720, bitrate: 1200 },
         { url: "mp4:bbb-1600", width: 1080, bitrate: 1600 }
       ]
    },
    plugins: {
 
        // bandwidth check plugin
        bwcheck: {
            url: "flowplayer.bwcheck-3.2.10.swf",
 
            // CloudFront uses Adobe FMS servers
            serverType: 'fms',
 
            // we use dynamic switching, the appropriate bitrate is switched on the fly
            dynamic: true,
 
            netConnectionUrl: 'rtmp://s3b78u0kbtx79q.cloudfront.net/cfx/st',
 
            // show the selected file in the content box. This is not used in real installations.
            onStreamSwitchBegin: function (newItem, currentItem) {
               $f().getPlugin('content').setHtml("Will switch to: " + newItem.streamName +
                " from " + currentItem.streamName);
            },
            onStreamSwitch: function (newItem) {
               $f().getPlugin('content').setHtml("Switched to: " + newItem.streamName);
            }
        },
 
        // RTMP streaming plugin
        rtmp: {
            url: "http://releases.flowplayer.org/swf/flowplayer.rtmp-3.2.10.swf",
            netConnectionUrl: 'rtmp://s3b78u0kbtx79q.cloudfront.net/cfx/st'
        },
 
        // a content box so that we can see the selected video dimensions. This is not used in real
        // installations.
        content: {
            url: "http://releases.flowplayer.org/swf/flowplayer.content-3.2.8.swf",
            top: 0, left: 0, width: 250, height: 150,
            backgroundColor: 'transparent', backgroundGradient: 'none', border: 0,
            textDecoration: 'outline',
            style: {
                body: {
                    fontSize: 14,
                    fontFamily: 'Arial',
                    textAlign: 'center',
                    color: '#ffffff'
                }
            }
        }
    }
});

JavaScript

Additional demo and alternative plugin

Configuration

Bitrate items

The available bitrates and their properties are defined in the clip object. Here is an example of this bitrate list and the bitrate items contained in it. 

clip: {
    bitrates: [
        { url: "mp4:bbb-800", width: 480, bitrate: 800, isDefault: true },
        { url: "mp4:bbb-1200", width: 720, bitrate: 1200 },
        { url: "mp4:bbb-1600", width: 1080, bitrate: 1600 }
    ]
}

JavaScript

The properties of the bitrate items are as follows:

property / datatypeDescription

url (required)

The url to the clip.

bitrate (required)

The clip bitrate.

width (required)

The width of the video encoded in this bitrate.

isDefault

Set the clip as default to play on startup, will be used as fallback if there was no bandwidth detected.

Plugin configuration options

property / datatypeDefaultDescription

bitrateProfileName

bitrateProfile

Used when detected bandwidth values are remembered (see the rememberBitrate setting). This is the name of the Shared Object where the bitrates are saved. You might want to change this if you have different sets of files and you want to keep the detected bandwidths separate for those sets.

cacheExpiry

86400

Used when detected bandwidth values are remembered (see the rememberBitrate setting). The expiration time for cached bitrates. The default value is 24 hours (86400 seconds). After the expiration period has passed, the bandwidth is re-detected.

checkOnStart

 
false

Set this to true if you want to perform an initial bwcheck with RTMP. This way the playback can be started automatically with a bitrate based on this initial check. Relying completely on bitrate monitoring and dynamic bitrate switching might be a bit slower to adjust to the best bitrate. If you set this to true, make sure your RTMP server has the bwchecker application installed (Wowza does not have it installed by default).

dynamic

false

Enables dynamic stream switching (Quality Of Service monitoring) for Adobe Flash Media Server 3 and Wowza Media Server 2.

dynamicBuffer

false

When enabled, this feature will dynamically calculate the best buffer time to suit the available bandwidth.

live

false

Set this to true with live streams.

maxWidth

null

Sets the maximum video width that will be selected. By default the maximum width is the width of the video screen area. This value can be used to override this. Sometimes used when the player is resized dynamically using scripting to follow the selected stream dimensions.

netConnectionUrl

null

The URL used to check the bandwidth. For HTTP-based checking, this should point to a reference file that is loaded as part of the check. The file should reside on the same host as the plugin, or it will require domain context policies for remote loading of the file to prevent sandbox issues. For RTMP this should be a RTMP url pointing to a streaming server.

qos

{bwUp: true, bwDown: true, frames: false, buffer: true, screen: true}

Specifies the dynamic switching rules to be used. Used when dynamic is set to true. The following rules are available:

  • bwUp - switches up (to a larger bitrate) when sufficient bandwidth is available
  • bwDown - switches down (to a smaller bitrate) when sufficient bandwidth is not available
  • frames - switches up or down based on the number of dropped video frames. Not used by default.
  • buffer - switches up or down based on the size of the video buffer
  • screen - switches up or down based on the width of the video screen. If you remove the screen rule the plugin selects the stream without considering the screen size. This causes a video wider than the screen to be selected if the other rules allow this.

  • ratio - used for Adobe Http Streaming.

  • bitrateSafety - is part of the calculation for going up and down, this will make the switch happen more closely near the bitrate in the list when comparing with bandwidth, its default is 1.15 * bitrate.

  • minDroppedFrames - if you increase this to 5 the switch up rule will not try and drop down if its less than this.
  • maxUpSwitchesPerStream - if you increase this it will increase the count a stream can switch up before being locked for a certain interval default is 3
  • waitDurationAfterDownSwitch - the interval to wait before allowing to switch up in milliseconds default is 30000 (30 seconds)
  • clearFailedCountInterval - the interval to wait before clearing a locked out bitrate. This is the prescision value times the clip duration, the default is 1. A value of 0.5 would mean half the clip duration.
  • ruleCheckInterval - the interval between switching rule checks in milliseconds, default is 500

rememberBitrate

false

Indicates whether the detected bandwidth should be remembered for the client browser. If true the detection is performed only once per domain and stored on the client browser. If false the detection is done every time a clip starts playing.

serverType

http

Identifies the type of server that we will be checking against. Available values are 'http', 'red5', 'wowza', and 'fms'.

switchOnFullscreen

true

Used when dynamic is set to false. Causes a bandwidth check and a switch when entering fullscreen or exiting fullscreen. When dynamic is set to true the plugin is doing QoS monitoring and switching dynamically if needed, also taking care the screen resize that happens with fullscreen mode.

RSS files

You can specify the available bitrates and files in a RSS playlist file. See this demo with a RSS file used to specify the bitrates for more information.

JavaScript API

Methods

MethodReturnsDescription

getBitrate()

int

Gets the current bitrate. The returned value is the bitrate in use after the latest bitrate transition has been completed. If a bitrate switch is in progress the value reflects the bitrate right now being used, not the one we are switching to.

setBitrate(bitrate)

null

Changes the stream to the specified bitrate. The specified value should be one of the values contained in the bitrates array. If the player is currently playing a clip, the stream corresponding to the specified bitrate is started. If dynamic stream switching is enabled, the stream switches dynamically while playing; otherwise, the stream plays from the start of the clip. Note: QoS monitoring and dynamic stream switching is disabled when this method is called so that the dynamic switching does not override the bitrate specified using this method. You can enable dynamic switching again using the enableDynamic() method (see below).

enableDynamic(enabled)

null

Enables or disables dynamic stream switching. The specified enabled value is a Boolean specifying the enabled state.

checkBandwidth()

null

Initiates a new bandwidth check. The detected bandwidth is stored in the client browser if the config option rememberBitrate is set to true. If the player is currently playing a clip, a new stream based on the detected bandwidth is selected and started. If dynamic stream switching is enabled, the stream switches dynamically while playing; otherwise, the stream plays from the start of the clip. When the bandwidth check is successfully called, the onBwDone event is called allowing you to get the results.

Events

EventWhen does it fire?

onBwDone()

Fires when the bandwidth has been detected. The callback is fed with the following arguments:

  • url the complete URL that was resolved for playback
  • mappedBitrate the bitrate selected from the bitrates array
  • detectedBitrate the detected bitrate used to resolve the mappedBitrate

onStreamSwitchBegin(newItem, currentItem)

Fires when a bitrate switch is initiated. A second event is fired when the switch is completed, see below. This event is called only when the dynamic configuration property is enabled. The callback is fed with two bitrateItem objects that describe the new bitrate we are switching to and the current one. These objects have following properties:

  • streamName - the name of the stream
  • bitrate
  • width

onStreamSwitch(newItem)

Fires when the bitrate switch has been completed. Once fired the new stream starts playing and is shown in the player. This event is called only when the dynamic configuration property is enabled. The callback is fed with an object argument that has following properties:

  • streamName - the name of the stream
  • bitrate
  • width

onStreamSwitchFailed(info)

Fires when the server has returned a failure to dynamically switch the video. This is generally due to keyframe inconsistancies between the multi-rate videos which is required by the servers. As fallback the bwcheck plugin will attempt a native switch of the video by reloading the video.

  • info - The message returned from the server

Here are the events related to establishing a connection and clustering. Note that if you are not clustering the hosts used for bandwidth checking, the host index will always have a value of zero.

EventWhen does it fire?

onConnect()

Fires when the plugin starts a new connection attempt. The callback is fed with two arguments:

  • host the URL from the hosts list where the connection is attempted from
  • hostIndex the index of the host in the hosts list

onConnectFailed()

Fires when a connection attempt has failed. The callback is fed with two arguments:

  • host the URL from the hosts list where the failure happened
  • hostIndex the index of the host in the hosts list

onFailed()

Fires when all hosts in the cluster have failed. See also the connectCount option, that specifies how many times the hosts are evaluated before failing.

Advanced features

Clustering of bandwidth checks

You can configure an array of hosts to be used for the bandwidth check. The plugin chooses a live host from this array until it finds one that does not fail. This provides a way to add failover. Note that this is not designed to be used with dynamic stream switching as the hosts in the cluster are used only in the initial RTMP bandwidth check call. Here is an example of how to configure clustering for the bandwidth check: 

bwcheck: {
        url: "flowplayer.bwcheck-3.2.10.swf",
        serverType: 'red5',
 
        // the actual streaming happens from this host. In reality you would
        // probably configure a cluster of hosts here too.
        netConnectionUrl: 'rtmp://electroteque.org/bwcheck',
 
        // the hosts used for the initial bandwidth check
        hosts: [
            {host:'rtmp://electroteque1.org/bwcheck'},
            {host:'rtmp://electroteque2.org/bwcheck'},
            {host:'rtmp://electroteque.org/bwcheck'}
        ]
    }

JavaScript

The configuration above is for clustering the bandwidth checking connections only. If you want to cluster your streaming connections, then you need to use our clustering plugin.

The clustering configuration for bandwidth checking and for the actual streaming are separate. This is because in many cases the RTMP applications used for bandwidth checking are different from the applications that are used for streaming, and therefore their host URLs are also different.

Download

flowplayer.bwcheck-3.2.10.swf

just the working flash file to get you going
flowplayer.bwcheck-3.2.10.zip

working flash file (swf) + README.txt and LICENSE.txt
flowplayer.bwcheck-3.2.10-src.zip

source code

Please right-click and choose "Save link as..." (or similar)

See the version history for this tool.

Found a bug?

If you encounter problems in this script, please send a bug report to the bug reporting forum. If you have a problematic page, including a direct URL to that page is by far the most effective way of helping us to find a bug.