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.2)
Features
- Quality Of Service monitoring and dynamic stream switching.
- Support for progressive download, 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 against Wowza servers running in the HDDN content delivery network.
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.4.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:vod/demo.flowplayer/bbb-400.mp4", width: 320, height: 180, bitrate: 400,
// 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:vod/demo.flowplayer/bbb-800.mp4", width: 480, bitrate: 800 },
{ url: "mp4:vod/demo.flowplayer/bbb-1200.mp4", width: 720, bitrate: 1200 },
{ url: "mp4:vod/demo.flowplayer/bbb-1600.mp4", width: 1080, bitrate: 1600 }
]
},
plugins: {
// bandwidth check plugin
bwcheck: {
url: 'flowplayer.bwcheck-3.2.2.swf',
// HDDN uses Wowza servers
serverType: 'wowza',
// we use dynamic switching, the appropriate bitrate is switched on the fly
dynamic: true,
netConnectionUrl: 'rtmp://vod01.netdna.com/play',
// show the selected file in the content box. This is not used in real installations.
onStreamSwitch: function(bitrate, streamName) {
$f().getPlugin('content').setHtml("Playing now: " + streamName);
}
},
// RTMP streaming plugin
rtmp: {
url: 'flowplayer.rtmp-3.2.3.swf',
netConnectionUrl: 'rtmp://vod01.netdna.com/play'
},
// 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 |
|---|---|---|
| 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 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'. |
| 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. |
| 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. |
| dynamic boolean |
false | Enables dynamic stream switching for Adobe Flash Media Server 3 and Wowza Media Server 2. |
| 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 2 does not have it installed by default). |
| 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. |
| streamSelectionStrategy string |
default |
Possible values: (default, resizable) The strategy to use for the stream selection rule. The default rule will choose a bitrate matching the available bandwidth while also matching a video that is less than or equal to the player screen size. When the player goes fullscreen, the same rule is applied but using the larger fullscreen size. The resizable selection strategy chooses a bitrate with video dimensions less than or equal to the config setting maxContainerWidth which is the maximum width the player can be resized to. This is useful if you want to dynamically resize the player according to the selected video dimensions. |
| maxContainerWidth int |
Used in conjunction with the resizable strategy (see above), sets the maximum width the player can be resized to, or the maximum video width that should be selected when not in fullscreen mode. | |
| enableDynamicBuffer boolean |
false | When enabled, this feature will dynamically calculate the best buffer time to suit the available bandwidth. |
| enableQosMonitor boolean |
false | When enabled, this feature will enable the quality of service monitor for non-dynamic rtmp streams. The quality of service monitor dynamically upgrades / downgrades the stream in realtime. If using the non-dynamic rtmp stream, the stream switching is possible but not seamless. |
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 | 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: QoS monitoring and 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 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. | |
| getSelectionStrategy() | string | Returns the stream selection strategy config set with the streamSelectionStrategy configuration option. |
Events
| Event | When does it fire? |
|---|---|
| onBwDone() |
Fires when the bandwidth has been detected. The callback is fed with the following arguments:
|
| 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:
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.2.swf | just the working Flash file to get you going |
| flowplayer.bwcheck-3.2.2.zip | working Flash file (swf) + README.txt and LICENCE.txt |
| flowplayer.bwcheck-3.2.2-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.