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.

NOTE: For webex-js-sdk@2.32.0 or above → values mapping used for resolutions ['LOW', 'MEDIUM', 'HIGH'] are LOW is 480p, MEDIUM is 720p and HIGH is 1080p. If using earlier versions, LOW is 360p, MEDIUM is 480p and HIGH is 720p.

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: Default resolution is set to 720p and for changing it with,

• Predefined profile: pass quality level to getMediaStream method like

const [localStream, shareStream]  = await meeting.getMediaStreams(mediaDirection, "480p");

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

NOTE: Do not pass any resolution other than pre-defined resolutions otherwise it will throw level not supported error. For using resolutions other than pre-defined, use custom profile as described later.

Then use above localStream for adding media after joining a meeting like,

await meeting.addMedia({mediaSettings, localStream})

• Custom profile

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.

Also developers can pass different constraints like facingMode, frameRate, deviceId, etc to get video media stream with required constraints applied on it(check example below). Available values for facingMode are ["user", "environment", "left", "right"]. Refer to this for detailed information on facingMode.

const audioVideo = {
    audio: true,
    video: {
        width: {
            max: 400,
            ideal: 400
        },
        height: {
            max: 200,
            ideal: 200
        },
        deviceId: "dummyId",
        frameRate: {
            ideal: 10,
            max: 15
        },
        facingMode: {
            ideal: "user"   //user means developer is asking for a video source which is facing toward the user; this includes, for example, the front-facing camera on a smartphone
        },
    }
};

const [localStream, shareStream] = await meeting.getMediaStreams(mediaDirection, audioVideo)

or

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

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({mediaSettings, localStream})

2. During meeting:

• Change local video resolution by calling below method with preferred level

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

• Using custom stream

const [localStream, shareStream] = await meeting.getMediaStreams(mediaDirection, audioVideo)

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

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 the 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.
getMediaStreams	ParameterError: ${audioVideo} not supported. Either pass level from pre-defined resolutions or pass complete audioVideo object	Pass level from pre-defined resolutions or use complete audioVideo object with video property.
getUserMedia	Media:index#getMedia --> navigator.mediaDevices.getUserMedia failed - [object OverconstrainedError] (facingMode)	If developer request for back camera(environment) on a laptop device, overconstrained error will occur. Use either ideal instead of exact or request available constraints only like front camera on laptop device.

Layout

Please check Layout for details.