How - and why - to artificially lower bandwidth/bitrate

A subscriber with a good network connection may not need or want the high-bitrate, high-resolution stream that would normally be requested based on the network connection speed. For example, the subscriber may be displaying the video on a small portion of its screen, in which case any resolution beyond that which is being displayed would be superfluous, or may have other limitations such as its CPU.

The video bitrate can be limited temporarily if needed. This can be done on either the publisher side or the subscriber side, but is more typically requested by the subscriber. In other words, a subscriber uses the limit bandwidth feature to inform the Phenix streaming system that it can only use a certain number of bits per second.

The bandwidth limitation does not affect the bandwidth of the entire stream, only that of the specific track you are attempting to limit.

Currently, bandwidth limitations only apply to video. Bandwidths of audio and of data are not affected by this feature.

Determine the desired bandwidth limit, based on the bitrate used by the resolution to be used as a maximum.

For subscribers using content that is being published using multi-bitrate (MBR), the bitrate specified in the limit bandwidth should be about halfway between layers, where the lower value corresponds to the maximum resolution that you wish to set, and the upper value is the next resolution above that maximum. Refer to the Quality Table in the Phenix API documentation for resolutions and their corresponding bitrate values.

For subscribers using content that is being published as a single bitrate (SBR), the bitrate received by the subscriber may not match the requested bitrate. When using WebSDK2.0, if the content is SBR, the bandwidth limit method does not have any effect on the bandwidth received by the requesting client.

To reduce the bitrate for Android and iOS clients, use the limitBandwidth feature.

The effects of limitBandwidth depend on whether the content being used by the subscriber is being published using Multiple Bitrates (MBR) or Single Bitrate (SBR).

When a subscriber invokes limitBandwidth on content that is being published at MBR, the Phenix Adaptive Bitrate (ABR) logic will provide the subscriber with a lower bitrate stream instead of the higher bitrate stream that the platform might otherwise provide based on network throughput.

A subscriber invoking limitBandwidth on SBR content will request that the publisher lower the video bitrate to try to match the requested value. Publishers providing SBR typically lower the bitrate only if the request comes from a certain percentage of users (e.g., if 20% of users request a lower bitrate), as changing the bitrate will affect all subscribers. If too few users request a lower bitrate, the bitrate will not be changed.

When limitBandwidth is called, a disposable is returned. The bandwidth limitation is in effect until the disposable is released, thus the disposable is used to control the duration of the bandwidth limitation.

The video bitrate will not immediately change after limitBandwidth has been invoked.

Similarly, once the disposable has been released, it may take several seconds for the bitrate to recover.

If limitBandwidth is called multiple times before any of the previous disposables are released, then only the most recent override will remain in effect until its disposable is released. Although releasing any of the disposables from earlier limitBandwidth calls will have no effect, it is considered a best practice to dispose of any limitBandwidth disposables that have been replaced by subsequent calls as they are in effect retired/out of scope objects.

1. Set the desired bandwidth limit, in bits per second, using limitBandwidth.

2. To remove the bandwidth limitation, "unset" the limitBandwidth by releasing the disposable that was returned when the limitBandwidth was set. That will allow the bitrate to ramp up to the max video bitrate.

For example, suppose the objective is to restrict the video to a resolution of 360p or lower. The Quality Table shows 520kbps is exactly the video bitrate for the 360p rendition. The next-higher resolution is 480p, with a video bitrate of 830kbps. Assuming that both streams include audio (at 60kbps for this example), the value to set for a bandwidth limit is:

((520kbps video + 60kbps audio) + (830kbps + 60kbps)) / 2 = 735kbps

Convert the limit from kbps to bps (735000) and set that value using limitBandwidth.

The bandwidth limit value is in bits per second.

import PhenixSdk
 
// Previously obtained
let subscriber: PhenixMediaStream = ...
 
// Limit video bitrate to 735kbps for 10 seconds
// We assume there is at least one video track on this stream
var disposable = subscriber.getVideoTracks()[0].limitBandwidth(735000)
 
DispatchQueue.main.asyncAfter(deadline: .now() + 10) {
  // Dropping the disposable will undo the bandwidth limitation
  disposable = nil
}

Other examples can be found with the API documentation for Android or iOS.

WebSDK 2.0 provides a method called setBitrateLimit, which can be used much like the limitBandwidth feature described for Android and iOS.

This value will only be used when the incoming stream has multiple bitrates available.

To enable this feature, add the following to your application's JavaScript (or the equivalent in TypeScript):

channel.setBitrateLimit(500000); /* Value is in BPS */

Like the limitBandwidth feature, this value is in bits per second, so the example above would reduce the incoming stream to no more than 500 Kbps.

To remove the bitrate limit, use the clearBitrateLimit method.

channel.clearBitrateLimit();