You will recieve your password to this address. Address is not made public.

Your preferred username that is used when logging in.

Bandwidth detection Selecting the best bitrate based on available bandwidth

Introduction

The Bandwidth Check plugin is used to detect the bandwidth that is available to the player. Based on the result of this detection the plugin selects the stream or file that is best suited for the available bandwidth. This way the viewing experience of the user is optimal without unnecessary buffering in the middle of the stream. If the user has a broadband connection (large bandwidth) he will be served with a HD quality stream and will have a good viewing experience, and with slower connection speeds a file with a smaller bitrate will be selected.

Video (and audio) files are encoded with several different bitrates so that good matches are available for the connection speeds that are being targeted.

(Version 3.1.3)

Features

HTTP Example

This example demonstrates HTTP-based bandwidth checking:

Search engine friendly content
Your speed appears here.

The configuration is shown below. This example uses HTTP to detect the bandwidth. It loads a reference file from the URL configured with netConnectionUrl and calculates the bandwidth based on the download speed and file size.

flowplayer("player", "http://releases.flowplayer.org/swf/flowplayer-3.1.5.swf", {
		
	// configure the required plugin
	plugins:  {
		
		// bandwidth check plugin
		bwcheck: {  
			url: 'flowplayer.bwcheck-3.1.3.swf',   
			netConnectionUrl: 'http://releases.flowplayer.org/swf/expressinstall.swf',
			bitrates: [40, 150, 400, 700, 1000],
		
			// this method is called when the bandwidth check is done
			onBwDone: function(url, chosenBitrate, bitrate) {
				var el = document.getElementById("info");
				el.innerHTML = "Your speed is: " +bitrate+ "<br />Video file served: " +url;
			}
		}
		
	},
	clip: {
		urlResolvers: 'bwcheck'
	}
	
});

You need to have different video files for each bitrate you wish to target. This configuration uses the following files and these need to all be available on the server:

Configuration

Here is a list of the configuration options:

property / datatype default description
checkOnBegin
boolean
true If true (the default) the plugin checks the bandwidth for every clip once their playback starts even when the clips don't specify this plugin as their urlResolver. Specify false here if you have clips in the playlist for which the bandwidth should not be checked.
netConnectionUrl
string
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. For RTMP this should be a RMTP url pointing to a streaming server.
serverType
string
http Identifies the type of server that we will be checking against. Available values are 'http', 'red5', 'wowza', and 'fms'.
bitrates
array or object
List of available bitrates. The server should have video files encoded in each of these specified bitrates. The detected bandwidth is mapped to the closest value found in this array and the stream file name is resolved based on the mapped bitrate value. See also below on how to give labels to bitrates.
cacheExpiry
number
86400
The expiry time for cached bitrates. The default value is 24 hours (86400 seconds). After the expiry period has passed the bandwidth is re-detected. See also the rememberBitrate setting.
defaultBitrate
int
The bitrate used if the detection fails. This should be one of the values contained in the bitrates array.
urlPattern
array
{0}-{1}.{2} A pattern used to resolve the file name based on the bitrate. First the detected bitrate is mapped to an available bitrate using the bitrates array (see above) and then the URL is resolved by applying this pattern. For example, if the URL configured for Flowplayer is "skyandice.flv" and the mapped bitrate is 400, then the resolved URL is "skyandice-400.flv". {0} refers to the clip basename, {1} is the mapped bitrate, and {2} is file extension.
urlExtension
string
The file extension used when applying the urlPattern. You need to specify this if the URL's don't have common extensions like '.flv' or '.mp4' which can be determined by looking for the last '.' in the filename and using the characters following its position to be the extension. With the Highwinds CDN this extension is currently flv.smil when FLV files are used.
rememberBitrate
boolean
true Should the detected bandwidth 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.
dynamic
boolean
false Enables dynamic stream switching for Adobe Flash Media Interactive Server. See below for more details.

Bandwidth checking hosts can be clustered so that you can have many of them available to serve your files. If any of the checks fails, then another host is selected. The following configuration options are related to clustering:

property / datatype default description
hosts
array
The hosts that are part of the cluster. These should be base URLs for each host to be used together with the clip's URL. The complete URL will be formed by concatenating the host URL and the clip's URL.
connectTimeout
int
2000 Connection timeout for a single connection attempt, given in milliseconds. After this timeout has been reached, the connection attempt is considered a failure and the next host in the cluster is evaluated.
connectCount
int
3 Number of times to loop through all the hosts in the cluster before giving up.
failureExpiry
int
2000 The expiry time (in milliseconds) to wait before a failed server is attempted again. The failure timestamp is stored in the client browser and a new connection attempt is only attempted after this time has expired.
loadBalance
boolean
false When this is set to true the plugin accesses the configured hosts randomly providing the ability to balance the streaming load more evenly between each host to improve overall performance. If any of the hosts does not work, then another host is chosen.

You can assign labels to the bitrate values. These labels will be used when the filename is resolved. The labels are specified in the bitrates configuration variable:

// bitrates with their labels
	bitrates: { low: 256, mid: 512, high: 1024 },
	// our URL's have following extension
	urlExtension: 'mp4.smil'

With this configuration we get the following URLs when the original URL before bwcheck is "video.mp4.smil":

The use of labels allows us to change the bitrates corresponding to the labels and the names of the files continue to make sense. Additionally the player configuration does not need to change.

RTMP Example

The bwcheck plugin supports RTMP servers such as Wowza, Red5 and Adobe FMS. Below is an example:

Search engine friendly content
Click on the splash image above.

The configuration is shown below. Note that the serverType and urlPattern values that need to be defined for Adobe FMS.

flowplayer("rtmpPlayer", "http://releases.flowplayer.org/swf/flowplayer-3.1.5.swf", {

	// configure the required plugins
	plugins:  {

		// RTMP streaming plugin
		rtmp: {
			url: 'flowplayer.rtmp-3.1.3.swf',
			netConnectionUrl: 'rtmp://cyzy7r959.rtmphost.com/flowplayer'
		},

		// bandwidth check plugin
		bwcheck: {
			url: 'flowplayer.bwcheck-3.1.3.swf',

			// Influxis uses Flash Media Servers
			serverType: 'fms',

			// Use this connection for bandwidth detection
			netConnectionUrl: 'rtmp://cyzy7r959.rtmphost.com/flowplayer',

			// available bitrates for file names
			bitrates: [40, 150, 400, 700, 1000],

			// use a customized urlPattern for file names
			urlPattern: '{0}-{1}',

			// this method is called when the bandwidth check is done
			onBwDone: function(url, chosenBitrate, bitrate) {
				var el = document.getElementById("rtmpInfo");
				el.innerHTML = "Your speed is: " +bitrate+ "<br />Video file served: " +url;
			}
		}

	},

	// configure the clip to use the rtmp plugin for providing video data
	// and the bwcheck plugin in resolving the URLs
	clip: {
		provider: 'rtmp',
		
		// use bwcheck for all clips
		urlResolvers: 'bwcheck'
	}

});

With the Wowza server you need to install the bwcheck app that is bundled in the Wowza distribution. Similarily with Red5 you need to install its bwcheck application that can be installed using Red5's installer. With Adobe FMS bandwidth checking works without any extra steps.

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. Here is an example configuration on how to configure clustering for the bandwidht check:

bwcheck: {
        url: 'flowplayer.rtmp-3.1.3.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 bandwidth checking
        hosts: [
            {host:'rtmp://electroteque1.org/bwcheck'},
            {host:'rtmp://electroteque2.org/bwcheck'},
            {host:'rtmp://electroteque.org/bwcheck'}
        ],

        defaultBitrate: 300,
        bitrates: [
            100,300,500,700
        ],
        //{0} is the filename, {1} is the bitrate, {2} is the extension
        urlPattern: '{0}-{1}.{2}'
    }

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 RMTP applications used for bandwidth checking are different from the applications that are used for streaming, and therefore their host URLs are also different.

Dynamic stream switching

Dynamic stream switching is available in Adobe's FMS 3.5. In dynamic switching the available bandwidth is monitored while the stream plays and the stream is switched on-the-fly if the available bandwidth decreases or increases. See more information about dynamic stream switching in Dynamic stream switching with Flash Media Server 3.

Dynamic stream switching is configured just like RTMP bandwidth checking for Adobe FMS and by adding the option dynamic: true to the plugin's configuration. Here is a page demonstrating this in action.

Using it together with other plugins

You can use bandwidth checking together with other plugins like the secure streaming plugin. In fact it is possible to chain together 2 or more URL resolver plugins.

JavaScript API

Methods

method returns description
getBitrate int Returns the mapped bitrate after it has been detected. If playback is not started then this method tries to return the remembered bitrate if the rememberBitrate configuration option is enabled.
setBitrate(bitrate) 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: Dynamic stream switching is disabled when this method is called so that the dynamic adaption does not override the bitrate specified using this method. You can enable dynamic switching again using the dynamic() method (see below).
dynamic(enabled) Enables or disables dynamic stream switching. The specified enabled value is a Boolean specifying the enabled state.
checkBandwidth() 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 dynamicaly 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

Event When 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
onStreamSwitch() Fires when the bandwidth has been dynamically switched. This event is called only when the dynamic configuration property is enabled. The callback is fed with the following arguments:
  • bitrate the bitrate selected from the bitrates array
  • newUrl the complete URL that was resolved for playback
  • oldUrl the previous URL being used before the switch

You can see this event in action in the dynamic switching demo.

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.

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

Download

flowplayer.bwcheck-3.1.3.swf just the working Flash file to get you going
flowplayer.bwcheck-3.1.3.zip working Flash file (swf) + README.txt and LICENCE.txt
flowplayer.bwcheck-3.1.3-src.zip source code

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

See the version history for this tool.

NOTE We are no longer providing packed scripts. Althought they may have smaller file size they offer less performance than minified scripts. See details from JavaScript Library Loading Speed.

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.