- Documentation
- Live Streaming
- Develop your app
- Live Streaming
- Enhance basic livestream
- Set up common livestream config
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.
Only one of the
camera
,screen
, andcustom
streams can be created at a time. To create multiple different streams, call the createZegoStream method multiple times.Although the API supports setting resolution, many devices do not support customize resolution, so we recommend you use the default values.
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.
In order to make video collection compatible with devices and browsers as much as possible, we recommend you set the width and height of the resolution to a multiple of 8 when setting the video parameter.
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 |
// 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.
Value | Frame rate (fps) | Bitrate (kbps) | Scenario |
---|---|---|---|
1 | 20 | 800 | Scenarios that require high fluency. |
2 | 15 | 1500 | Scenarios that require both fluency and definition. |
3 | 5 | 2000 | Scenarios that require high definition. |
4 | frameRate | bitrate | Customized. |
// 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
})
The following shows some known limitations of the setVideoConfig
method:
- You can't use this method to modify the video quality property of third-party captured video.
- It only supports Chrome 63 or later, Safari 11 or later.
- When using this method to modify the resolution, you can change the resolution to a value lower than the current resolution. If you need to modify the resolution to higher than the current one, the maximum resolution can only be adjusted to the best resolution (not the max resolution) of the camera.
- When using this method to modify the frame rate and resolution:
- Frame rate settings do not apply to Safari 13 and earlier.
- Safari 11 and earlier only supports specific resolutions.
- iOS Safari cannot use a lower resolution in H.264 encoding.
- Firefox only supports the video frame rate of 30 FPS.
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.
The following is the resolution of the widescreen on PC. The resolution of the portrait screen on the mobile can be switched from the width and height in the following table.
Definiton/Aspect ratio | 16:9 | 4:3 | 1:1 | SDK default value |
---|---|---|---|---|
Lowest | 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 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.
There is a common misconception that the higher the bitrate, the better. But in practice, 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, a higher bitrate will occupy network bandwidth and waste video decoding resources.
For setting the most appropriate values, see next chapter 6.3 Recommended values for common scenarios.
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.
Video definition | Resolution (width × height) | Frame rate (fps) | Bitrate (Kbps) |
---|---|---|---|
120p |
160 × 120 |
15 |
65 |
120 × 120 |
15 |
50 |
|
180p |
320 × 180 |
15 |
140 |
180 × 180 |
15 |
100 |
|
240 × 180 |
15 |
120 |
|
240p |
320 × 240 |
15 |
200 |
240 × 240 |
15 |
140 |
|
424 × 240 |
15 |
220 |
|
360p |
640 × 360 |
15 |
400 |
360 × 360 |
15 |
260 |
|
640 × 360 |
30 |
600 |
|
360 × 360 |
30 |
400 |
|
480 × 360 |
15 |
320 |
|
480 × 360 |
30 |
490 |
|
640 × 360 |
15 |
800 |
|
640 × 360 |
24 |
800 |
|
640 × 360 |
24 |
1000 |
|
480p |
640 × 480 |
15 |
500 |
640 × 480 |
30 |
1000 |
|
480 × 480 |
15 |
400 |
|
640 × 480 |
30 |
750 |
|
480 × 480 |
30 |
600 |
|
848 × 480 |
15 |
610 |
|
848 × 480 |
30 |
930 |
|
640 × 480 |
10 |
400 |
|
720p |
1280 × 720 |
15 |
1130 |
1280 × 720 |
30 |
2000 |
|
1280 × 720 |
30 |
1710 |
|
960 × 720 |
15 |
910 |
|
960 × 720 |
30 |
1380 |
|
1080p |
1920 × 1080 |
15 |
2080 |
1920 × 1080 |
30 |
3000 |
|
1920 × 1080 |
30 |
3150 |
|
1920 × 1080 |
60 |
4780 |