Common Video Configuration
Feature Introduction
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 screen resolution 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, unit is kbps (kilobits 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 appropriate mirror mode and view mode allows developers to provide personalized video display modes.
Sample Source Code Download
Please refer to Download Sample Source Code to get the source code.
For related source code, please check the files in the "/ZegoExpressExample/Examples/CommonFeatures/CommonVideoConfig" directory.
Prerequisites
Before configuring video, 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 the ZEGO Express SDK in the project and implemented basic audio and video publishing and playing functions. For details, please refer to Quick Start - Integration and Quick Start - Implementation Flow.
Usage Steps
1 Modify video configuration
Call the setVideoConfig interface to modify video configuration. Users can customize parameters or use preset values for settings.
You need to set up related video configurations 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, please contact technical support. For details, please refer to Does ZEGO Express SDK support playing 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 up related video configurations before preview (startPreview) and publishing stream (startPublishingStream)
ZegoVideoConfig *videoConfig = [[ZegoVideoConfig alloc] init];
videoConfig.captureResolution = CGSizeMake(360, 640);
videoConfig.encodeResolution = CGSizeMake(360, 640);
videoConfig.fps = 15;
videoConfig.bitrate = 600;
[[ZegoExpressEngine sharedEngine] 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.
Use preset values
You can also use the preset combination values provided by ZEGO Express SDK to modify video configuration. The preset combination values of ZegoVideoConfigPreset are as follows:
| ZegoVideoConfigPreset | Capture Resolution （Width × Height） | Encoding Resolution （Width × Height） | Frame Rate（fps） | Bitrate（kbps） |
|---|---|---|---|---|
| PRESET_180P | 180 × 320 | 180 × 320 | 15 | 300 |
| PRESET_270P | 270 × 480 | 270 × 480 | 15 | 400 |
| PRESET_360P | 360 × 640 | 360 × 640 | 15 | 600 |
| PRESET_540P | 540 × 960 | 540 × 960 | 15 | 1200 |
| PRESET_720P | 720 × 1280 | 720 × 1280 | 15 | 1500 |
| PRESET_1080P | 1080 × 1920 | 1080 × 1920 | 15 | 3000 |
Example code for calling the setVideoConfig interface using preset values:
// Use preset for video settings
ZegoVideoConfig *config = [ZegoVideoConfig configWithPreset:ZegoVideoConfigPreet1080P];
[[ZegoExpressEngine sharedEngine] setVideoConfig:config];2 Modify video view mode
Before setting video view mode, you need to stop preview or stop playing stream first, otherwise it will not 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 | Description |
|---|---|
| ZegoViewModeAspectFit | Proportional scaling, there may be black borders. |
| ZegoViewModeAspectFill | Proportional scaling to fill the entire View, some parts may be cropped. |
| ZegoViewModeScaleToFill | Fill the entire View, the image may be stretched. |
The effects of the three video rendering fill modes are shown in the figure:
- In the figure above, the original video resolution is 300 × 300 (width × height), and the view size is 300 × 500 (width × height).
- In the figure above, the original video size height equals width, and the view size height is greater than width. Therefore, in the "ZegoViewModeAspectFit" rendering mode, black borders appear above and below the video; if the view size width is greater than height at this time, in the "ZegoViewModeAspectFit" rendering mode, black borders will appear on the left and right of the video.
Taking setting preview view mode to "ZegoViewModeAspectFit" as an example:
// remotePlayView is the view object on the UI interface
ZegoCanvas *previewCanvas = [ZegoCanvas canvasWithView:self.remotePlayView];
// Set view mode to ZegoViewModeAspectFit
previewCanvas.viewMode = ZegoViewModeAspectFit;
// Start preview
[[ZegoExpressEngine sharedEngine] startPreview:previewCanvas];3 Set mirror mode
This feature can be set before or after publishing stream, and takes effect immediately after setting.
You can call setVideoMirrorMode to set whether local preview video and published video enable mirror mode. Currently, the following four mirror modes are supported:
| Enumeration | Description |
|---|---|
| ZegoVideoMirrorModeNoMirror | Neither local preview nor playing stream end sees mirrored video. |
| ZegoVideoMirrorModeOnlyPreviewMirror | Only local preview shows mirrored video, this mode is used by default. |
| ZegoVideoMirrorModeOnlyPublishMirror | Only the video seen by the playing stream end is mirrored. |
| ZegoVideoMirrorModeBothMirror | Both local preview and playing stream end see mirrored video. |
The effects of the four mirror modes are as follows:
Taking setting playing stream end to display mirrored video and local preview to display non-mirrored video as an example:
// Set mirror mode to only the video seen by playing stream end is mirrored
[[ZegoExpressEngine sharedEngine] setVideoMirrorMode:ZegoVideoMirrorModeOnlyPublishMirror];