Player Load and Stream Connection APIs

This document describes some methods in the Brightcove Player API that give you an extra level of control over how the player interacts with the FMS streaming video server. In most cases, you should  not need to use these methods. However, they are available if you want to modify the player's default behavior.

• Buffers and streaming video
• Disabling initial bandwidth detection
• Delaying the player's initial connection

Buffers and streaming video

When you are delivering streaming video, the Flash player uses an internal buffer to maintain a steady non-interrupted playback experience. The required size of this buffer is affected mainly by two conditions: the encoding rate of the video and the quality of the network (available bandwidth). Since this buffer stores the next bits to read for content playback, you never want the player to reach a state where the buffer is empty. Filling the buffer takes time, since you need to download the upcoming bits over the network. To deliver a satisfying viewer experience, the player's buffer behavior needs to balance the initial load time against the risk that the buffer becomes empty, leading to video that pauses or plays in stops and starts. The smaller the buffer setting, the sooner playback can begin, since the buffer can be filled quickly. However, for viewers with lower-bandwidth connections, a small buffer can result in the player not downloading data into the buffer as fast as it is reading data out of it. The player will pause to download enough data to fill the buffer again in this scenario and the viewer experience can be very bad. If you have a large buffer size set, initial playback times will be slower, since you need to wait for more data to transfer into it at the start, but the experience during playback should be better because there is less chance of the buffer emptying.

By default, the Brightcove player checks the viewer's bandwidth and weighs this against the video's encoding rate to determine the best size for the buffer in order to produce the best quality viewing experience, with a reasonable player load size. The player continues to check available bandwidth and adjust the buffer size during playback.

Disabling initial bandwidth detection

Two methods in the Player API's VideoPlayer Module, enableInitialBandwidthDetection and setDefaultBufferTime, are available that enable you to control the player's bandwidth detection and buffering behavior. You can use enableInitialBandwidthDetection (which is true by default) to disable the initial bandwidth detection. With enableInitialBandwidthDetection set to false, the player omits its bandwidth detection while it is loading. Without the initial bandwidth detection check, the player is not able to calculate the optimal buffer size, so it uses a default buffer size. The default buffer time is 5 seconds, but you can modify that using the setDefaultBufferTime method. Note that the buffer size refers to the duration of the video in the player's buffer, not the amount of time it takes to load the buffer.

If you are using adaptive streaming (which you will be, unless you are using progressive download or unless you have removed the dynamicStreaming=true parameter from your player publishing code), then disabling initial bandwidth detection and setting the default buffer will affect only the initial player experience. Once playback has started, the adaptive streaming algorithm takes over and starts to calculate the best settings to use for the buffer as the viewer's connection and CPU resources change during the content playback.

Brightcove recommends that in most cases, you should use our standard bandwidth detection and buffering policies and not override them with the enableInitialBandwidthDetection method. However, if you expect your audience generally to have high-bandwidth connections, you can set a comparatively small buffer size, like 2 seconds, so that the buffer is filled quickly and content starts to play back sooner. If you expect your audience to have lower-bandwidth connections, you might set a larger buffer, trading a longer time before the video starts to play back against a smoother, better experience overall.

Example

In this JavaScript example, we disable initial bandwidth detection and set the default buffer size to 10 seconds:

<script type="text/javascript">

var player, video, content, exp;

function onTemplateLoaded(pPlayer) {
   player  = bcPlayer.getPlayer(pPlayer);
   video   = player.getModule(APIModules.VIDEO_PLAYER);
   content = player.getModule(APIModules.CONTENT);
   exp     = player.getModule(APIModules.EXPERIENCE);
   video.enableInitialBandwidthDetection(false);
   video.setDefaultBufferTime(10);
}
</script>
<!--
By use of this code snippet, I agree to the Brightcove Publisher T and C 
found at https://accounts.brightcove.com/en/terms-and-conditions/. 
--> 
[player publishing code]

Delaying the Player's Initial Connection

By default, a Brightcove player that is delivering streaming video connects to the FMS server on load to send user bandwidth information. This behavior means that as soon as the viewer clicks the play button, the player can be ready with a video rendition that best matches the available bandwidth. Once the player establishes a connection to the FMS server, it sends repeated requests to the server to keep the connection alive.

To avoid these repeated requests, you can use the setConnectOnLoad method in the Player API's VideoPlayer Module to delay the player's initial connection to the FMS server until playback is requested by the viewer. Keeping the connect-on-load behavior (the default, true) means a more instant-on experience for the user. However, setting this to false removes the need for the constant connection keep-alive requests prior to actual playback. This call needs to be made prior to the templateReady event in order to work with initially loaded content.

For example, you could use this JavaScript immediately before your player publishing code:

<script type="text/javascript">

var player, video, content, exp;

function onTemplateLoaded(pPlayer) {
     player = bcPlayer.getPlayer(pPlayer);
     video = player.getModule(APIModules.VIDEO_PLAYER);
     video.setConnectOnLoad(false);
}
</script>

This approach is especially helpful if you are using RTMP Tunneled (RTMPT) to deliver your videos, but may be useful in other streaming delivery scenarios as well.