Call & Participant State

Access call, participant, and client state using reactive hooks that update on WebSocket events and API calls.

Best Practices

  • Load calls first - Ensure call.get() or call.join() completes before accessing state hooks
  • Use StreamCall provider - Wrap components with StreamCall to access call state hooks
  • Handle truncation - useParticipants() returns max 250 participants; publishing participants have priority
  • Prefer utility functions - Use hasAudio(), hasVideo() instead of checking streams directly
  • Check participant source - Handle different participant sources (WebRTC, RTMP, WHIP, SIP) appropriately

Call state

Observe call state by providing a Call instance to StreamCall.

For the best experience, please make sure that the provided Call instance is loaded and connected to our backend: Load Call.

Otherwise, call.state and the call state hooks will provide empty values.

Example using useCall, useCallCallingState, and useParticipants hooks:

import {
  Call,
  StreamCall,
  useCall,
  useCallStateHooks,
} from "@stream-io/video-react-native-sdk";

export default function MyApp() {
  let call: Call;

  return (
    <StreamCall call={call}>
      <MyCallUI />
    </StreamCall>
  );
}

const MyCallUI = () => {
  const call = useCall();

  const { useCallCallingState, useParticipants } = useCallStateHooks();
  const callingState = useCallCallingState();
  const participants = useParticipants();

  return (
    <View>
      <Text>Call: {call?.cid}</Text>
      <Text>State: {callingState}</Text>
      <Text>Participants: {participants.length}</Text>
    </View>
  );
};

Access call state and receive change notifications anywhere in your app without manual WebSocket subscriptions.

  • StreamCall - Context provider making call state available to children
  • useCall - Returns the Call instance for API calls

Call State Hooks

Available call state hooks:

NameDescription
useCallThe Call instance that is registered with StreamCall. You need the Call instance to initiate API calls.
useCallBlockedUserIdsThe list of blocked user IDs.
useCallCallingStateProvides information about the call state. For example, RINGING, JOINED or RECONNECTING.
useCallClosedCaptionsThe closed captions of the call.
useCallCreatedAtThe time the call was created.
useCallCreatedByThe user that created the call.
useCallCustomDataThe custom data attached to the call.
useCallEgressThe egress information of the call.
useCallEndedAtThe time the call was ended.
useCallEndedByThe user that ended the call.
useCallIngressThe ingress information of the call.
useCallMembersThe list of call members
useCallSessionThe information for the current call session.
useCallSettingsThe settings of the call.
useCallStartedAtThe actual start time of the current call session.
useCallStartsAtThe scheduled start time of the call.
useCallStatsReportWhen stats gathering is enabled, this observable will emit a new value at a regular (configurable) interval.
useCallThumbnailThe thumbnail of the call.
useCallUpdatedAtThe time the call was last updated.
useCameraStateThe camera state of the local participant.
useDominantSpeakerThe participant that is the current dominant speaker of the call.
useHasOngoingScreenShareIt will return true if at least one participant is sharing their screen.
useHasPermissionsReturns true if the local participant has all the given permissions.
useIncomingVideoSettingsThe state of manual overrides to incoming video quality.
useIsCallCaptioningInProgresstrue if the call is being close-captioned.
useIsCallHLSBroadcastingInProgresstrue if the call is being broadcasted in HLS mode.
useIsCallIndividualRecordingInProgresstrue if the indivudal track recording is running.
useIsCallLivetrue if the call is currently live.
useIsCallRawRecordingInProgresstrue if the raw recording is currently running.
useIsCallRecordingInProgresstrue if the call is being recorded.
useIsCallTranscribingInProgresstrue if the call is being transcribed.
useMicrophoneStateThe microphone state of the local participant.
useOwnCapabilitiesThe capabilities of the local participant.
useScreenShareStateThe screen share state of the local participant.
useSpeakerStateNot supported in React Native

View the full list by destructuring useCallStateHooks:

import { useCallStateHooks } from "@stream-io/video-react-native-sdk";

const {
  useCallMembers,
  useDominantSpeaker,
  useParticipants,
  useLocalParticipant,
  useIsCallRecordingInProgress,
  // ...
} = useCallStateHooks();

Participant state

Display participant information using these hooks. They return StreamVideoParticipant objects with participant details.

Participant State Hooks

NameDescription
useAnonymousParticipantCountThe approximate participant count of anonymous users in the active call.
useLocalParticipantThe local participant is the logged-in user.
useParticipantCountThe approximate participant count of the active call. This includes the anonymous users as well, it is computed on the server-side.
useParticipantsAll participants, including local and remote participants.
usePinnedParticipantsThe participants that are currently pinned.
useRawParticipantsA version of useParticipants that is not affected by participant sort settings and thus causes less component updates.
useRemoteParticipantsAll participants except the local participant.

Warning: In a call with many participants, the value of the useParticipants() is truncated to 250 participants.

The participants who are publishing video, audio, or screen sharing have priority over the other participants in the list. This means, for example, that in a livestream with one host and many viewers, the host is guaranteed to be in the list.

import {
  Call,
  useCallStateHooks,
  StreamCall,
} from "@stream-io/video-react-native-sdk";

export default function App() {
  let call: Call;

  return (
    <StreamCall call={call}>
      <MyCallUI />
    </StreamCall>
  );
}

const MyCallUI = () => {
  const { useLocalParticipant, useParticipantCount } = useCallStateHooks();
  const participantCount = useParticipantCount();
  const localParticipant = useLocalParticipant();

  return (
    <View>
      <Text>Number of participants: {participantCount}</Text>
      <Text>Session ID: {localParticipant.sessionId}</Text>
    </View>
  );
};

Participant data

StreamVideoParticipant properties:

NameDescription
audioLevelThe audio level of the participant (determined on the server).
audioStreamThe audio MediaStream.
audioVolumeThe audio volume level of the participant (overridable local audioVolume level).
connectionQualityThe participant's connection quality.
customThe participant's custom data. Comes from the custom field of the user object.
imageThe image of the participant.
isDominantSpeakerIt's true if the participant is the current dominant speaker in the call.
isLocalParticipantIt's true if the participant is the local participant.
isSpeakingIt's true if the participant is currently speaking.
joinedAtThe time the participant joined the call.
nameThe name of the participant.
pausedTracksThe tracks that are currently server-side paused for the local participant.
pinHolds pinning information.
publishedTracksThe track types the participant is currently publishing
reactionThe last reaction this user has sent to this call.
rolesThe roles of the participant in this call.
screenShareAudioStreamThe screen share audio MediaStream.
screenShareStreamThe screen share MediaStream.
sessionIdThe identifier of the participant within the existing call session
sourceThe participant source: WebRTC (default), RTMP (OBS), WHIP, SIP, RTSP, SRT...
userIdThe user ID of the participant.
videoStreamThe video MediaStream.
viewportVisibilityStateThe viewport visibility state of the participant.

Utility functions

SDK utility functions for working with participants:

import {
  hasAudio,
  hasVideo,
  hasScreenShare,
  hasScreenShareAudio,
  hasPausedTrack,
  isPinned,
  useCallStateHooks,
} from "@stream-io/video-react-native-sdk";

// example usage
const { useParticipants } = useCallStateHooks();
const participants = useParticipants();

// check if the participant has audio, video, screen share or screen share audio
const [participant] = participants;
const hasAudioOn = hasAudio(participant);
const hasVideoOn = hasVideo(participant);
const hasScreenShareOn = hasScreenShare(participant);
const hasScreenShareAudioOn = hasScreenShareAudio(participant);
const isPinnedOn = isPinned(participant);
const isVideoPaused = hasPausedTrack(participant, "videoTrack");

// participants with a specific role
const hosts = participants.filter((p) => p.roles.includes("host"));

// participants that publish video and audio
const videoParticipants = participants.filter(
  (p) => hasVideo(p) && hasAudio(p),
);

Detecting participant source

Participants join from different sources: WebRTC, RTMP/OBS, WHIP, SIP, etc. Check the source property:

import { SfuModels } from "@stream-io/video-react-native-sdk";

const { useParticipants } = useCallStateHooks();
const participants = useParticipants();

// participants joining through OBS have RTMP source
const rtmpParticipants = participants.filter(
  (p) => p.source === SfuModels.ParticipantSource.RTMP,
);

Client state

Observe client state by providing a StreamVideoClient instance to StreamVideo. Use useConnectedUser to observe the connected user.

Example:

import {
  useConnectedUser,
  StreamVideo,
  StreamVideoClient,
} from "@stream-io/video-react-native-sdk";

export default function App() {
  let client: StreamVideoClient;

  return (
    <StreamVideo client={client}>
      <MyHeader />
    </StreamVideo>
  );
}

const MyHeader = () => {
  const user = useConnectedUser();
  return <Text>{user ? `Logged in: ${user.name}` : "Logged out"}</Text>;
};

Access client state and receive notifications without manual WebSocket subscriptions.

Client state hooks

NameDescription
useStreamVideoClientThe StreamVideoClient instance.
useConnectedUserReturns the connected user. Holds the server-side data of the connected user.
useCallsA list of all tracked calls. These calls can be outgoing (I have called somebody) or incoming (somebody has called me). Loaded calls (call.get()) are also part of this list.

connectedUser properties:

NameDescription
created_atThe time the user was created.
customCustom user data.
deleted_atThe time the user was deleted.
devicesThe registered push notification devices of the user.
idThe id of the user.
imageThe profile image of the user.
nameThe name of the user.
roleThe role of the user.
teamsThe teams the user belongs to.
updated_atThe time when the user was updated.