Join Live Stream - Android

Once the live stream is configured, the next step is to join it. If you have not initialized the live stream yet, you can follow the guide here.

join()

• To join the live stream, call the join() method of the Room class.
• Call it after you create the live stream room with VideoSDK.createRoom().
• join() is a suspend function, so call it from a coroutine, for example lifecycleScope.launch (from androidx.lifecycle:lifecycle-runtime-ktx). See Coroutines and Error Handling.
• Add your RoomEventListener before you call join(), or you can miss the first events.
• If the live stream can't be joined, join() throws VideoSDKException:
  • 3055 (ERROR_OPERATION_IN_PROGRESS) if a join is already running.
  • 3054 (ERROR_ALREADY_IN_REQUESTED_STATE) if the live stream is already joined.
  • 3056 (ERROR_OPERATION_ABORTED) if leave() cancelled the join.
  • The server's error code, such as 4002 (INVALID_TOKEN) for a token the server rejects, or 3047 (ERROR_UNABLE_TO_JOIN_ROOM).

Events associated with Join

The following callbacks are received when a participant joins successfully.

• Local Participant will receive an onRoomJoined event, when successfully joined. It can arrive before join() returns.
• Remote Participant will receive an onParticipantJoined event with the newly joined Participant object from the event callback.

class LiveStreamActivity : AppCompatActivity() {
  private var liveStream: Room? = null

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_live_stream)
    // create the live stream room
    liveStream = VideoSDK.createRoom(...)
    ...

    // Add event listener for listening upcoming events of live stream
    liveStream!!.addEventListener(roomEventListener)

    // join the live stream
    lifecycleScope.launch {
      try {
        liveStream!!.join()
      } catch (e: VideoSDKException) {
        Log.e("VideoSDK", "Join failed: ${e.code} ${e.name}")
      }
    }
  }

  private val roomEventListener: RoomEventListener = object : RoomEventListener() {
    //Event to determine if the live stream has been joined
    override fun onRoomJoined(switchRoomId: String?) {
        Log.d("VideoSDK", "onRoomJoined")
    }
    //Event to determine some other participant has joined
    override fun onParticipantJoined(participant: Participant) {
        Log.d("#VideoSDK", participant.displayName + " joined")
    }
  }
}

leave()

• To leave the live stream, call the leave() method of the Room class.
• It also works while the live stream is reconnecting. Called while a join is still running, it cancels that join.
• It throws VideoSDKException with code 3035 (ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED) if join() was never called, and 3054 (ERROR_ALREADY_IN_REQUESTED_STATE) if it was already left. Neither is reported on onError.
• After a failed join, call leave() too: it releases the live stream and fires onRoomLeft with LeaveReason.MANUAL_LEAVE_CALLED. To try again, create a new live stream with VideoSDK.createRoom().

note

leave() is a suspend function, so call it from a coroutine and catch VideoSDKException.

btnLeave.setOnClickListener {
  lifecycleScope.launch {
    try {
      liveStream!!.leave()
    } catch (e: VideoSDKException) {
      // 3035: never joined, 3054: already left
      Log.w("VideoSDK", "Leave refused: ${e.code} ${e.name}")
    }
  }
}

Events associated with the leave() method

The following callbacks are received when a participant leaves the live stream.

• The Local Participant will receive the onRoomLeft event with a LeaveReason, once they have successfully left the livestream. After leave(), the reason is MANUAL_LEAVE_CALLED.
• All the Remote Participants—including all the hosts and audience members—will receive the onParticipantLeft event with the Participant object of the user who left the livestream and a LeaveReason.

private val roomEventListener = object : RoomEventListener() {
  //Event to determine if the live stream has been left
  override fun onRoomLeft(reason: LeaveReason) {
    Log.d("#VideoSDK", "onRoomLeft() :: reason: ${reason.message}")
  }

  //Event to determine some other participant has left
  override fun onParticipantLeft(participant: Participant, reason: LeaveReason) {
    Log.d("#VideoSDK", "${participant.displayName} left :: reason: ${reason.message}")
  }
}

tip

Call the leave() method before your live stream screen is destroyed, for example from your leave button as above. lifecycleScope is already cancelled when onDestroy() runs, so a leave() launched there never runs.

API Reference

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

• createRoom
• join()
• onRoomJoined()
• onParticipantJoined()
• leave()
• onRoomLeft()
• onParticipantLeft()