Common Video Configuration
Feature Overview
When making video calls or live streaming, developers can set video attributes as needed to adjust the clarity and smoothness of the video, thereby obtaining a better user experience.
- Resolution:
- Video resolution: A parameter used to measure the amount of data in an image, usually expressed as ppi.
- Capture resolution: The resolution of the screen provided by capture devices such as cameras.
- Encoding resolution: The resolution of the screen after encoding processing.
- Bitrate: The number of bits transmitted per second, in bps (bit per second).
- Frame Rate: A measure of the number of video frames displayed per unit time, in fps (Frame Per Second).
Sample Source Code Download
Please refer to Download Sample Source Code to get the source code.
For related source code, please see the files in the "src/Examples/CommonFeatures/CommonVideoConfig" directory.
Development Notes
- Different devices and browsers may support resolutions differently. If the camera of some devices can only capture at a specific resolution, in this case, the browser will automatically adjust the resolution; but at the same time, a black screen may appear due to the inability to capture the screen. To be compatible with as many different devices and browsers as possible, it is recommended that developers set the width and height of the resolution to a multiple of 8 when customizing video attributes. If the black screen problem still cannot be solved, please check the camera permission settings or replace the camera device.
- Whether the video can reach a resolution of 1080p or above depends on the performance of the device. This resolution requirement may not be achieved on devices with lower performance. If 720p resolution is used and the device performance cannot keep up, the frame rate may be too low.
Prerequisites
Before setting video attributes, make sure:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and Server address. For details, please refer to Console - Project Information.
- You have integrated ZEGOCLOUD Express SDK in your project and implemented basic audio/video streaming. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
Usage Steps
Set Video Attribute Configuration
Call the createZegoStream interface to create a ZegoLocalStream stream instance object. Different video data capture methods use different parameters to set video attribute configuration. If no special settings are made, the SDK will automatically apply the resolution, bitrate, and frame rate suitable for the selected scenario to obtain the best experience effect according to the selected scenario. For details, please refer to Scenario-based Audio and Video Configuration.
- Each time a stream is created, you can only choose one of "camera", "screen", and "custom". If you need to create multiple streams, you can call the createZegoStream interface multiple times.
- Although the API supports setting resolution, many devices do not support custom resolutions. It is recommended to use preset values.
-
camera
When capturing source data through a camera, use the "quality" parameter in the "camera" object to set the video quality. The combined values of this parameter are shown in the table below. Among them, 1, 2, and 3 are preset values. If the value is 4, it means that developers can customize the resolution, frame rate, and bitrate. For related settings, please refer to How to Choose Video Resolution/Frame Rate/Bitrate in this article.
To be compatible with as many devices and browsers as possible for video screen capture, it is recommended to set the width and height of the resolution to a multiple of 8 when customizing video parameters.
| Value | Resolution | Frame Rate (fps) | Bitrate (kbps) |
|---|---|---|---|
| 1 | 320 × 240 | 15 | 300 |
| 2 | 640 × 480 | 15 | 800 |
| 3 | 1280 × 720 | 20 | 1500 |
| 4 | width × height | frameRate | bitrate |
// Use recommended parameters
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 capturing source data through the screen, use the "quality" parameter in the "screen" object to set the screen sharing video quality. The combined values of this parameter are shown in the table below. Among them, 1, 2, and 3 are preset values. If the value is 4, it means that developers can customize the frame rate and bitrate. The resolution of screen sharing is set through width and height, but it will not change the actual captured screen ratio.
| Value | Frame Rate (fps) | Bitrate (kbps) | Applicable Scenarios |
|---|---|---|---|
| 1 | 20 | 800 | Suitable for scenarios with high requirements for smoothness. |
| 2 | 15 | 1500 | Suitable for scenarios that balance smoothness and clarity. |
| 3 | 5 | 2000 | Suitable for scenarios with high requirements for clarity. |
| 4 | frameRate | bitrate | Custom. |
// Pass a boolean value
let option = {
screen: {
video: true
},
// equal to
screen: {
audio: false,
video: {
frameRate: 15,
bitRate: 1500
}
}
}
// Pass an object
option = {
videoBitrate: 1500,
screen: {
audio: false,
video: {
quality: 4,
frameRate: 15,
width: 1280,
height: 720
}
}
}
zg.createZegoStream(option)-
custom
When using third-party source data, set the video bitrate through the "bitrate" parameter in the "custom" object. The range is 0-10240, and the default value is "800".
const el = document.querySelector("video") let option = { videoBitrate: 800, custom: { video: { source: el // source can be <video> or <audio> media object or MediaStream }, audio: { source: el // source can be <video> or <audio> media object or MediaStream } } } zg.createZegoStream(option)
Modify Published Stream Video Attribute Configuration
Developers can call the setVideoConfig interface to set the quality parameters of the published video stream.
setVideoConfig(localStream, {
width: 320,
height: 240,
frameRate: 15,
maxBitrate: 300
})- The setVideoConfig interface supports dynamically modifying the quality parameters of the published video stream.
- The setVideoConfig interface does not support modifying the attribute configuration of the captured third-party video.
- The setVideoConfig interface only supports browsers of Chrome 63 or above, and Safari 11 or above.
- When calling the setVideoConfig interface to modify the resolution, you can modify it to a value lower than the current resolution; if you need to modify it to a value higher than the current resolution, you can only adjust it to the best resolution captured by the camera (not the maximum resolution).
- When calling the setVideoConfig interface to modify the frame rate and resolution, the known issues are as follows:
- Safari 13 and below versions do not take effect for frame rate settings.
- Safari 11 and below versions only support specific resolutions.
- iOS Safari cannot use lower resolutions with H.264 encoding.
- Firefox only supports video frame rate of 30 fps.
How to Choose Video Resolution/Frame Rate/Bitrate
In Usage Steps, we have already explained how to set parameters such as resolution, frame rate, and bitrate through SDK interfaces. Usually, the choice of video parameters should be determined according to the actual situation. When developers develop their own audio and video applications, if they are not sure what resolution, frame rate, and bitrate to use, please refer to the following recommended values.
Resolution/Frame Rate/Bitrate
Resolution
The width and height in the resolution parameters represent the number of horizontal pixels and vertical pixels respectively. The higher the number of pixels per unit length, the finer the picture.
When choosing the resolution, developers can choose the video resolution according to the size of the video window (i.e., the width and height of the <video> tag). If the video window is small, low resolution is recommended; if the video window is large, high resolution is recommended.
The SDK presets the resolutions of three video quality parameters. Developers can refer to the following common resolution recommendation table for custom settings according to their own product requirements for resolution and screen ratio.
The following are resolutions for PC widescreen. Mobile and PC have different understandings of video width and height. The two are exactly opposite. The same resolution is landscape on PC and portrait on mobile.
| Clarity/Ratio | 16:9 | 4:3 | 1:1 | SDK Preset Value |
|---|---|---|---|---|
| Extremely Low | 160 × 90 | 160 × 120 | 120 × 120 | - |
| Low | 320 × 180 | 320 × 240 | 240 × 240 | 320 × 240 |
| Standard | 640 × 360 | 640 × 480 | 480 × 480 | 640 × 480 |
| 720p | 1280 × 720 | 960 × 720 | 720 × 720 | 1280 × 720 |
| 1080p | 1920 × 1080 | 1440 × 1080 | 1080 × 1080 | - |
Frame Rate
Frame rate indicates how many frames of pictures are coded per second. The higher the frame rate, the smoother the picture. The SDK preset recommended values include 5, 15, 20, etc. Developers can set as needed.
Bitrate
Bitrate refers to the amount of data used by a video file per unit time. The setting of the bitrate parameter is mainly used to control bandwidth pressure and the resource consumption of encoding and decoding.
Relationship Between Resolution/Frame Rate/Bitrate
The bitrate is approximately equal to the frame rate multiplied by the amount of data per frame. Therefore, the higher the frame rate and resolution, the higher the transmission bitrate.
When the actual transmission bitrate is low due to poor network, device and browser limitations, or low target bitrate parameters, the real-time frame rate and resolution will fluctuate, but the frame rate will be prioritized over the resolution.
Therefore, if developers do not have high requirements for picture smoothness, it is recommended to maintain picture clarity by setting a low frame rate.
There is a common misconception here that the higher the bitrate, the better. In practical applications, a higher bitrate requires a higher resolution and frame rate to match. For example, for a resolution of 320 × 240 and a bitrate of 1000 kbps, an excessively high bitrate will occupy network bandwidth and video decoding resources, causing waste.