Join Live Stream - iOS

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

join()

• To join the live stream you can call the join() method of the Room class.
• This method can be called after the Room is created with VideoSDK.createRoom().
• join() is async throws, so call it with try await inside a Task.

Events associated with the join() method

Following events are received when a participant successfully joins the livestream.

• Local Participant will receive an onRoomJoined event, when successfully joined.
• Remote Participant will receive an onParticipantJoined event with the newly joined Participant object from the event callback.

Swift

func handleJoinStream() {
    Task {
        do {
            try await room?.join()
        } catch {
            print("Failed to join the livestream: \(error)")
        }
    }
}

extension LiveStreamViewController: RoomEventListener {

    // Event to know the room is joined
    func onRoomJoined() {
        print("You just joined the livestream")
    }

    // Event to know some other participant joined
    func onParticipantJoined(_ participant: Participant) {
        print("A new remote participant \(participant.displayName) just joined the livestream")
    }
}

Keep these in mind when you call join():

• A second join() throws ERROR_OPERATION_IN_PROGRESS while a join is running, and ERROR_ALREADY_IN_REQUESTED_STATE once you are in the live stream.
• If the join fails, the room state changes to FAILED and join() throws the error. The failure is usually also sent to onError, so handle it in one place.
• If you call leave() while the join is still running, the join is cancelled and join() returns without throwing. Treat onRoomJoined as the sign that you are in the live stream.
• For a host, join() returns before the mic and camera from micEnabled and camEnabled start. Wait for onStreamEnabled before you treat local media as on.

leave()

• To leave the live stream you can call the leave() method of the Room class.
• leave() is async throws, so call it with try await inside a Task.
• It throws ERROR_ALREADY_IN_REQUESTED_STATE if you have already left or the live stream has ended, and ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED if you have not joined. These errors are not sent to onError.

note

This method can be called after the live stream is joined successfully. If you call it while join() is still running, it cancels the join.

Events associated with the leave() method

Following callbacks are received when a participant leaves the live stream.

• The Local Participant will receive the onRoomLeft event, once they have successfully left the livestream.
• 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 the LeaveReason.

Swift

func handleLeaveStream() {
    Task {
        do {
            try await room?.leave()
        } catch {
            // Already left, or never joined
            print("Failed to leave the livestream: \(error)")
        }
    }
}

extension LiveStreamViewController: RoomEventListener {
    func onRoomLeft(reason: LeaveReason) {

        // remove listeners
        room?.localParticipant.removeEventListener(self)
        room?.removeEventListener(self)

        print("You left the livestream: \(reason)")
    }

    func onParticipantLeft(_ participant: Participant, reason: LeaveReason) {

        // remove listener
        participant.removeEventListener(self)

        print(participant.displayName, "just left the livestream")
    }
}

tip

You should call the leave() method when your main live stream screen is closed, so that the live stream is left once the screen goes away.

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()