Pin/Unpin Participants - Android

In a live stream setup, you often want to control which participant is actively visible on screen — whether it’s the host, a special guest, or someone screen sharing. To manage this dynamically, the Participant class provides two key methods:

• pin() – Focus on a specific participant’s camera or screen share

• unpin() – Remove that focus and return to the default layout

This allows you to programmatically decide who gets the spotlight in your live stream layout.

pin()

The pin() method makes it easy to bring a host camera or screen share front and center in the broadcast layout. Once pinned, you can write the layout logic to place this host in the primary frame, e.g. fullscreen or in a highlighted position.

Kotlin

private fun pinParticipant(participant: Participant) {
    participant.pin(null)
    Toast.makeText(context, "Participant pinned", Toast.LENGTH_SHORT).show()
}

Java

private void pinParticipant(Participant participant) {
    participant.pin(null);
    Toast.makeText(context, "Participant pinned", Toast.LENGTH_SHORT).show();
}

unpin()

When a host is no longer the focus (e.g. their segment is over), you can reset their pinned state using unpin(). This allows your live stream UI to revert to a default grid view or automatically promote the next speaker.

Kotlin

private fun unpinParticipant(participant: Participant) {
    participant.unpin(null)
    Toast.makeText(context, "Participant unpinned", Toast.LENGTH_SHORT).show()
}

Java

private void unpinParticipant(Participant participant) {
    participant.unpin(null);
    Toast.makeText(context, "Participant unpinned", Toast.LENGTH_SHORT).show();
}

Events associated with pin/unpin

Following callbacks are received when a host is pinned or unpinned in the livestream.

• All participants-including all the hosts and audience members will receive a callback on the onPinStateChanged event with the data object containg the peerid of the participant who was pinned, the state and pinnedBy values.

Kotlin

private val meetingEventListener = object : MeetingEventListener() {
    override fun onPinStateChanged(pinStateData: JSONObject) {
        try {
            Log.d("VideoSDK", "onPinStateChanged: $pinStateData")

            meeting?.let {
                val peerId = pinStateData.getString("peerId")
                var participant = it.participants[peerId]
                
                if (participant == null) {
                    participant = it.localParticipant
                }

                val name = participant?.displayName ?: "Unknown"
                Toast.makeText(this@MainActivity, "Pinned $name", Toast.LENGTH_SHORT).show()
            }
        } catch (e: JSONException) {
            e.printStackTrace()
        }
    }
}

Java

private final MeetingEventListener meetingEventListener = new MeetingEventListener() {
    @Override
    public void onPinStateChanged(JSONObject pinStateData) {
        try {
            Log.d("VideoSDK", "onPinStateChanged: " + pinStateData);
            if (meeting != null) {
                String peerId = pinStateData.getString("peerId");
                Participant participant = meeting.getParticipants().get(peerId);

                if (participant == null) {
                    participant = meeting.getLocalParticipant();
                }

                String displayName = participant.getDisplayName();
                Toast.makeText(MainActivity.this, "Pinned " + displayName, Toast.LENGTH_SHORT).show();
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }
};

info

• Based on the onPinStateChanged event, you should update your live stream layout for all participants (including the audience) to reflect the current pinned participant. This means conditionally rendering the pinned participant in the main view or spotlight area across all clients.

API Reference

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

• pin()
• unpin()