Custom video sources and backgrounds

This article explains how to use a custom video source in calls and conferences.

Custom video source API allows you to send custom video to a call or a conference from video sources managed on the application side. It gives the possibility to implement such functionality as camera filters, background blur, video background replacement, and any kind of the video preprocessing, using 3rd party libraries. It is important to consider that the application is responsible for the management of all resources for video processing including their proper deallocation.

Configure the SDK

Before the SDK is initialized, it is required to create a WebRTC EglBase instance that holds EGL state and shared configuration.

Android SDK v2

Create an EglBase instance via the EglBase.create() API, and add it into ClientConfig before calling Voximplant.getClientInstance().

1
val eglBase = EglBase.create()
2
val clientConfig = ClientConfig()
3
clientConfig.eglBase = eglBase
4
val client = Voximplant.getClientInstance(
5
    /* executor = */ Executors.newSingleThreadExecutor(),
6
    /* context = */ applicationContext,
7
    /* clientConfig = */ clientConfig,
8
)

Android SDK v3

The EglBase instance should be created and set to the VICalls.eglBase property before the calls module is initialized using the VICalls.initialize API.

1
val eglBase = EglBase.create()
2
VICalls.eglBase = eglBase
3
VICalls.initialize()

Set up a custom video source

Custom video source takes the video frames from a SurfaceTexture into the application renders them. The WebRTC SurfaceTextureHelper class provides API that creates a SurfaceTexture and allows the SDK to convert a texture frame into a required format to send the frame to a call or a conference. SurfaceTextureHelper should be created via an EglBase instance that the SDK has been configured with. It is also required to configure the SurfaceTexture size according to the video resolution.

1
val surfaceTextureHelper: SurfaceTextureHelper? = SurfaceTextureHelper.create(
2
    "threadName",
3
    eglBase.eglBaseContext,
4
)
5
surfaceTextureHelper!!.setTextureSize(frameWidth, frameHeight)

Android SDK v2

ICustomVideoSource interface represents the custom video source. Create it via the Voximplant.getCustomVideoSource API and configure it with the SurfaceTextureHelper instance via the ICustomVideoSource.setSurfaceTextureHelper API.

Subscribe to custom video source events to handle when the SDK is ready to consume the video frames.

1
val customVideoSource = Voximplant.getCustomVideoSource()
2
customVideoSource.setSurfaceTextureHelper(surfaceTextureHelper)
3
customVideoSource.setCustomVideoSourceListener(object : ICustomVideoSourceListener {
4
    override fun onStarted() {
5
        // start rendering to the surfaceTextureHelper.surfaceTexture
6
    }
7
8
    override fun onStopped() {
9
        // stop rendering to the surfaceTextureHelper.surfaceTexture
10
    }
11
})

Android SDK v3

The CustomVideoSource class represents the custom video source. Create its instance and set it up with the SurfaceTextureHelper instance. Use the CustomVideoSource.addListener API to subscribe for the custom video source events.

1
val customVideoSource = CustomVideoSource()
2
customVideoSource.surfaceTextureHelper = surfaceTextureHelper
3
customVideoSource.addListener(object : VideoSource.EventsListener {
4
        override fun onStart() {
5
            // start rendering to the surfaceTextureHelper.surfaceTexture
6
        }
7
        override fun onStop(reason: VideoSource.StopReason) {
8
            // stop rendering to the surfaceTextureHelper.surfaceTexture
9
        }
10
        override fun onError(error: VideoSource.Error) {}
11
    }
12
)

Use the custom video source in a call

Android SDK v2

Use the Call.useCustomVideoSource API to make the SDK use the provided custom video source instead of camera device.

1
val callSettings = CallSettings()
2
callSettings.videoFlags = VideoFlags(true, true)
3
val call: ICall? = client.call(user, callSettings)
4
call!!.useCustomVideoSource(customVideoSource)
5
try {
6
    call!!.start()
7
} catch (callException: CallException) {
8
    // handle error
9
}

Android SDK v3

Create a LocalVideoStream instance with the custom video source and set it to the call or conference settings.

1
val localVideoStream = LocalVideoStream(customVideoSource)
2
val callSettings = CallSettings()
3
callSettings.localVideoStream = localVideoStream
4
callSettings.receiveVideo = true
5
val call: Call? = VICalls.createCall(
6
    number = "number_to_call",
7
    callSettings = callSettings,
8
)
9
try {
10
    call!!.start()
11
} catch (callException: CallException) {
12
    // handle error
13
}

See also

• Voximplant DeepAR video call GitHub demo