Custom ScreenShare Sources - Android

To deliver high-quality livestreams, it's essential to fine-tune screen share tracks being broadcasted. Whether you’re hosting a webinar, or going live with a presentation, using custom media tracks gives you better control over stream quality and performance.

Custom Screen Share Track

A custom screen share track lets you choose the resolution and frame rate of the screen you share with hosts and viewers, whether it is sent as simulcast layers, and whether the device's audio is shared too.

How to Create Custom Screen Share Track ?

• Create the track with VideoSDK.createScreenShareVideoTrack(). Pass the consent Intent from MediaProjectionManager as data.
• You can choose the encoderConfig from h360p_30fps, h480p_15fps, h480p_30fps, h720p_5fps, h720p_15fps, h720p_30fps, h1080p_15fps and h1080p_30fps.
• createScreenShareVideoTrack() returns the track. It returns null when the user declined, or when encoderConfig is not in the list above. The second case also reports 3071 (ERROR_INVALID_CUSTOM_TRACK_CONFIG) on onError.
• The track holds the user's consent and your settings. Screen capture starts when you pass the track to enableScreenShare().

Example

// data is received from onActivityResult method.
val track = VideoSDK.createScreenShareVideoTrack(

  // This will accept the  height & FPS of video you want to capture.
  encoderConfig = "h720p_15fps", //  `h360p_30fps` | `h1080p_30fps` // Default : `h720p_15fps`

  // It is Intent received from onActivityResult when user provide permission for ScreenShare.
  data = data,

  // Optional: If true, the screen is sent as up to three simulcast layers.
  multiStream = false, // true | Default : false

  // Optional: If true, the audio your device plays is shared too.
  withAudio = false // true | Default : false
)

// track is null when the user declined
if (track != null) {
  lifecycleScope.launch {
    try {
      room!!.enableScreenShare(track)
    } catch (e: VideoSDKException) {
      Log.e("VideoSDK", "Screen share failed: ${e.code} ${e.name}")
    }
  }
}

note

With withAudio = true, the shared audio is mixed into your mic track, so it is sent only while your mic is on, and muting the mic mutes both. No separate SHARE_AUDIO stream is sent, so other participants hear it in your microphone stream and getShareAudioStats() returns null for you. It needs Android 10 (API 29) or later and the RECORD_AUDIO permission.

How to Setup Custom Screen Share Track ?

To share the screen with a custom track, pass the CustomStreamTrack to enableScreenShare() on the Room. It is a suspend function, so call it from a coroutine.

note

enableScreenShare() throws VideoSDKException with 3054 (ERROR_ALREADY_IN_REQUESTED_STATE) while a screen share is running. Call disableScreenShare() before you share with a new track.

Example

private fun askPermissionForScreenShare() {
  val mediaProjectionManager = application.getSystemService(
      Context.MEDIA_PROJECTION_SERVICE
  ) as MediaProjectionManager
  startActivityForResult(
      mediaProjectionManager.createScreenCaptureIntent(), CAPTURE_PERMISSION_REQUEST_CODE
  )
}

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)
  if (requestCode != CAPTURE_PERMISSION_REQUEST_CODE) return
  if (resultCode == RESULT_OK) {
    val track = VideoSDK.createScreenShareVideoTrack("h720p_15fps", data)
    if (track != null) {
      lifecycleScope.launch {
        try {
          liveStream!!.enableScreenShare(track)
        } catch (e: VideoSDKException) {
          Log.e("VideoSDK", "Screen share failed: ${e.code} ${e.name}")
        }
      }
    }
  }
}

API Reference

The API references for all the methods and events utilised in this guide are provided below.

• Custom Video Track
• Custom Screen Share Track
• enableScreenShare()