Bandwidth detection Make sure you reach your entire audience with good quality
Introduction
The Bandwidth detection plugin monitors the bandwidth that is available to the player. Based on this detection, the plugin selects the stream or file that is best suited to the available bandwidth.
The goal is to offer the best viewing experience possible for an audience with varying Internet connection speeds. 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.
(Version 3.2.5)
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.
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.
Demo
The player shown below uses dynamic stream switching with Amazon CloudFront. Here is a tutorial about configuring Amazon CloudFront streaming using Flowplayer.
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.7.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, height: 270, 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-800", width: 480, bitrate: 800 },
{ 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.5.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: 'flowplayer.rtmp-3.2.3.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: 'flowplayer.content-3.2.0.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'
}
}
}
}
});
Additional demos
Configuration
| property / datatype | default | description |
|---|---|---|
| bitrateProfileName string |
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 boolean |
false, if dynamic: true. true if dynamic: 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 boolean |
false | Enables dynamic stream switching (Quality Of Service monitoring) for Adobe Flash Media Server 3 and Wowza Media Server 2. |
| dynamicBuffer boolean |
false | When enabled, this feature will dynamically calculate the best buffer time to suit the available bandwidth. |
| live boolean |
false | Set this to true with live streams. |
| maxWidth int |
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 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. 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 object |
{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. Following rules are available:
|
| rememberBitrate boolean |
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 string |
http | Identifies the type of server that we will be checking against. Available values are 'http', 'red5', 'wowza', and 'fms'. |
| switchOnFullscreen boolean |
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. |
HD button
The HD selection button is is shown in this demo. Here's how to configure it.
To make the button show up in the dock:
hdButton: 'dock'
To make the button show up in the controlbar:
hdButton: 'controls'
To have it in the dock and also in the controlbar:
hdButton: 'both'
Here's how to configure other aspects related to the HD button.
hdButton: {
place: 'dock',
// custom labels for the HD splash
splash: {
onLabel: 'enabled',
offLabel: 'disabled'
}
}
The hdButton object accepts following properties:
| property / datatype | default | description |
|---|---|---|
| place string |
'controls' | Where to display the HD button? 'controls' shows it in the controlbar, 'dock' shows it in the dock, 'both' shows it both in the dock and in the controlbar. |
| splash object/boolean |
{ left: '50%', top: '50%', width: '50%', height: '50%', onLabel: 'IS ON', offLabel: 'IS OFF' } |
Properties for the "HD IS ON" / "HD IS OFF" splash that is briefly displayed when the user toggles between HD on and off. The splash is shown on top of the video area. This object accepts all display properites. The default display properties used with the splash are { left: '50%', top: '50%', width: '50%', height: '50%' }. This sets the splash centered in the player and taking 60% of it's horizontal and vertical space. To disable the splash completely use splash: false. onLabel sets the label text shown below the HD symbol when HD is enabled. Default: 'IS ON'. offLabel sets the label text shown below the HD symbol when HD is disabled. Default: 'IS OFF'. |
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
| method | returns | description |
|---|---|---|
| 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) | 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) | 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 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
| Event | When does it fire? |
|---|---|
| onBwDone() |
Fires when the bandwidth has been detected. The callback is fed with the following arguments:
|
| 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:
You can see this event in action in the dynamic switching demo. |
| 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:
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:
|
| onConnectFailed() |
Fires when a connection attempt has failed. The callback is fed with two arguments:
|
| 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
JavaScript Plugin
The source distribution package contains an example JavaScript plugin you can use to generate a bitrate selection user inteface. You can see the bwcheck JavaScript plugin in this demo.
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.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 the initial bandwidth check
hosts: [
{host:'rtmp://electroteque1.org/bwcheck'},
{host:'rtmp://electroteque2.org/bwcheck'},
{host:'rtmp://electroteque.org/bwcheck'}
]
}
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.
Download
| flowplayer.bwcheck-3.2.5.swf | just the working Flash file to get you going |
| flowplayer.bwcheck-3.2.5.zip | working Flash file (swf) + README.txt and LICENCE.txt |
| flowplayer.bwcheck-3.2.5-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.