Skip to content
Add Custom Backgrounds to your Live Video Calling application using the Agora Android UIKit featured

Add Custom Backgrounds to your Live Video Calling application using the Agora Android UIKit

By Author: Rishav Naskar In Developer

Creating a video streaming app is amazingly easy with the Agora SDK and the Agora UIKit. Moreover, Agora has many features that enhance video call quality and convenience. For example, virtual backgrounds bring life to video calls.

We can customize the background of a video call in three ways:

  • Using an image as the background
  • Applying a solid color to the background
  • Applying blur effects to the existing background

In this tutorial, you will learn how to add virtual backgrounds in Android using the Agora Android SDK and the Agora Android UIKit

Prerequisites and requirements


Step 1: If you are not integrating this into an existing project, create a new Android application in Android Studio.

Step 2: Head over to GitHub and clone the Agora UIKit GitHub repo and open the project in File Explorer.

You will find the agorauikit_android directory inside this cloned UIKit project. Copy and paste this directory into your application, at the parent level. This directory essentially contains the Agora Android UIKit and is crucial to making our extension work.

Step 3: Make sure your project-level build.gradle has the following:

allprojects {
    repositories {
        maven { url '' }
        flatDir {
            dirs 'libs'

Step 4: Head over to the project-level build.gradle.kts of the UIKit and do the following:

  1. Remove the plug-in maven if present, as it is deprecated.
  2. Remove the version code and the version name if present.

Step 5: We will add a package to either click a picture or fetch one from our device’s gallery. To do that, let’s import the Android UIKit and an image picker package in our app-level level build.gradle:

implementation 'com.github.dhaval2404:imagepicker:2.1'
implementation project(':agorauikit_android')

Step 6: We need to add the following permissions to our AndroidManifest.xml file for necessary user permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.BLUETOOTH" />

And, voila! We’re done setting up. Now, let’s dive in to some code!

Video Call UI

For our application, we won’t have to work on building the UI too much, because all that is already taken care of by the Agora Android UIKit.

Basic Video Call using Agora Android UIKit

Implementing Virtual Background

Here, we have used MainActivity.kt as the main activity used for launching our video call app

Importing necessary dependencies

import io.agora.agorauikit_android.AgoraButton
import io.agora.agorauikit_android.AgoraConnectionData
import io.agora.agorauikit_android.AgoraVideoViewer
import io.agora.agorauikit_android.requestPermissions
import io.agora.rtc.Constants
import io.agora.rtc.IRtcEngineEventHandler
import com.github.dhaval2404.imagepicker.ImagePicker

Declaring some variables

We will be needing the following three variables in our entire implementation.

  • agView : This, variable of type AgoraVideoViewer, is used to call the Android UIKIT without which the video call would not be possible
  • tag: This String is used for logging relevant data. We can choose to ignore this as long as we make the respective changes while logging data if necessary
  • virtualBackgroundToggle: This Boolean is used to turn the virtual background effect on/off and is absolutely crucial in this implementation

We can add these in Mainactivity.kt in the following manner:

private var agView: AgoraVideoViewer? = null
private val tag = "VirtualBackground"
private var virtualBackgroundToggle = false

Joining the video call with Virtual Background

The method joinCall() has been used to implement Virtual Backgrounds. Check the Video Call UI above for your reference.

Virtual Backgrounds automatically detect any subjects in the video call and doesn’t overlap with any of them. These come in 3 different ways in Agora’s Android SDK

  • Virtual Background Image: We can fetch any image from the phone’s gallery or camera using any available package and add that as a background to our video call.
  • Virtual Background Color: We can add any color in it’s hex form as our background.
  • Virtual Background Blur: We can add an additional blur effect our existing background in three levels: Low, Medium and High.

It’s crucial to remember to enable only one of the above Virtual Backgrounds at a time. In the above gist, I have used Virtual Background Image, as an example. We can enable any of the other two while the commenting out the rest.

Toggle Virtual Background

We are using an Agora Button to enable/disable the Virtual Background Effect in the Android UIKIT.

Applying Virtual Background Image

We will apply Virtual Background Image in the following steps:

  • Fetch image from Gallery/Camera using a third-party package by launching appropriate intents
  • Enable the Virtual Background Image when the Activity returns a result
  • The image chosen must match these specifications

Applying Virtual Background Color

We can use any hex color for Virtual Background which matches these specifications.

Applying Virtual Background Blur

We can apply three types of Blur Levels: Low, Medium and High

Enabling Virtual Background

Finally, we need to enable the Virtual Background using Agora’s Android UIKIT and Android SDK. Here, we will implement the enableVirtualBackground() method which you might have found above.

Disabling Virtual Background

This is where we will simply disable the Virtual Background in just one line of code! All thanks for Agora’s amazing Android UIKIT and Android SDK


We now have a video call app with cool Virtual Backgrounds! We should be able to run the app successfully in our Android application.

There are a ton of other features which are all very simple to implement. You can check them out here.


You can try out this app by following the GitHub link. After cloning the repo, just run the app on a physical Android device to test the application.

Other Resources

To learn more about the Agora Android SDK and other use cases, see the developer guide here.

You can also have a look at the complete documentation for the functions discussed above and many more here.

And I invite you to join the Developer Slack community.