Manage On-Screen Participants - Android

It is important that only the necessary people are on screen while the livestream is on. To handle this, we will be using the pin and unpin methods of the Participant class.

note

To ensure only the hosts/speakers are shown in the grid, you should use the SPOTLIGHT layout and pin as the priority when starting the interactive livestream.

Let us first explore two methods that we will be using to manage on-screen participants.

pin()

With this method you can pin any participant's camera, screen share or both. Use the pin state to decide which participants to render in the grid.

unpin()

With this method you can unpin any participant's camera, screen share or both. This can be useful to reset pin state of the participant.

Both methods take a PinType for what to pin or unpin: PinType.CAM, PinType.SHARE or PinType.SHARE_AND_CAM, the default. They are suspend functions, so call them from a coroutine, such as lifecycleScope.launch (from androidx.lifecycle:lifecycle-runtime-ktx), and catch VideoSDKException.

Managing On-Screen Participants

1. If you want to pin all the hosts/speakers automatically, you can do it by listening to the onRoomJoined callback and onParticipantModeChanged, where you can pin and unpin based on the mode.

private fun updateLocalPin() {
    val localParticipant = room!!.localParticipant
    lifecycleScope.launch {
        try {
            //We will pin the participant if mode is SEND_AND_RECV, else unpin
            if (localParticipant.mode == Mode.SEND_AND_RECV) {
                localParticipant.pin(PinType.SHARE_AND_CAM)
            } else {
                localParticipant.unpin(PinType.SHARE_AND_CAM)
            }
        } catch (e: VideoSDKException) {
            Log.e("VideoSDK", "pin/unpin failed: ${e.code} ${e.name}")
        }
    }
}

private val roomEventListener: RoomEventListener = object : RoomEventListener() {
  override fun onRoomJoined(switchRoomId: String?) {
    updateLocalPin()
  }

  override fun onParticipantModeChanged(participantId: String, mode: Mode) {
    // react only to the local participant's own mode change
    if (room!!.localParticipant.id == participantId) {
      updateLocalPin()
    }
  }
}

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

  // add listener to room
  room!!.addEventListener(roomEventListener)
}

2. When rendering the participant grid on the Speaker side, make sure to show only the participants who are in SEND_AND_RECV mode. You can filter the participants as shown in the example below.

 private fun getSpeakerList(): List<Participant?>? {
    val speakerList: MutableList<Participant?> = ArrayList()
    val participants = room!!.participants
    for (entry: Map.Entry<String, Participant> in participants.entries) {
        val participant = entry.value
        if (participant.mode == Mode.SEND_AND_RECV) {
            speakerList.add(participant)
        }
    }
    return speakerList
}

API Reference

The API references for all the methods utilized in this guide are provided below.

• pin
• unpin