Set the Video Profile

Introduction

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.

Sample project

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.

Implementation

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 setVideoEncoderConfiguration before enableVideo, which reduces the time to render the first local video frame.

Resolution, frame rate and bitrate

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.

Video profile table

Recommended video profiles

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:

• One-to-one video call:
  • Resolution: 320 × 240; frame rate: 15 fps; bitrate: 200 Kbps.
  • Resolution: 640 × 360; frame rate: 15 fps; bitrate: 400 Kbps.
• One-to-many video call:
  • Resolution: 160 × 120; frame rate: 15 fps; bitrate: 65 Kbps.
  • Resolution: 320 × 180; frame rate: 15 fps; bitrate: 140 Kbps.
  • Resolution: 320 × 240; frame rate: 15 fps; bitrate: 200 Kbps.

Orientation mode

Video rotation involves the video capturer and the video player, where:

• The video capturer captures the video and outputs the relevant video information, namely, the relative position of the video and the status bar.
• The video player renders the received video and rotates the video according to the rotation information.

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, FIXED_LANDSCAPE, and FIXED_PORTRAIT.

ADAPTIVE

In the 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

In the 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

In the 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.

Degradation preference

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.

Mirror mode

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.

Minimum frame rate and bitrate

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 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, fo 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 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.

Sample code

You can refer to the following code sample when setting the parameters of setVideoEncoderConfiguration:

// 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);

Considerations

• The parameters specified in setVideoEncoderConfiguration are the maximum values under ideal network conditions. The SDK adapts (most often downwards) these parameters according to the network conditions in real-time.
• Setting parameters in setVideoEncoderConfiguration affects 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.