Custom Video Track - Android

You can pass a custom video track for a participant's video. Use it to set the video encoder config, camera and simulcast settings of the video you send to other participants.

Creating a Custom Video Track

• You can create a Video Track using createCameraVideoTrack() method of VideoSDK.
• This method can be used to create video track using different encoding parameters & camera facing mode.
• The method opens the camera, so request the CAMERA permission before you call it.

Parameters

• encoderConfig:

  • type: String
  • required: false
  • default: h720p_w1280p
  • Allowed values : h90p_w160p | h120p_w160p | h144p_w176p | h180p_w240p | h180p_w320p | h240p_w320p | h360p_w480p | h360p_w640p | h480p_w640p | h480p_w720p | h540p_w960p | h720p_w960p | h720p_w1280p | h1080p_w1440p | h1080p_w1920p
  • The encoder config to use for the video track.

note

Above mentioned encoder configurations are valid for both, landscape as well as portrait mode.

• facingMode:

  • type: FacingMode
  • required: false
  • default: FacingMode.front
  • Allowed values : FacingMode.front | FacingMode.back
  • It specifies whether to use the front or back camera for the video track.

• multiStream

  • type: Boolean
  • required: false
  • default: true
  • If true, the video is published in several quality layers (simulcast), so each participant can receive the layer that suits them. If false, a single layer is sent.

• context:

  • type: Context
  • required: true
  • Pass the Android Context for this parameter.

• videoDeviceInfo:

  • type: VideoDeviceInfo
  • required: false
  • A camera from VideoSDK.getVideoDevices(). If passed, it is used instead of facingMode.

• maxLayer:

  • type: Int
  • required: false
  • default: 3
  • The highest number of simulcast layers to publish, from 1 to 3.

• bitrateMode:

  • type: BitrateMode
  • required: false
  • default: BitrateMode.BALANCED
  • Allowed values: BitrateMode.HIGH_QUALITY | BitrateMode.BALANCED | BitrateMode.BANDWIDTH_OPTIMIZED
  • How much bitrate the encoder uses for the chosen encoderConfig.

• videoCodec:

  • type: VideoCodec
  • required: false
  • Allowed values: VideoCodec.VP8 | VideoCodec.VP9 | VideoCodec.AV1 | VideoCodec.H264
  • The codec to publish the video with. If not passed, the default codec is used. A codec other than VP8 publishes a single layer, even when multiStream is true.

note

To apply video filters from an external SDK (e.g., Banuba), use a video processor. For Banuba integration with VideoSDK, please visit Banuba Integration with VideoSDK

Returns

• CustomStreamTrack?. It is never null: if the track can't be created, the method throws VideoSDKException instead, for example 3017 when CAMERA has not been granted.
• Called on the main thread, the method returns before the camera has opened. If the camera then fails to open (for example 3023 when another app is using it), the track ends and the error goes to the track.onEnded = { error -> } handler.
• A track you have not published keeps the camera open. If you don't publish it, call track.stop() to release the camera.

Example

try {
  val videoCustomTrack: CustomStreamTrack? = VideoSDK.createCameraVideoTrack(
    encoderConfig = "h240p_w320p",
    facingMode = FacingMode.front,
    context = this,
  )
} catch (e: VideoSDKException) {
  Log.e("VideoSDK", "Video track creation failed: ${e.code} ${e.name}")
}

Using Custom Video Track

Custom Track while initializing the meeting

If you are passing webcamEnabled = true in the initMeeting of VideoSDK and want to use custom tracks from start of the meeting, you can pass custom track in the initMeeting as shown below.

override fun onCreate(savedInstanceState: Bundle?) {
    //..

    val customTracks: MutableMap<String, CustomStreamTrack> = HashMap()

    try {
      val videoCustomTrack = VideoSDK.createCameraVideoTrack(
        encoderConfig = "h240p_w320p",
        facingMode = FacingMode.back,
        multiStream = false,
        context = this,
      )
      customTracks["video"] = videoCustomTrack!!  //Key must be "video"
    } catch (e: VideoSDKException) {
      Log.e("VideoSDK", "Video track creation failed: ${e.code} ${e.name}")
    }

    // create a new meeting instance
    val meeting = VideoSDK.initMeeting(
      context = this@MainActivity,
      meetingId = meetingId,
      name = participantName,
      //MicEnabled
      micEnabled = true,
      //WebcamEnabled , If true, it will use the passed custom track to turn webcam on
      webcamEnabled = true,
      //Pass the custom tracks here
      customTracks = customTracks,
    )
}

Custom Track with enableWebcam()

To turn the webcam on with a custom track during the meeting, pass the CustomStreamTrack to the enableWebcam() method of Meeting. It is a suspend function, so call it from a coroutine.

note

enableWebcam() throws VideoSDKException with code 3054 when the webcam is already on. To switch a webcam that is on to a new track, use changeWebcam() with the track instead.

lifecycleScope.launch {
  try {
    val customStreamTrack = VideoSDK.createCameraVideoTrack(
      encoderConfig = "h240p_w320p",
      facingMode = FacingMode.back,
      context = this@MainActivity,
    )
    meeting.enableWebcam(customStreamTrack)
  } catch (e: VideoSDKException) {
    Log.e("VideoSDK", "Enable webcam failed: ${e.code} ${e.name}")
  }
}