# Banuba AR Face Filter (/en/realtime-media/marketplace/build/add-video-and-ar-effects/banuba/android)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

This guide is provided by Banuba. Agora is planning a documentation upgrade program for all extensions on the marketplace. Please stay tuned.

By integrating Banuba Face AR SDK and Agora.io SDK you can enable augmented reality features in video calls such as face filters, face touch up filters and virtual backgrounds. You can find the integration examples below.

      
## Prerequisites

* The latest Banuba SDK archive
* [Banuba Extension files for Android](https://f.hubspotusercontent10.net/hubfs/4992313/Agora_Banuba_Extension/AgoraBanubaExtension2%28Android%29.zip)
* Banuba trial client token.

To receive a trial token or a full commercial licence from Banuba - please fill in our form on [form on banuba.com](https://www.banuba.com/face-filters-sdk) website, or contact us via [info@banuba.com](mailto\:info@banuba.com).

## Integrate Banuba Face AR extension

### Get Started

1. Make sure that you have Android **NDK** and **CMake** are installed! Project contains C++ sources, so this is required! Recommended NDK versions is 21.1.6352462, required CMake version is 3.9, 3.14 or above is recommended (Android SDK manager provides 3.18.1, it should be installed).
2. Get the latest Banuba SDK archive, [Banuba trial client token](https://www.banuba.com/facear-sdk/face-filters).
   To receive full commercial license from Banuba - please fill in our form on [form on banuba.com](https://www.banuba.com/face-filters-sdk) website, or contact us via [info@banuba.com](mailto\:info@banuba.com).
3. Copy `.aar` file from the Banuba SDK archive into `libs` dir:
   > `banuba_effect_player-release.aar` => `libs/`
4. Copy `include/bnb` directory into `libs/bnb_sdk/`:
   > `include/bnb` => `libs/bnb_sdk/bnb`
5. Get [the latest Agora RTC SDK archive](https://console.agora.io/marketplace/extension/introduce?serviceName=banuba).
6. Copy `jar` files from the Agora RTC SDK archive into `libs` dir:
   > `agora-rtc-sdk.jar` => `libs/`
7. Copy architecture folders from the Agora RTC SDK archive into `jniLibs` dir:
   > `arm64-v8a`, `armeabi-v7a` and `x86_64` => `libs/jniLibs/`
8. Copy Agora SDK headers (`*.h` files) into `libs/agora_rtc_sdk/include`:
   > `low_level_api/include` => `libs/agora_rtc_sdk/include`
9. Copy and Paste your Banuba client token into appropriate section of `app/src/main/java/com/banuba/sdk/agorapluginexample/ClientToken.kt` with " " symbols. For example: BANUBA\_CLIENT\_TOKEN = "place\_your\_token\_here"
10. Visit [agora.io](https://console.agora.io) to sign up and get token, app ID and channel ID.
11. Copy and Paste your Agora token, app ID and channel ID into appropriate section of `app/src/main/java/com/banuba/sdk/agorapluginexample/ClientToken.kt` with " " symbols. For example: AGORA\_APP\_ID = "place\_your\_token\_here"
12. Open the project in Android Studio and run the necessary target using the usual steps.

#### How to use `BanubaFiltersAgoraExtension`

Add following imports:

```kotlin
import com.banuba.agora.plugin.BanubaEffectsLoader
import com.banuba.agora.plugin.BanubaExtensionManager
import com.banuba.agora.plugin.BanubaResourceManager
import com.banuba.agora.plugin.model.ArEffect
import com.banuba.sdk.utils.ContextProvider
```

Add extension to RtcEngineConfig:

```kotlin
RtcEngineConfig().apply {
    ...
    System.loadLibrary("banuba")
    addExtension(BanubaExtensionManager.EXTENSION_NAME)
    ContextProvider.setContext(mContext)
    ...
}
```

Create and initialize BanubaResourceManager:

```kotlin
private val banubaResourceManager by lazy(LazyThreadSafetyMode.NONE) {
    BanubaResourceManager(this)
}
```

```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
    ...
    banubaResourceManager.prepare()
}
```

After those steps enable and initialize extension:

```kotlin
agoraRtc.enableExtension(
    BanubaExtensionManager.VENDOR_NAME,
    BanubaExtensionManager.VIDEO_FILTER_NAME,
    true
)
```

```kotlin
private fun initBanubaPlugin() {
    agoraRtc.setExtensionProperty(
        BanubaExtensionManager.VENDOR_NAME,
        BanubaExtensionManager.VIDEO_FILTER_NAME,
        BanubaExtensionManager.KEY_SET_RESOURCES_PATH,
        banubaResourceManager.resourcesPath
    )
    agoraRtc.setExtensionProperty(
        BanubaExtensionManager.VENDOR_NAME,
        BanubaExtensionManager.VIDEO_FILTER_NAME,
        BanubaExtensionManager.KEY_SET_EFFECTS_PATH,
        banubaResourceManager.effectsPath
    )
    agoraRtc.setExtensionProperty(
        BanubaExtensionManager.VENDOR_NAME,
        BanubaExtensionManager.VIDEO_FILTER_NAME,
        BanubaExtensionManager.KEY_SET_TOKEN,
        BANUBA_CLIENT_TOKEN
    )
}
```

To enable/disable effects use the following code:

```kotlin
private val onEffectPrepared = object : BanubaResourceManager.EffectPreparedCallback {
    override fun onPrepared(effectName: String) {
        sendEffectToFilter(effectName)
    }
}

private fun sendEffectToFilter(effect: String) {
    agoraRtc.setExtensionProperty(
        BanubaExtensionManager.VENDOR_NAME,
        BanubaExtensionManager.VIDEO_FILTER_NAME,
        BanubaExtensionManager.KEY_LOAD_EFFECT,
        effect
    )
}
```

```kotlin
banubaResourceManager.prepareEffect(Effect name, onEffectPrepared)
```

#### Effects managing

To retrieve current effects use the following code:

```kotlin
val effects: List<ArEffect> = BanubaEffectsLoader(this).loadEffects()
```

ArEffect contains following information:\
`name: String` - pass to `banubaResourceManager.prepareEffect(Effect name, onEffectPrepared)`. Also can be used to display label on the UI\
`preview: Bitmap` - can be used as preview image

To modify effects, add or remove effect folder in `app/src/main/assets/effects` directory.
By default sample contains the following effects:

1. `ElvisUnleashed`
2. `EnglandEightPieceCap`
3. `FashionHistory1940_male`
4. `MorphingHatBow`
5. `Nerd`
6. `SnapBubblesGlasses`
7. `Space`
8. `StarGlow`
9. `TitanicJack`

## Run the demo

* [Demo app (public)](https://f.hubspotusercontent10.net/hubfs/4992313/Agora_Banuba_Extension/AgoraBanubaDemoApp%28Android%29.apk)
* [Github repository](https://github.com/Banuba/agora-plugin-filters-android)