User experience in real-time engagement scenarios involving video is closely related to the quality of the video, such as its sharpness and smoothness.
Video profiles are preset configurations of resolution, frame rate, and bitrate. Developers can implement video profiles to control how video streams will appear to users under ideal network conditions. This article shows how to call the API provided by Agora to set video profiles.
Agora provides an open-source sample project on GitHub that implements setting the video profile. You can download the sample project to try it out or view the source code.
Before proceeding, ensure that you have implemented real-time audio and video functions in your project.
The Agora SDK provides the
setVideoEncoderConfiguration method to set the video profile. After you initialize the
IRtcEngine object, you can call
setVideoEncoderConfiguration either before or after joining a channel.
If you do not intend to update the video profile after joining a channel, Agora recommends calling
enableVideo, which reduces the time to render the first local video frame.
You can set the video resolution, frame rate, and bitrate with the following parameters:
dimensions: The video encoding resolution (px). The default value is 640 × 360. Generally speaking, the higher the resolution, the sharper the video. The value of this parameter does not indicate the orientation mode of the output video. For how to set the orientation mode of the output video, see Orientation mode.
frameRate: The video encoding frame rate (fps), that is, the number of frames that the SDK encodes per second. The default value is 15. Generally speaking, the higher the frame rate, the smoother the video. For scenarios with high requirements on video smoothness, You can set this parameter as 20 or 25. Agora recommends not setting
frameRate as any value beyond 30.
bitrate: The video encoding bitrate (Kbps). The default value is
STANDARD_BITRATE, that is, the standard bitrate mode. Under the standard bitrate mode, the SDK assigns a bitrate value according to the channel profile, video dimensions, and frame rate that you set.
The Agora SDK provides selections of video dimensions, frame rate, and bitrate for you to choose from. You can also customize the values according to the table below.
(width x height)
|160 x 120||15||65||130|
|120 x 120||15||50||100|
|320 x 180||15||140||280|
|180 x 180||15||100||200|
|240 x 180||15||120||240|
|320 x 240||15||200||400|
|240 x 240||15||140||280|
|424 x 240||15||220||440|
|640 x 360||15||400||800|
|360 x 360||15||260||520|
|640 x 360||30||600||1200|
|360 x 360||30||400||800|
|480 x 360||15||320||640|
|480 x 360||30||490||980|
|640 x 480||15||500||1000|
|480 x 480||15||400||800|
|640 x 480||30||750||1500|
|480 x 480||30||600||1200|
|848 x 480||15||610||1220|
|848 x 480||30||930||1860|
|640 x 480||10||400||800|
|1280 x 720||15||1130||2260|
|1280 x 720||30||1710||3420|
|960 x 720||15||910||1820|
|960 x 720||30||1380||2760|
|1920 x 1080||15||2080||4160|
|1920 x 1080||30||3150||6300|
|1920 x 1080||60||4780||6500|
The recommended video profiles vary by scenario. For example, in a one-to-one online class, the video windows of the teacher and student are both large, which calls for higher resolutions, frame rates, and bitrates. In a one-to-four online class, however, the video windows of the teacher and students are smaller, so lower resolutions, frame rates, and bitrates are used to accommodate bandwidth limitations.
The following profiles for different scenarios are recommended:
Video rotation involves the video capturer and the video player, where:
To avoid issues such as video scaling and cropping caused by video rotation, the Agora SDK provides the
orientationMode parameter in the
setVideoEncoderConfiguration method. You can use this parameter to set the video orientation mode according to your scenario to get the video you want.
The orientationMode parameter provides three modes to suit different user needs:
ADAPTIVE mode, the output video always follows the orientation of the captured video, and the receiver takes the rotation information passed on from the video encoder. This mode applies to scenarios where video orientation can be adjusted on the receiver and is usually used between Agora SDKs.
FIXED_LANDSCAPE mode, the video capturer sends the video in the landscape orientation relative to the status bar. If the captured video is in portrait mode, the video encoder crops it to fit the output. This mode applies to situations where the receiving end cannot process the rotation information.
FIXED_PORTRAIT mode, the video capturer sends out the video in the portrait orientation relative to the status bar. If the captured video is in landscape mode, the video encoder crops it to fit the output. This mode applies to situations where the receiving end cannot process the rotation information.
To optimize user experience in weak network conditions, Agora provides the
degradationPreference parameter to set how you wish to degrade the video under limited network bandwidth.
By default, the SDK does not mirror the video during encoding. You can use the
mirrorMode parameter to decide whether to mirror the video that remote users see.
If your scenario has special requirements on video sharpness or smoothness, you can also use the following parameters to set the minimum frame rate or bitrate:
minFrameRate: The minimum video frame rate (fps). You can use
MAINTAIN_QUALITYto balance the video sharpness and video smoothness under unreliable connections. When
minFrameRateis relatively low, the frame rate degrades significantly, fo the poor network conditions have limited impact on video sharpness. When
minFrameRateis relatively high, the frame rate degrades within a limited range, so the poor network conditions can have high impact on video sharpness.
minBitrate: The minimum video bitrate (Kbps). The Agora SDK automatically adjusts the encoding bitrate to adapt to the network conditions. Setting this parameter to a value greater than the default value forces the video encoder to output high-quality video images but may cause more packet loss and sacrifice video smoothness.
minBitratecan meet the requirements of most real-time scenarios. Unless you have special requirements , Agora recommends not changing these default values.
You can refer to the following code sample when setting the parameters of
// Set the video encoder configuration. // Set the video resolution as 640 × 360. VideoEncoderConfiguration (lpVideoConfig(640, 360), // Set the video frame rate as 15 fps. FRAME_RATE_FPS_15, // Set the video bitrate as 800 Kbps. 800, // Set the orientation mode as ADAPTIVE. ORIENTATION_MODE_ADAPTIVE, // Set the degradation preference as MIANTAIN_QUALITY. MAINTAIN_QUALITY ); // Set the video encoder configuration. lpAgoraEngine->setVideoEncoderConfiguration(lpVideoConfig);
setVideoEncoderConfigurationare the maximum values under ideal network conditions. The SDK adapts (most often downwards) these parameters according to the network conditions in real-time.
setVideoEncoderConfigurationaffects your bill. In case network adaptation occurs, the unit price is calculated based on the actual video dimensions. For more information, see Billing for Real-time Communication.