Set the Video Profile (Web SDK 3.x)

Introduction

You can set the video profile, either before or after a user joins a channel, for the user to enjoy better video quality during a video call or interactive live streaming.

The Agora Web SDK provides two methods to set the video profile: setVideoProfile and setVideoEncoderConfiguration. You can choose either one according to your video scenario. The difference between these two methods is as follows:

• setVideoEncoderConfiguration: You can set each parameter of the video profile.
• setVideoProfile: You can choose one profile, which includes a fixed set of parameters.

Implementation

Before setting the video profile, ensure that you have implemented the basic real-time communication functions in your project. For details, see Start a Video Call or Start a Live Interactive Video Streaming.

After creating a stream object, you can call the setVideoProfile or setVideoEncoderConfiguration method to set the video resolution, frame rate, birtate and orientation mode.

API call sequence

Refer to the following diagram to set the video profile in your project:

Note:

• If you prefer video smoothness to sharpness, use setVideoProfile to set the video resolution and Agora self-adapts the video bitrate according to the network condition. If you prefer video sharpness to smoothness, use setVideoEncoderConfiguration, and set min in bitrate as 0.4 - 0.5 times the bitrate value in the video profile table.

• The setVideoProfile method is usually called before Stream.init. From v2.7, you can also call this method after Stream.init to change the video encoding profile.

• The setVideoEncoderConfiguration method can be called before or after Stream.init, but has the following known limitations:

  • This method works on Chrome 63 or later and is not fully functional on other. Known issues are as follows:

    • The frame rate setting does not take effect on Safari 12 or earlier.
    • Safari 11 or earlier only supports specific resolutions.

  • The parameters specified in this method are ideal values under ideal network conditions. .

  • The actual resolution, frame rate, and bitrate depend on the device. See MediaStreamTrack.applyConstraints() for more information.

Sample code

// Set the video profile with the setVideoEncoderConfiguration method.
stream.setVideoEncoderConfiguration({
  // The video resolution.
  resolution: {
    width: 640,
    height: 480
  },
  // The video frame rate (fps). We recommend setting it as 15. Do not set it to a value greater than 30.
  frameRate: {
    min: 15,
    max: 30
  },
  // The video bitrate (Kbps). Refer to the video profile table below to set this parameter.
  bitrate: {
    min: 1000,
    max: 5000
  }
});

// Set the video profile with the setVideoProfile` method.
// Sets the video profile as 480p_3, which means a resolution of 480 x 480, a frame rate of 15, and a bitrate of 400.
localStream.setVideoProfile("480p_3");
});

API Reference

• setVideoEncoderConfiguration
• setVideoProfile

Considerations

• Supported resolutions vary from browser to browser. See video profile and supported Browsers for details.
• Due to the limitations of some devices and browsers, the resolution you set may fail to take effect and be adjusted by the browser. In this case, your charges will be calculated based on the actual resolution.
• Whether the 1080 resolution or above can be supported depends on the device. If the device cannot support 1080p, the frame rate will be lower than the set value.
• The Safari browser has a fixed video frame rate of 30 fps and does not support customization.
• Changing the video profile after Stream.init only works on Chrome 63 or later and Safari 11 or later. On some iOS devices, when you update the video profile after Stream.init, black bars might appear around your video.
• Do not call these two methods when publishing streams.

Recommended video profiles

Video profiles vary from case to case. For example, in a one-to-one online class, the video windows of the teacher and student are both large, which requires higher resolutions, frame rates, and bitrates. While in a one-to-four online class, the video windows of the teacher and students are smaller, so lower resolutions, frame rates, and bitrates are used to maintan the bandwidth.

We recommend the following profiles for different scenarios:

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

If you want to customize the video parameters with the setVideoEncoderConfiguration method, refer to the table below to set the parameters: