Common Video Configuration
Feature Overview
In video calls or live streaming, developers can specify publish stream and play stream video related configurations 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: Refers to the image resolution provided by capture devices such as cameras.
- Encoding resolution: Refers to the resolution of the image after encoding processing.
- Bitrate: Refers to 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 appropriate mirror mode and view mode allows developers to provide personalized video display modes.
Example Source Code Download
Please refer to Download Example Source Code to get the source code.
For related source code, please check the files in the "/ZegoExpressExample/CommonFeatures/src/main/java/im/zego/commonvideoconfig" directory.
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 in your 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
Modify video configurations by calling the setVideoConfig interface. Users can either customize parameters or use preset values for settings.
You need to set relevant 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 publish 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 play stream end needs to play 60-frame streams, you need to 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 relevant video configurations before preview (startPreview) and publishing stream (startPublishingStream)
ZegoVideoConfig 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.getEngine().setVideoConfig(videoConfig);The width and height resolutions on mobile are opposite to those 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 for Settings
You can also use the preset combination values provided by ZEGO Express SDK to modify video configurations. 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 when calling the setVideoConfig interface using preset values:
// Use presets for video settings
ZegoVideoConfig videoConfig = new ZegoVideoConfig(ZegoVideoConfigPreset.PRESET_1080P);
ZegoExpressEngine.getEngine().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 will not take effect.
By modifying the "viewMode" parameter of the view object ZegoCanvas, you can modify the view mode of the video. Currently supports three video rendering fill modes:
| Enumeration Value | Description |
|---|---|
| ASPECT_FIT | Proportional scaling, there may be black borders. |
| ASPECT_FILL | Proportional scaling to fill the entire View, some parts may be cropped. |
| SCALE_TO_FILL | 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 size is equal to the width, and the height of the view size is greater than the width. Therefore, in the "ASPECT_FIT" rendering mode, black borders appear above and below the video; if the view size width is greater than the height at this time, in the "ASPECT_FIT" rendering mode, black borders will appear on the left and right of the video.
Taking setting the preview view mode to "ASPECT_FIT" and starting preview as an example:
// preview is the "SurfaceView/TextureView/SurfaceTexture" object on the UI interface
previewCanvas = new ZegoCanvas(preview);
// Set view mode to ASPECT_FIT
previewCanvas.viewMode = ZegoViewMode.ASPECT_FIT;
// Start preview
engine.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 the local preview video and the published video enable mirror mode. Currently supports the following four mirror modes:
| Enumeration Value | Description |
|---|---|
| NO_MIRROR | Neither the local preview nor the video seen by the play stream end is a mirror image. |
| ONLY_PREVIEW_MIRROR | Only the local preview is a mirror image. This mode is used by default. |
| ONLY_PUBLISH_MIRROR | Only the video seen by the play stream end is a mirror image. |
| BOTH_MIRROR | Both the local preview and the video seen by the play stream end are mirror images. |
The effects of the four mirror modes are as follows:
Taking setting the play stream end mirror display and setting the local preview non-mirror display as an example:
// Set mirror mode to only the video seen by the play stream end is a mirror image
engine.setVideoMirrorMode(ZegoVideoMirrorMode.ONLY_PUBLISH_MIRROR);