Manage Roles - Android

Roles with VideoSDK

In interactive live streaming, each participant has a role. VideoSDK supports three participant modes:

1. SEND_AND_RECV (Mode.SEND_AND_RECV) When a participant is joining with mode set to SEND_AND_RECV, that participant can send media and receive the media of other participants, and also interact with them using the features like chat, poll etc.

2. SIGNALLING_ONLY (Mode.SIGNALLING_ONLY) When a participant is joining with mode set to SIGNALLING_ONLY, that participant neither sends nor receives any media. They can still interact with other participants using chat, polls etc.

3. RECV_ONLY (Mode.RECV_ONLY) When a participant is joining with mode set to RECV_ONLY, that participant can receive the media of other participants but sends none. They can also interact with other participants using chat, polls etc.

This image is for education purpose

When to use the Roles?

1. Simple Adaptive Streaming

• Simple Adaptive Streaming (SAS) is a type of livestreaming that requires minimal interaction between the host and viewers.

• It is particularly useful for events with a large number of viewers who prefer not to engage with the host.

• In SAS, each speaker joins a VideoSDK room in SEND_AND_RECV mode, while viewers can simply watch the livestream using its HLS URL. Unlike the speakers, viewers do not need to join the room in SEND_AND_RECV or SIGNALLING_ONLY mode.

  • The SDK delivers the HLS URL as hlsUrl.playbackHlsUrl in onHlsStateChanged, when the state is HLSState.HLS_PLAYABLE.

This video is for education purpose

2. Adaptive Streaming with increased engagement

• If you're looking to increase engagement with your audience during a live streaming event, consider using Adaptive Streaming technology. With this approach, you can incorporate interactive features such as polls and conversations, and give viewers the ability to join and leave the livestream as the host decides.

• To set this up, have all speakers join as SEND_AND_RECV mode participants, while the audience joins as SIGNALLING_ONLY mode participants. This way, everyone can participate in the interactive elements of the live stream and create a more dynamic and engaging experience for all.

This video is for education purpose

Using roles

Set the participant's mode with the mode argument of createRoom(). The token and room id come from your server, so fetch them in a coroutine before you create the room.

class MainActivity : AppCompatActivity() {

  private var room: Room? = null

  // Fetch these from your server, as shown in Initialize Live Stream
  suspend fun getToken(): String = TODO("Fetch a token from your server")

  suspend fun getRoomId(token: String): String = TODO("Create a room with the rooms API")

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    lifecycleScope.launch {
      //We will fetch token and roomId and store it in local variables
      val token = getToken()
      val roomId = getRoomId(token)

      try {
        // initialize the VideoSDK
        VideoSDK.initialize(applicationContext)

        // create a new room instance
        room = VideoSDK.createRoom(
            roomId = roomId,
            token = token,
            participantName = "NAME HERE",
            micEnabled = true,
            camEnabled = true,
            mode = Mode.SEND_AND_RECV, // allowed: SEND_AND_RECV | SIGNALLING_ONLY | RECV_ONLY
            multiStream = false,
        )
      } catch (e: VideoSDKException) {
        // 3073: the token or the roomId is empty
        Log.e("VideoSDK", "createRoom failed: ${e.code} ${e.name}")
      }

      Log.d("VideoSDK", "onCreate: $roomId")
    }
  }
}

Getting Participant Mode

You can identify a participant's role by using the mode property from Participant class. It is a Mode.

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

  val localParticipant = room!!.localParticipant
  Log.d("VideoSDK", "Participant mode : " + localParticipant.mode)
}

Changing Participant's Mode

Let's say you are hosting a livestream and you want one of your viewers to join the livestream with you. In this case the viewer's mode is changed with the changeMode() method of the Room class.

• changeMode() changes the mode of the participant who calls it. To change a viewer's mode, ask the viewer's app to call it, as shown in Invite Guest on Stage.
• changeMode() is a suspend function. Call it from a coroutine, such as lifecycleScope.launch (from androidx.lifecycle:lifecycle-runtime-ktx). It throws a VideoSDKException with 3054 when the participant is already in that mode, and 3055 while another changeMode() is running.
• When the participant moves back to SEND_AND_RECV, the SDK brings their mic and camera back as they were just before the mode change: on if they were on, off if they had turned them off. A participant that joined in another mode gets the mic and camera it enabled with micEnabled and camEnabled in createRoom().

findViewById<View>(R.id.btnConferenceMode).setOnClickListener { view: View? ->
    lifecycleScope.launch {
        try {
            // change mode to SEND_AND_RECV
            room!!.changeMode(Mode.SEND_AND_RECV)
        } catch (e: VideoSDKException) {
            // 3054: already in this mode, 3055: another change is running
            Log.e("VideoSDK", "changeMode failed: ${e.code} ${e.name}")
        }
    }
}

findViewById<View>(R.id.btnViewerMode).setOnClickListener { view: View? ->
    lifecycleScope.launch {
        try {
            // change mode to SIGNALLING_ONLY
            room!!.changeMode(Mode.SIGNALLING_ONLY)
        } catch (e: VideoSDKException) {
            Log.e("VideoSDK", "changeMode failed: ${e.code} ${e.name}")
        }
    }
}

API Reference

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

• Room
• Participant
• createRoom()
• mode
• changeMode()