Common Video Configuration
Overview
During video calls or live streaming, developers can specify video-related configurations for publishing and playing streams as needed, such as video capture resolution, video encoding output resolution, video frame rate, bitrate, view mode, and mirror mode.
- 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 image provided by capture devices such as cameras.
- Encoding resolution: The resolution of the image after encoding processing.
- Bitrate: The number of bits transmitted per second, in bps (bit per second).
- Frame rate: A unit of measurement for the number of video frames displayed per unit time, measured in "frames per second" (Frame Per Second, fps).
Setting appropriate video resolution, frame rate, and bitrate can provide users with a better experience in audio and video scenarios. Choosing the right mirror mode and view mode allows developers to provide personalized video display modes.
Prerequisites
Before setting video configurations, please ensure:
- You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.
- You have integrated ZEGO Express SDK into the project and implemented basic audio and video streaming functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation.
Usage Steps
1 Modify Video Configuration
Call the setVideoConfig interface to modify video configuration. Users can either customize parameters or use preset values for configuration.
You need to set the relevant video configuration before publishing stream (startPublishingStream) or preview (startPreview). After publishing stream, only encoding resolution and bitrate modifications are supported.
Custom Parameter Settings
Call setVideoConfig to modify publishing stream video configuration. Through this interface, you can set video frame rate, bitrate, video capture resolution, and video encoding output resolution. If not set, the default video configuration is as follows:
| Configuration Item | Default Value |
|---|---|
| Resolution | 360p |
| Bitrate | 600 kbps |
| Frame rate | 15 fps |
The following example sets video capture resolution to 360p, encoding resolution to 360p, bitrate to 600 kbps, and frame rate to 15 fps:
let videoConfig = new ZegoVideoConfig();
videoConfig.captureHeight = 640;
videoConfig.captureWidth = 360;
videoConfig.encodeHeight = 640;
videoConfig.encodeWidth = 360;
videoConfig.fps = 15
videoConfig.bitrate = 600;
// Set video configuration
ZegoExpressEngine.instance().setVideoConfig(videoConfig);The width and height resolution on mobile is opposite to that on PC. For example, the resolution of 360p on mobile is 360 × 640, while the resolution of 360p on PC is 640 × 360.
Using Preset Values
You can also use the preset combination values provided by ZEGO Express SDK. The preset combination values of ZegoVideoConfigPreset are as follows:
| ZegoVideoConfigPreset | Capture Resolution （Width × Height） | Encoding Resolution （Width × Height） | Frame Rate（fps） | Bitrate（kbps） |
|---|---|---|---|---|
| Preset180P | 180 × 320 | 180 × 320 | 15 | 300 |
| Preset270P | 270 × 480 | 270 × 480 | 15 | 400 |
| Preset360P | 360 × 640 | 360 × 640 | 15 | 600 |
| Preset540P | 540 × 960 | 540 × 960 | 15 | 1200 |
| Preset720P | 720 × 1280 | 720 × 1280 | 15 | 1500 |
| Preset1080P | 1080 × 1920 | 1080 × 1920 | 15 | 3000 |
When calling the setVideoConfig interface to use preset values, the example code is as follows:
// Use presets for video settings
let videoConfig = new ZegoVideoConfig(ZegoVideoConfigPreset.Preset1080P);
ZegoExpressEngine.instance().setVideoConfig(videoConfig);2 Modify Video View Mode
Before setting the video view mode, you need to stop preview or stop playing stream first, otherwise it cannot take effect.
By modifying the "viewMode" parameter of the view object ZegoView, you can modify the view mode of the video. Currently, three video rendering fill modes are supported:
| Enumeration Value | Description |
|---|---|
| AspectFit | Aspect ratio scaling, may have black borders. |
| AspectFill | Aspect ratio scaling to fill the entire View, some parts may be cropped. |
| ScaleToFill | Fill the entire View, the image may be stretched. |
The effects of the three video rendering fill modes are shown in the figure:
- The original video resolution shown in the figure above is 300 × 300 (width × height), and the view size is 300 × 500 (width × height).
- In the figure above, the height of the original video is equal to the width, and the height of the view is greater than the width. Therefore, in the "AspectFill" rendering mode, black borders appear above and below the video. If the view width is greater than the height at this time, black borders will appear on the left and right sides of the video in the "AspectFit" rendering mode.
Taking setting the preview view mode to "AspectFit" and starting preview as an example:
let canvas = {"reactTag": findNodeHandle(this.refs.zego_preview_view), "viewMode": ZegoViewMode.AspectFit, "backgroundColor": 0};
// Start preview
ZegoExpressEngine.instance().startPreview(canvas);3 Set Mirror Mode
This function can be set before or after publishing stream, and takes effect immediately after setting.
You can call setVideoMirrorMode to set whether mirror mode is enabled for local preview video and published video. Currently, the following four mirror modes are supported:
| Enumeration Value | Description |
|---|---|
| NoMirror | Neither local preview nor the playing stream sees a mirrored image. |
| OnlyPreviewMirror | Only local preview shows a mirrored image, this mode is used by default. |
| OnlyPublishMirror | Only the playing stream sees a mirrored image. |
| BothMirror | Both local preview and the playing stream see mirrored images. |
The effects of the four mirror modes are as follows:
Taking setting the playing stream to display mirrored and local preview to display non-mirrored as an example:
// Set mirror mode so that only the playing stream sees a mirrored image
ZegoExpressEngine.instance().setVideoMirrorMode(ZegoVideoMirrorMode.OnlyPublishMirror);