Manage On-Screen Participants - iOS

It is important that only the necessary people are present on the screen when 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. You can 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 the pin state of the participant.

Both methods are async throws, so call them with try await inside a Task. They throw a VideoSDKError, for example when you call them before joining or while the live stream is reconnecting.

note

Mode.CONFERENCE and Mode.VIEWER were removed in 4.0.0. Use SEND_AND_RECV instead of CONFERENCE, and SIGNALLING_ONLY instead of VIEWER.

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.

Swift

class LiveStreamViewController: ObservableObject {
  //...
  func initializeStream(streamId: String, userName: String, mode: Mode) {
    //...
    // Add event listeners and join the live stream
    room?.addEventListener(self)
    //...
  }
}

extension LiveStreamViewController: RoomEventListener {
    func onRoomJoined() {
        guard let localParticipant = self.room?.localParticipant else { return }
        self.localParticipant = localParticipant
        localParticipant.addEventListener(self)
        //We will pin the participant if mode is SEND_AND_RECV
        Task {
            do {
                if localParticipant.mode == .SEND_AND_RECV {
                    try await localParticipant.pin()
                } else {
                    try await localParticipant.unpin()
                }
            } catch {
                print("Error while updating the pin state: \(error)")
            }
        }
    }

    func onParticipantModeChanged(participantId: String, mode: VideoSDKRTC.Mode) {
        let participant = self.participants.first { $0.id == participantId }
        if let participant = participant {
            //We will pin the participant if mode is SEND_AND_RECV
            Task {
                do {
                    if mode == .SEND_AND_RECV {
                        try await participant.pin()
                    } else {
                        try await participant.unpin()
                    }
                } catch {
                    print("Error while updating the pin state: \(error)")
                }
            }
        }
    }
    //...
}

API Reference

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

• pin()
• unpin()