How to use setPreferredResolution() to manage bandwidth usage for subscribed streams

Objective

Limit bandwidth usage for inbound streams by requesting an appropriate resolution for each subscribed stream.

when a stream is published with simulcast there are multiple versions or layers of the stream published at different resolutions depending on the camera resolution and available network bandwidth.  The primary purpose of simulcast is to allow users with low network performance to subscribe to a lower resolution of a stream while others still see the high definition version.  However, the setPreferredResolution function allows developers to use this to optimise their Video API usage.

An example is a multi-party call.  If you have 6 participants onscreen at the same time and they all have HD cameras publishing at 720p you will, by default, stream the highest quality version of each stream.  What happens if one person then shares their screen.  You may have the screen-share take up the majority of the screen space and then a stack of smaller elements to one side.

The examples below can help manage bandwidth usage for these streams and improve overall quality.

Applies To

• Vonage Video API
• Streams published with Simulcast (What is Scalable Video (Simulcast)?)
• JS SDK
  NOTE: that these examples are using the JS SDK but the same functions are available in native SDKs as well.  More information is available on our Developer Site

Procedure

There are two methods available to set your preferred resolution for a subscribed stream.  The first option is to set this when subscribing using the properties object when using session.subscribe().  The second option is to call the setPreferredResolution function of the subscriber object while subscribed to the stream.

Example 1:

var subscriberOptions = {
  preferredResolution: {width: 320, height: 180}
}
session.on("streamCreated", function(event) { 
  subscriber = session.subscribe(event.stream, targetHtmlElement, subscriberOptions); 
});

This sets the preferred resolution of your subscriber when it is created.

Example 2:

subscriber.setPreferredResolution({width: 320, height: 180})

This allows you to set your preferred resolution while a stream is in place.

In the screen-sharing example mentioned above you may have 6 camera participants stacked on one side with each one at 120x90 (WxH in pixels) on screen.  You can call the following for each camera stream when the screen-share starts:

subscriber.setPreferredResolution({width: 120, height: 90})

This is a "preferred" resolution.  It is not likely that this resolution is available but the server will stream the next higher resolution if not.  In this scenario, you avoid streaming six 720p streams when the video will be scaled down to 120x90 onscreen.

Using setPreferredResolution() when UI elements are resized can help to ensure you are always receiving the most appropriate stream resolution for the best user experience.

NOTE: DO NOT call subscriber.setPreferredResolution() immediately after calling session.subscribe().  This is a server side feature and when doing this the server side of the subscribed stream will not yet be created.  If you need to set the preferred resolution immediately you should use example 1 above and set it as a subscriber parameter.

Additional Information

As noted previously, this is a "preferred" setting.  A lower resolution stream may still be provided if your network or device is struggling to maintain the higher resolution you have requested.

Duplicate requests to set resolution will not be sent to the Media Server.  If you request the same resolution more than once the request is ignored by the SDK.

You can also use setPreferredFrameRate() to further optimise usage.

Developer Documentation:
https://tokbox.com/developer/sdks/js/reference/Subscriber.html#setPreferredResolution

https://tokbox.com/developer/sdks/js/reference/Subscriber.html#setPreferredFrameRate