Manage On-Screen Participants - React Native

When engaging in interactive live streaming, it is essential to have only the necessary participant on the screen during the livestream. To manage this, the pin and unpin methods of the useParticipant hook are employed.

note

This page uses the following asynchronous methods. Refer to their API reference for the errors each Promise may reject with, and handle these rejections appropriately based on your use case.

• pin()
• unpin()

note

To ensure only the hosts/speakers are displayed in the grid, utilize the SPOTLIGHT layout and prioritize the pin function when initiating the interactive livestream.

Below is an explanation of the methods used to manage on-screen participants.

pin()

This method allows you to pin any participant's camera, screen share, or both. Use the pin state to choose which participants your grid shows.

unpin()

This method allows you to unpin any participant's camera, screen share, or both. It is particularly useful for resetting the pin state of the participant.

Managing On-Screen Participants

1. If you want to automatically pin all the hosts/speakers, you can achieve this by listening to the onRoomJoined callback and onParticipantModeChanged event. In these callbacks, you can pin and unpin participants based on their mode. In onRoomJoined, use the mode you passed in the RoomProvider config. In onParticipantModeChanged, use the mode that the event passes.

import { Constants, useRoom } from "@videosdk.live/react-native-sdk";
import { useEffect, useRef } from "react";

// joinMode is the mode you passed in the RoomProvider config
function RoomView({ joinMode }) {
  const mRoom = useRoom({});

  //Here a reference to the room value is used because
  //while referencing it in the callbacks its latest state has to be obtained.
  const mRoomRef = useRef(mRoom);

  useEffect(() => {
    mRoomRef.current = mRoom;
  }, [mRoom]);

  useRoom({
    onRoomJoined: async () => {
      const localParticipant = mRoomRef.current?.localParticipant;
      //Pin the participant if they joined in SEND_AND_RECV mode
      if (joinMode === Constants.Mode.SEND_AND_RECV) {
        try {
          await localParticipant.pin("SHARE_AND_CAM");
        } catch (err) {
          console.error("pin failed:", err);
        }
      } else {
        try {
          await localParticipant.unpin("SHARE_AND_CAM");
        } catch (err) {
          console.error("unpin failed:", err);
        }
      }
    },
    onParticipantModeChanged: async ({ participantId, mode }) => {
      const localParticipant = mRoomRef.current?.localParticipant;
      //Pin the participant if the new mode is SEND_AND_RECV, else unpin them
      if (participantId === localParticipant?.id) {
        if (mode === Constants.Mode.SEND_AND_RECV) {
          try {
            await localParticipant.pin("SHARE_AND_CAM");
          } catch (err) {
            console.error("pin failed:", err);
          }
        } else {
          try {
            await localParticipant.unpin("SHARE_AND_CAM");
          } catch (err) {
            console.error("unpin failed:", err);
          }
        }
      }
    },
  });
  return <>...</>;
}

2. When rendering the participant grid on the Speaker side, ensure that only participants in SEND_AND_RECV mode are displayed. Read each participant's mode from the useParticipant hook, which updates when the participant changes mode, as shown in the example provided below.

import {
  Constants,
  useRoom,
  useParticipant,
} from "@videosdk.live/react-native-sdk";

function SpeakerGrid() {
  const { participants } = useRoom();

  return (
    <>
      {[...participants.keys()].map((participantId) => (
        <SpeakerTile key={participantId} participantId={participantId} />
      ))}
    </>
  );
}

function SpeakerTile({ participantId }) {
  const { mode } = useParticipant(participantId);

  //Render only the participants in SEND_AND_RECV mode
  if (mode !== Constants.Mode.SEND_AND_RECV) {
    return null;
  }

  // ParticipantView is your component that renders the participant's video
  return <ParticipantView participantId={participantId} />;
}

API Reference

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

• pin
• unpin
• onParticipantModeChanged
• mode