This page shows how to call the API provided by Agora to set video profiles.
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 appear to users under ideal network conditions.
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 setVideoEncoderConfiguration
before 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. In general, the higher the resolution is, the sharper the video gets. 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. In general, the higher the frame rate is, the smoother the video gets. For scenarios with high requirements for video smoothness, you can set this parameter as 20 or 25. Agora recommends not setting frameRate
greater than 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.To achieve high video quality, you need to strike a balance between video dimensions, bitrate, and frame rate. Higher video dimensions require a higher bitrate. With a fixed bitrate, an excessively high frame rate reduces video dimensions.
The parameters specified are the maximum values under ideal network conditions. If the SDK cannot render the video using the specified parameters due to poor network conditions, lower quality settings are used.
The recommended video settings 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 settings for different scenarios are recommended:
Video rotation involves the video capturer and the video player, where the following occurs:
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: ORIENTATION_MODE_ADAPTIVE
, ORIENTATION_MODE_FIXED_LANDSCAPE
, and ORIENTATION_MODE_FIXED_PORTRAIT
.
Regardless of the mode, the relative position of the video and the status bar on both the video capturer and the player remain the same.
In the ORIENTATION_MODE_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:
If the captured video is in landscape mode, the output video is in landscape mode.
If the captured video is in portrait mode, the output video is in portrait mode.
In the ORIENTATION_MODE_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.
In the ORIENTATION_MODE_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 poor 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 use the following parameters to alter the minimum frame rate or bitrate:
minFrameRate
: The minimum video frame rate (fps). You can use minFrameRate
and MAINTAIN_QUALITY
to balance the video sharpness and video smoothness under unreliable connections. When minFrameRate
is relatively low, the frame rate degrades significantly, so the poor network conditions have limited impact on video sharpness. When minFrameRate
is 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 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.minFrameRate
and minBitrate
can meet the requirements of most real-time scenarios. Unless you have special requirements, Agora recommends not changing these default values.Before proceeding, ensure that you have implemented basic real-time functions in your project. See Start a Call or Start Interactive Live Streaming.
To set the video profile in your project, refer to the following sample code:
// Set a VideoEncoderConfiguration object.
// Set the resolution as 640 x 360.
VideoEncoderConfiguration (lpVideoConfig(640, 360),
// Set the frame rate as 15 fps.
FRAME_RATE_FPS_15,
// Set the bitrate as 800 Kbps.
800,
// Set the orientation mode as ADAPTIVE.
ORIENTATION_MODE_ADAPTIVE
// Set the degradation preference as MAINTAIN_QUALITY.
MAINTAIN_QUALITY
);
// Set the video encoder configuration.
lpAgoraEngine->setVideoEncoderConfiguration(lpVideoConfig);
This section includes in-depth information about the methods used in this page and links to related pages.
setVideoEncoderConfiguration
are the maximum values under ideal network conditions. The Agora SDK adapts these parameters (typically downwards) according to the network conditions in real-time.setVideoEncoderConfiguration
might affect your bill. If network adaptation occurs, the unit price is calculated based on the actual video dimensions. For more information, see Billing for Real-time Communication.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.
Resolution (width × height) | Frame rate (fps) | Live bitrate (Kbps) |
---|---|---|
160 × 120 | 15 | 130 |
120 × 120 | 15 | 100 |
320 × 180 | 15 | 280 |
180 × 180 | 15 | 200 |
240 × 180 | 15 | 240 |
320 × 240 | 15 | 400 |
240 × 240 | 15 | 280 |
424 × 240 | 15 | 440 |
640 × 360 | 15 | 800 |
360 × 360 | 15 | 520 |
640 × 360 | 30 | 1200 |
360 × 360 | 30 | 800 |
480 × 360 | 15 | 640 |
480 × 360 | 30 | 980 |
640 × 480 | 15 | 1000 |
480 × 480 | 15 | 800 |
640 × 480 | 30 | 1500 |
480 × 480 | 30 | 1200 |
848 × 480 | 15 | 1220 |
848 × 480 | 30 | 1860 |
640 × 480 | 10 | 800 |
1280 × 720 | 15 | 2260 |
1280 × 720 | 30 | 3420 |
960 × 720 | 15 | 1820 |
960 × 720 | 30 | 2760 |
1920 × 1080 | 15 | 4160 |
1920 × 1080 | 30 | 6300 |
1920 × 1080 | 60 | 6500 |