Common Video Configuration
Introduction
During video calls or live streaming, developers can specify related configurations for publishing and playing stream videos 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 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, 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 appropriate mirror mode and view mode allows developers to provide personalized video display modes.
Download Sample Source Code
Please refer to Download Sample Source Code to obtain the source code.
For related source code, please check the files in the "/ZegoExpressExample/Examples/CommonFeatures/CommonVideoConfig" directory.
Prerequisites
Before setting video configurations, ensure that:
- A project has been created in the ZEGOCLOUD Console, and valid AppID and AppSign have been obtained. For details, please refer to Console - Project Information.
- ZEGO Express SDK has been integrated into the project, and basic audio and video streaming functionality has been implemented. For details, please refer to Quick Start - Integration and Quick Start - Implementation Process.
Usage Steps
1 Modify Video Configuration
Modify video configuration by calling the setVideoConfig interface. Users can either customize parameters or use preset values for settings.
Relevant video configurations need to be set before publishing stream (startPublishingStream) or preview (startPreview). After publishing stream, only encoding resolution and bitrate modifications are supported.
Custom Parameter Settings
Call the setVideoConfig interface 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 no special settings are made, the SDK will automatically apply resolution, bitrate, and frame rate suitable for the selected scenario based on the selected scenario to obtain the best experience effect. For details, please refer to Scenario-based Audio and Video Configuration.
If the playing stream end needs to play 60-frame streams, you need to contact technical support. For details, please refer to Does ZEGO Express SDK support pulling 60-frame streams?
Taking setting video capture resolution to 360p, encoding resolution to 360p, bitrate to 600 kbps, and frame rate to 15 fps as an example:
// Need to set relevant video configurations before preview (startPreview) and publishing stream (startPublishingStream)
ZegoVideoConfig videoConfig;
videoConfig.captureHeight = 360;
videoConfig.captureWidth = 640;
videoConfig.encodeHeight = 360;
videoConfig.encodeWidth = 640;
videoConfig.fps = 15
videoConfig.bitrate = 600;
// Set video configuration
ZegoExpressEngine::getEngine()->setVideoConfig(videoConfig);The width and height resolution on mobile devices is opposite to that on PC. For example, the resolution of 360p on mobile devices is 360 × 640, while the resolution of 360p on PC is 640 × 360.
Using Preset Values
In addition to custom setting parameters, 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) |
|---|---|---|---|---|
| ZEGO_VIDEO_CONFIG_PRESET_180P | 320 × 180 | 320 × 180 | 15 | 300 |
| ZEGO_VIDEO_CONFIG_PRESET_270P | 480 × 270 | 480 × 270 | 15 | 400 |
| ZEGO_VIDEO_CONFIG_PRESET_360P | 640 × 360 | 640 × 360 | 15 | 600 |
| ZEGO_VIDEO_CONFIG_PRESET_540P | 960 × 540 | 960 × 540 | 15 | 1200 |
| ZEGO_VIDEO_CONFIG_PRESET_720P | 1280 × 720 | 1280 × 720 | 15 | 1500 |
| ZEGO_VIDEO_CONFIG_PRESET_1080P | 1920 × 1080 | 1920 × 1080 | 15 | 3000 |
Example code when calling the setVideoConfig interface to use preset values:
// Use preset values for video settings
ZegoVideoConfig vConfig(ZEGO_VIDEO_CONFIG_PRESET_360P);
engine->setVideoConfig(vConfig);2 Modify Video View Mode
Before setting the video view mode, you need to stop preview or playing stream first, otherwise it cannot take effect.
By modifying the "viewMode" parameter of the view object ZegoCanvas, you can modify the view mode of the video. Currently, the following three video rendering fill modes are supported:
| Enumeration Value | Description |
|---|---|
| ZEGO_VIEW_MODE_ASPECT_FIT | Aspect ratio scaling, there may be black borders. |
| ZEGO_VIEW_MODE_ASPECT_FILL | Aspect ratio scaling fills the entire View, some parts may be cropped. |
| ZEGO_VIEW_MODE_SCALE_TO_FILL | Fills the entire View, the image may be stretched. |
The effects of the three video rendering fill modes are shown in the figure:
- The view resolution shown in the figure above is 320 × 390 (width × height), and the video resolution is 340 × 340 (width × height).
- In the figure above, the original video size length equals width, and the view size length is greater than width. Therefore, in the "ZEGO_VIEW_MODE_ASPECT_FIT" rendering mode, black borders appear on the top and bottom of the video; if the view size width is greater than length at this time, then in the "ZEGO_VIEW_MODE_ASPECT_FIT" rendering mode, black borders will appear on the left and right sides of the video.
Taking setting the preview view mode to "ZEGO_VIEW_MODE_ASPECT_FIT" and starting preview as an example:
// winId is the video preview window handle
ZegoCanvas previewCanvas(ZegoView(winId));
// Set view mode to ZEGO_VIEW_MODE_ASPECT_FIT
previewCanvas.viewMode = ZEGO_VIEW_MODE_ASPECT_FIT;
// Start preview
engine->startPreview(&previewCanvas);3 Set Mirror Mode
This function can be set before or after publishing stream, and takes effect immediately after setting.
Before publishing stream or after stopping publishing stream, you can set whether the local preview video and the published video enable mirror mode by calling setVideoMirrorMode. Currently, the following four mirror modes are supported:
| Enumeration Value | Description |
|---|---|
| ZEGO_VIDEO_MIRROR_MODE_NO_MIRROR | Neither the local preview nor the video seen by the playing stream end is a mirrored image. |
| ZEGO_VIDEO_MIRROR_MODE_ONLY_PREVIEW_MIRROR | Only the local preview is a mirrored image. This mode is used by default. |
| ZEGO_VIDEO_MIRROR_MODE_ONLY_PUBLISH_MIRROR | Only the video seen by the playing stream end is a mirrored image. |
| ZEGO_VIDEO_MIRROR_MODE_BOTH_MIRROR | Both the local preview and the video seen by the playing stream end are mirrored images. |
The effects of the four mirror modes are as follows:
Taking setting the playing stream end to mirror and local preview not to mirror as an example:
// Set mirror mode so that only the video seen by the playing stream end is a mirrored image
engine->setVideoMirrorMode(ZEGO_VIDEO_MIRROR_MODE_ONLY_PUBLISH_MIRROR);