Set up common video config

---

Introduction

ZEGO supports setting up the video configuration, such as video resolution, frame rate, and bitrate to provide a better experience in a video call or live streaming scenarios.

Basic concepts

• Resolution:
  • Video resolution: The number of pixels contained in each frame. The video resolution is often expressed in PPI.
  • Capture resolution: The total amount of pixels captured by a camera.
  • Encoder resolution: The resolution of the encoded image.
• Bitrate (bps): The number of bits that are conveyed or processed per unit of time. The bitrate is expressed in the unit bit per second unit.
• Frame rate (fps): The frequency (rate) at which consecutive images (frames) are captured or displayed. The frame rate is often expressed in frames per second or fps.

Prerequisites

Before you begin, make sure you complete the following steps:

• Create a project in ZEGOCLOUD Admin Console, and get the AppID and ServerSecret of your project.
• Integrate the Video Call SDK into the project. For details, see Integration and Implementation.

Set video configuration

To create a stream, call the createZegoStream method, and set the video properties according to the way you capture the video data.

camera

When you capture the video data with the camera, you can refer to the following to set the video quality:

To set the video quality, set the videoQuality parameter of the camera object.

The following table shows the values of the videoQuality parameter. The 1, 2, 3 are the default values, and the value 4 means you can customize the resolution, frame rate, and bitrate. For more details, see Chapter 6 Select the video resolution/frame rate/bitrate.

// Recommended settings. 
let option = {
    audioBitrate: 48
}

// Custom settings.
option = {
    videoBitrate: 300,
    audioBitrate: 48,
        camera: {
        audio: true,
        video : {
            quality: 4,
            width: 480,
            height: 480,
            frameRate: 15
        }
    }
}

zg.createZegoStream(option)

• screen

When you capture the video data with the screen, you can refer to the following to set the video quality:

To set the video quality of the screen sharing, set the videoQuality parameter of the screen object.

The following table shows the values of the videoQuality parameter. The 1, 2, 3 are the default values, and the value 4 means you can customize the frame rate, and bitrate. The width and height allow you to set the resolution of the shared screen without changing the actual proportion of the captured screen.

// Pass in Boolean values.
let option = {
    screen: {
        video: true
    },

    // equal to
    screen: {
        audio: false,
        video: {
            frameRate: 15,
            bitRate: 1500
       }
    }
}

// Pass in the object. 
option = {
    videoBitrate: 1500,
    screen: {
        audio: false,
        video: {
            quality: 4,
            frameRate: 15, 
            width: 1280,
            height: 720
        }
    }
}
zg.createZegoStream(option)

• custom

When you using the third-party raw video data, you can refer to the following to set the video quality:

To set the bitrate of the video, set the bitrate parameter of the custom object, which ranges from 0 - 10240, the default value is 800.

const el = document.querySelector("video")

let option = {
    videoBitrate: 800,
    custom: {
        video: {
            source: el // [source] can be <video>or <audio> object or MediaStream.
        },
        audio: {
            source: el // [source] can be <video>or <audio> object or MediaStream.
        }
    }
}

zg.createZegoStream(option)

Modify video configuration dynamically

To modify the video configuration properties, call the setVideoConfig method.

setVideoConfig(localStream, {
    width: 320,
    height: 240,
    frameRate: 15,
    maxBitrate: 300
})

Development considerations

• Resolution support may vary between devices and browsers. If the camera on some devices can only capture at a certain resolution, in that case, the browser will adjust the resolution automatically; But at the same time, it may not be able to capture the picture and appear black screen issue. In order to be compatible with as many devices and browsers as possible, we recommend you set the width and height of the video resolution to a multiple of 8 when customizing video properties. If the issue persists, check the camera permission settings or change the camera device.

• Whether the video resolution can reach more than 1080p depends on the device performance. This resolution may not be achieved on devices with lower performance features. If you use 720p resolution but the device can't keep up, it's possible that the frame rate will be too low.

• The video frame rate of Safari is 30 FPS and does not support a custom video frame rate.

Resolution/frame rate/bitrate

Generally, the selection of video properties is determined by the actual situation of the product. If you are not clear about the most appropriate resolution, frame rate, and bitrate, refer to the following recommended values when developing audio and video applications.

Resolution

The width and height in the resolution parameter represent the number of horizontal and vertical pixels respectively. The higher the number of pixels per unit length, the clearer the image.

When selecting a resolution, you can select the video resolution based on the size of the video window (i.e. the width and height of the <video> tag). If the video window is small, select a low resolution. Select high resolution if the video window is relatively large.

The SDK presets resolutions for three video quality parameters. You can refer to the common resolution table below to customize the resolutions and aspect ratio for your app.

Frame rate

Frame rate indicates how many frames are encoded per second. The higher the frame rate, the smoother the images. The SDK recommends using default values of 5, 15, and 20, which you can set as needed.

Bitrate

Bitrate refers to the data traffic per unit time of a video file. The bitrate parameter is mainly used to control bandwidth usage and codec resource consumption.

The relation between resolution/frame rate/bitrate

Bitrate is approximately equal to frame rate times the amount of data in a frame. So the higher the frame rate and resolution, the higher the bitrate of the transmission.

When the actual transmission bitrate is low due to poor network, device, and browser restrictions, and low target bitrate parameters, the real-time frame rate and resolution will fluctuate somewhat, but the frame rate will be maintained first and the resolution will be reduced.

So if you don't have high requirements for fluency, we recommend setting a low frame rate to keep the images clear.

Recommended values for common scenarios

• 1v1 video calling:

  • Resolution: 320 × 240, Frame rate: 15 fps, Bitrate: 200 kbps
  • Resolution: 640 × 360, Frame rate: 15 fps, Bitrate: 400 kbps

• Multi-party video calling/video conference

  • Resolution: 160 × 120, Frame rate: 15 fps, Bitrate: 65 kbps
  • Resolution: 240 × 180, Frame rate: 15 fps, Bitrate: 120 kbps
  • Resolution: 320 × 240, Frame rate: 15 fps, Bitrate: 200 kbps

• Live streaming, such as live video streaming, in-game live streaming etc. (Larger bitrates are needed to improve video quality).

  • Resolution: 1280 × 720, Frame rate: 15 fps, Bitrate: 1500 kbps
  • Resolution: 1280 × 720, Frame rate: 30 fps, Bitrate: 3000 kbps

You can set other common resolutions, frame rates, and bitrates by referring to the table below.