Video Resolution

Introduction

This wiki explains the Video resolutions for incoming and outgoing videos in the SDK. By bringing this feature, we are resolving the problems of providing the Best and HIGH (1080p) possible resolution.

As part of this feature, we have exposed the ability to developers to choose the desired resolution in sending & receiving the video streams, when joining the meeting or even mid-meeting if desired.

Pre-requisites

You need to have the following prerequisites.

Developer can choose the resolution before he creates the meeting or joins.

There are two scenarios,

1. Before join, user can create track using webex.meetings.media.getUserMedia() or
2. After join, meeting.getMediaStreams

Device camera should support full HD (1080p) in order to support the feature, if not it will be downscale to maximum supported resolution.

Developer can check if FHD supported your camera from this Webcam Test Resolution.

Also, please ensure the SDK version is webex-js-sdk@2.32.0 or above.

Resolution

Local Resolution

This section tells about what resolution SDK supports while sending video and what restrictions currently we have on different browsers.

The sharpness, smoothness, and overall quality of the video are directly linked to the frame rate, bitrate and other video settings. Below is the table which specifies different resolutions settings available currently in SDK.

Supported Resolution Table (Sending)

Video SDK provides a selection of video dimensions to choose from.

Video Profile	Resolution (Width×Height)	Frame Rate (fps)	Chrome	Firefox	Safari
360p	640 × 360	30	✓	✓	✓
480p	640 × 480	30	✓	✓	✓
720p	1280 × 720	30	✓	✓	✓
1080p	1920 × 1080	30	✓	✓	✓

Default resolution for sending video is 720p. You can upgrade or downgrade video resolution from the available dropdown values listed above.

User can use below listed API to set video resolution while sending local video.

1. Before Joining meeting: Set localQualityLevel before joining meeting using below method Predefined profile

const streams = meeting.getMediaStreams(mediaDirection,"200p");

meeting.addMedia({mediaSettings, localStream: stream.localStream})

Custom profile

const audioVideo = {
    audio: true,
    video: {
        width: {
            max: 400,
            ideal: 400
        },
        height: {
            max: 200,
            ideal: 200
        },
        frameRate: {
            ideal: 10,
            max: 15
        }
    }
};
const mediaDirection = {
    sendAudio: true,
    sendVideo: true,
    sendShare: false
};


const stream = await webex.meetings.media.getUserMedia(mediaDirection, audioVideo)
or
const stream = await meeting.getMediaStreams(mediaDirection, audioVideo)

meeting.addMedia({mediaSettings, localStream: stream.localStream})

if you dont pass the config it will take default level as 720p

Then joining meeting will set your local video resolution as per level passed instead of default level which is 720p.

2. During meeting: Change local video resolution by calling below method with preferred level

meeting.setLocalVideoQuality(level); // will update the resolutions automatically 

// create your own streams

const audioVideo = {
    audio: true,
    video: {
        width: {
            max: 400,
            ideal: 400
        },
        height: {
            max: 200,
            ideal: 200
        },
        frameRate: {
            ideal: 10,
            max: 15
        }
    }
};

const mediaDirection = {
    sendAudio: true,
    sendVideo: true,
    sendShare: false
};

const stream = meeting.getMediaStreams(mediaDirection,"200p");
or 
const stream = await meetings.getMediaStreams(mediaDirection, audioVideo)


await meeting.updateVideo({
   sendVideo: true,
   receiveVideo: true,
   stream: stream.localStream
})

Parameter level for above methods is one of the values from available supported resolution which are: ['360p', '480p', '720p', '1080p'].

Custom resolution

SDK supports developers to pass their own set of custom video resolution settings(refer this for different values and combinations for video) to get desired video resolution instead of selecting from predefined resolutions.

1. Before joining meeting by using getUserMedia():

const audioVideo = {
    audio: true,
    video: {
        width: {
            max: 400,
            ideal: 400
        },
        height: {
            max: 200,
            ideal: 200
        },
        frameRate: {
            ideal: 10,
            max: 15
        }
    }
};
const mediaDirection = {
    sendAudio: true,
    sendVideo: true,
    sendShare: false
};
const config = {
    resolution: {
        maxWidth: 1280,
        maxHeight: 720,
        idealWidth: 1280,
        idealHeight: 720
    }
};

const [localStream, shareStream] = await webex.meetings.media.getUserMedia(mediaDirection, audioVideo, sharePreferences, config)

meeting.mediaProperties.setLocalQualityLevel("200p")

This will create a custom video track and then use this custom track(localStream) to add media after joining the meeting using below method

await meeting.addMedia({ localStream, mediaSettings: mediaDirection })

2. During meeting using getMediaStreams():

To use custom resolution during meeting, first set localQualityLevel by calling below method with desired video resolution. For eg., to set video resolution as 400p x 200p(width x height), then

meeting.mediaProperties.setLocalQualityLevel("200p")

This will set localQualityLevel as your desired 200p and then call getMediaStreams method to set your video resolution as desired also, frame rate could be modified in audioVideo options.

const stream = await getMediaStreams(mediaDirection,audioVideo);

After we get stream value from getMediaStreams call, update current video stream with new stream by calling updateVideo method with desired custom resolution,

await meeting.updateVideo({
   sendVideo: true,
   receiveVideo: true,
   stream: stream.localStream
})

This will set local video resolution with quality level as 200p.

Screenshot is added from our Kitchen Sink app.

System constraints and restrictions

There are some restrictions which currently affect requested video resolution while sending video which are listed below:-

• The camera used to capture video must be of sufficiently good quality. If the user's hardware does not capture the visual information in suitably high definition, it limits the quality of video that is available to the remote user. For e.g., if a user sets video quality to full HD (1080p) while device supports resolution only till 720p (HD) then SDK will automatically downscale the video quality to 720p instead of requested full HD (1080p) resolution. We log the following error while this happens,

Logger.error(‘Local video quality of 1080p not supported, downscaling to highest possible resolution of 720p’)

• Users can check the values or range of values based upon the device or MediaStreamTrack using getCapabilities() method which tells what the browser's or device/video track capabilities are. To get the current values of what video resolution is being sent to remote user currently, then use getSettings() method.

• Bandwidth and stability of network connection limits the quality of video that is available to the remote user if the network quality goes up and down. Also, there’s a slight delay between switching to requested higher resolution video from current lower resolution video.

Settings for media quality

Default setting for local video is 720p & remote is HIGH (1080p).

Remote Resolution

This is the resolution of remote user received on your end. The quality of video received depends on other video settings such as bitrate, frame rate along with other environment factors such as network bandwidth, device capabilities etc.

Note: it's not always guaranteed that you will receive the exact resolution you asked for due to network constraints

Supported Resolution (Receiving)

SDK provides following options from video profile to choose from.

Video Profile (Level)	Resolution (Width x Height)	Frame Rate (fps)	Chrome	Firefox	Safari
HIGH	1920 × 1080	30	✓	✓	✓
MEDIUM	1280 × 720	30	✓	✓	✓
LOW	640 × 480	30	✓	✓	✓

API

To know about all the other APIs in the Webex JS SDK, please visit → https://webex.github.io/webex-js-sdk/api/

Use below API to set remote video resolution.

Set Remote Resolution

meeting.setRemoteQualityLevel("HIGH");

meeting.setRemoteQualityLevel("LOW");

Parameter for above methods is one of the values from this: ['LOW', 'MEDIUM', 'HIGH'] where LOW is 480p, MEDIUM is 720p and HIGH is 1080p.

• Change in the resolution takes time to update as it upgrades/downgrades gradually depending on the quality of network.
• This will only work if the remote user is sending resolution higher than the asked resolution.

Constraints

• If the device does not support full HD (1080p) it will be downscale to maximum supported resolution.

Demo

Kitchen Sink sample app

Please watch Vidcast Demo here for a happy path on the → Vidcast URL.

Errors

The possible errors that one could get from the APIs listed below,

API	Error	How to fix it?
setLocalVideoTrack	Meeting:index#setLocalVideoTrack --> Local video quality of "${localQualityLevel}" not supported, downscaling to highest possible resolution of "${height}p"	If the device doesn’t support it, remote resolution will be set to 720p.
setRemoteVideoConstraints	setRemoteVideoConstraints: unable to set max framesize, value for level "${level}" is not defined	Need to set the defined frame size values.

Layout

Please check Layout for details.