Adding Banuba SDK to your project

iOS

CocoaPods

CocoaPods packages

To start using Banuba SDK with CocoaPods, add a custom repository and desired packages to your Podfile:

Podfile

loading...

Then install pods:

pod install --repo-update

See banuba-sdk-podspecs repo for the list of all available packages and versions.

The complete example, configured for CocoaPods usage, can be found in our Objective-C quickstart example.

Swift Package Manager

SPM packages

Banuba SDK provides Swift Package Manager packages in the custom repositories.

Add Banuba SDK packages, to your Xcode project:

1. File > Add Package Dependencies...
2. Search for the package, for example https://github.com/sdk-banuba/BNBSdkApi
3. Press the Add Package button. After verifying the package, press Add Package again.

See the sdk-banuba repositories for the list of all available packages and versions.

The complete example, configured for SPM usage, can be found in our Beauty-iOS quickstart example.

How to choose required packages

warning

Only use the packages with the same version! Packages with different versions (even minor) may conflict or work incorrectly with each other.

tip

If feature or effect works incorrect, see application logs, to figure out which package is missed.

Add packages depends on the specific features or effects, which your app will use. It is your responsibility to include everything required for the desired behaviour.
See detailed packages description in the table below.

Example of the packages set for Face Tracking and Background Separation:

• BNBSdkApi
• BNBFaceTracker
• BNBBackground

See detailed packages description in the table below.

List of all available packages

Package name	Description
BNBSdkApi	platform-specific API, like Player, Input, Output, etc
BNBSdkCore	provides the functionality of the native EffectPlayer.
BNBEffectPlayer	contains the necessary shaders, used by sdk_core package and provides the following features: math utilities, texture utilities, morphing, beautification, etc.
BNBScripting	includes the basic functionality used by the effect api, see Effects.
BNBFaceTracker	package consists of neural network models used to track face and its features: lips, eyes, etc. Include it whenever you deal with tracking. See more about Face Tracking.
BNBLips	provides neural network models for lips segmentation. See more about Lips Segmentation.
BNBHair	provides neural network models for hair segmentation. See more about Hair Segmentation.
BNBHands	provides neural network models for hand, nail, and finger segmentation.
BNBOcclusion	provides the occlusion neural network. It is used to detect face collisions with different objects in the screen.
BNBEyes	provides neural network models for eyes segmentation. See more about Eye Segmentation.
BNBSkin	provides neural network models for skin segmentation. See more about Skin Segmentation.
BNBBackground	provides neural network models for background separation. See more about Background Separation.
BNBBody	provides neural network model to recognize the human body in full and separate it from the background in images and videos.
BNBAcneEyebagsRemoval	provides neural network models for acne removal and eye bag removal.
BNBNeck	provides neural network models for neck segmentation.
BNBResources	includes all the resources of the all packages. Use it when you don't care about the size or you need all the features!
BNBPoseEstimation	private
BanubaSdk	depends on the all the packages for the operation of all available features. Use it when you don't care about the size or you need all the features!

Android

Packages

Maven packages are published to the GitHub Packages Gradle registry.

To start using Banuba SDK from GitHub Packages, add a custom maven repo to your build.gradle.kts:

build.gradle.kts

loading...

important

Authentication is required in any case (regardless of read-only/download-only access), so a username and a password (GitHub token) with read-only packages access are required. You may use the username and password provided in our examples (and here) or create your own. Our samples always contains valid credentials, so please refer to it for an up-to-date token.

Refer to our GitHub repository to find the list of all available packages and their versions.

How to choose required packages

warning

Use only the packages with the same version! Packages with different versions (even minor) may conflict or work incorrectly with each other.

tip

If feature or effect works incorrect, see application logs, to figure out which package is missed.

Add packages depends on the specific features or effects, which your app will use. It is your responsibility to include everything required for the desired behaviour.
See detailed packages description in the table below.

build.gradle.kts

loading...

List of all available packages

Package name	Description
com.banuba.sdk.sdk_api	platform-specific APIs, like Player, Input, Output, etc.
com.banuba.sdk.sdk_core	provides the functionality of the native EffectPlayer.
com.banuba.sdk.effect_player	contains the necessary shaders, used by sdk_core package and provides the following features: math utilities, texture utilities, morphing, beautification, etc.
com.banuba.sdk.scripting	includes the basic functionality used by the effect api, see Effects.
com.banuba.sdk.face_tracker	consists of neural network models used to track a face and its features: lips, eyes, etc. Include it whenever you deal with tracking. See more about FRX.
com.banuba.sdk.lips	provides neural network models for lips segmentation. See more about Lips Segmentation.
com.banuba.sdk.hair	provides neural network models for hair segmentation. See more about Hair Segmentation.
com.banuba.sdk.hands	provides neural network models for hand, nail, and finger segmentation.
com.banuba.sdk.occlusion	provides the occlusion neural network. It is used to detect face collisions with different objects in the screen.
com.banuba.sdk.eyes	provides neural network models for eyes segmentation. See more about Eye Segmentation.
com.banuba.sdk.skin	provides neural network models for skin segmentation. See more about Skin Segmentation.
com.banuba.sdk.background	provides neural network models for background separation. See more about Background Separation.
com.banuba.sdk.body	provides neural network model to recognize the human body in full and separate it from the background in images and videos.
com.banuba.sdk.acne_eyebags_removal	provides neural network models for acne removal and eye bag removal.
com.banuba.sdk.neck	provides neural network models for neck segmentation.
com.banuba.sdk.banuba_sdk_resources	includes all the resources of the all packages. Use it when you don't care about the size or you need all the features!
com.banuba.sdk.pose_estimation	private
com.banuba.sdk.banuba_sdk	depends on the all the packages for the operation of all available features. Use it when you don't care about the size or you need all the features!

Web

NPM Package

Banuba WebAR is delivered as an NPM package, which includes executables (.js, .wasm, .simd.wasm) and resources modules (modules/*.zip).

npm i @banuba/webar

Resources Modules

Module name	Description
background.zip	provides neural network models for background separation. See more about Background Separation.
body.zip	provides neural network model to recognize the human body in full and separate it from the background in images and videos.
eyes.zip	provides neural network models for eyes segmentation. See more about Eye Segmentation.
face_tracker.zip	provides neural network models used to track face and its features: lips, eyes, etc. Include it whenever you deal with tracking. See more about FRX.
face_tracker_lite.zip	lightweight replacement for face_tracker.zip
hair.zip	provides neural network models for hair segmentation. See more about Hair Segmentation.
hands.zip	provides neural network models for hand, nail, and finger segmentation.
lips.zip	provides neural network models for lips segmentation. See more about Lips Segmentation.
skin.zip	provides neural network models for skin segmentation. See more about Skin Segmentation.
makeup.zip	provides prefabs for makeup application. See more about Makeup.

Bundlers

Banuba WebAR depends on BanubaSDK.data and BanubaSDK.wasm (or BanubaSDK.simd.wasm if you are targeting SIMD) files. By default the SDK expects these files to be accessible from the application root i.e. by the /BanubaSDK.data, /BanubaSDK.wasm /BanubaSDK.simd.wasm links. It must be taken into consideration when working with application bundlers like Vite, Rollup or Webpack.

Generally speaking one should be able to put BanubaSDK.data, BanubaSDK.wasm and BanubaSDK.simd.wasm files into the application assets folder (usually public/) and get the SDK loading these files properly.

But you may want to place the files somewhere else, that case the locateFile property of the Player.create() method should help you to set-up SDK properly.

Vite

Vite

import { Player, Module /* ... */ } from "@banuba/webar"
// vite uses special ?url syntax to import files as URLs
import data from "@banuba/webar/BanubaSDK.data?url"
import wasm from "@banuba/webar/BanubaSDK.wasm?url"
import simd from "@banuba/webar/BanubaSDK.simd.wasm?url"

import FaceTracker from "@banuba/webar/face_tracker.zip?url"
import Background from "@banuba/webar/background.zip?url"

// ...

const player = await Player.create({
  clientToken: "xxx-xxx-xxx",
  // point BanubaSDK where to find these vital files
  locateFile: {
    "BanubaSDK.data": data,
    "BanubaSDK.wasm": wasm,
    "BanubaSDK.simd.wasm": simd,
  },
})

await player.addModule(new Module(FaceTracker), new Module(Background))

// ...

tip

See Vite Explicit URL imports docs for details.

Rollup

Rollup

import { Player, Module /* ... */ } from "@banuba/webar"
// you need to set-up @rollup/plugin-url for the import syntax to work
import data from "@banuba/webar/BanubaSDK.data"
import wasm from "@banuba/webar/BanubaSDK.wasm"
import simd from "@banuba/webar/BanubaSDK.simd.wasm"

import FaceTracker from "@banuba/webar/face_tracker.zip"
import Background from "@banuba/webar/background.zip"

// ...

const player = await Player.create({
  clientToken: "xxx-xxx-xxx",
  // point BanubaSDK where to find these vital files
  locateFile: {
    "BanubaSDK.data": data,
    "BanubaSDK.wasm": wasm,
    "BanubaSDK.simd.wasm": simd,
  },
})

await player.addModule(new Module(FaceTracker), new Module(Background))

// ...

tip

See @rollup/plugin-url docs for details.

Webpack

Webpack

Depending on the version of Webpack used, you may have to add following rule to the module.rules section of the webpack.config.js:

module.exports = {
  module: {
    rules: [
      // ...
      {
        test: /\.wasm$/,
        type: 'javascript/auto',
        loader: 'file-loader',
      },
      // ...
    ],
    },
  },
}

Now import of .wasm files as URLs should work properly:

import { Player, Module /* ... */ } from "@banuba/webar"
import data from "@banuba/webar/BanubaSDK.data"
import wasm from "@banuba/webar/BanubaSDK.wasm"
import simd from "@banuba/webar/BanubaSDK.simd.wasm"

import FaceTracker from "@banuba/webar/face_tracker.zip"
import Background from "@banuba/webar/background.zip"

// ...

const player = await Player.create({
  clientToken: "xxx-xxx-xxx",
  // point BanubaSDK where to find these vital files
  locateFile: {
    "BanubaSDK.data": data,
    "BanubaSDK.wasm": wasm,
    "BanubaSDK.simd.wasm": simd,
  },
})

await player.addModule(new Module(FaceTracker), new Module(Background))

// ...

info

See the related Webpack issue for details.

Desktop

Banuba SDK for desktop platforms (i.e. Windows and MacOS) is distributed via GitHub Releases.

Release archives for Windows are packed in .zip (bnd_sdk.zip), for MacOS in .tar.gz (bnb_sdk.tar.gz).

Archives for Windows and MacOS contains identical C++ API, MacOS archive also contains Objective-C API identical to iOS. As usual, Objecive-C API is designed to be callable from Swift.

Still have questions about FaceAR SDK?

Visit our FAQ or contact our support.