Skip to main content
Version: 2.x.x

Methods returned by useParticipant Hook - React Native

Every method that sends a request rejects before you join with 3035 ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED, while the room reconnects with 3065 ERROR_ROOM_RECONNECTING, and when the request times out with 3079 ERROR_OPERATION_TIMED_OUT. The errors listed under each method are the ones specific to it. See Error Codes for every code.

enableMic()​

  • enableMic() asks a remote participant to turn their mic on.

Events associated with enableMic():​

  • First the participant will get a callback on onMicRequested() and once the participant accepts the request, mic will be enabled.

  • Every Participant will receive a callback on onStreamEnabled() of the useParticipant() hook with the RTCStream.

Returns​

  • Promise<void>. It rejects with 4067 ENABLE_PARTICIPANT_MIC_FAILED when the server refuses the request.

disableMic()​

  • disableMic() turns a remote participant's mic off.

Events associated with disableMic():​

  • Every Participant will receive a callback on onStreamDisabled() of the useParticipant() hook with the RTCStream.

Returns​

  • Promise<void>. It rejects with 4068 DISABLE_PARTICIPANT_MIC_FAILED when the server refuses the request.

enableCam()​

  • enableCam() asks a remote participant to turn their camera on.

Events associated with enableCam():​

  • First the participant will get a callback on onWebcamRequested() and once the participant accepts the request, webcam will be enabled.

  • Every Participant will receive a callback on onStreamEnabled() of the useParticipant() hook with the RTCStream.

Returns​

  • Promise<void>. It rejects with 4069 ENABLE_PARTICIPANT_WEBCAM_FAILED when the server refuses the request.

disableCam()​

  • disableCam() turns a remote participant's camera off.

Events associated with disableCam():​

  • Every Participant will receive a callback on onStreamDisabled() of the useParticipant() hook with the RTCStream.

Returns​

  • Promise<void>. It rejects with 4070 DISABLE_PARTICIPANT_WEBCAM_FAILED when the server refuses the request.

setQuality()​

  • setQuality() sets the quality of a remote participant's video that you receive. videoQuality reads it back.

Parameter​

  • quality : "low" | "med" | "high"

Returns​

  • Promise<void>. It rejects with:
    • 3068 ERROR_ACTION_NOT_SUPPORTED when it is called on the local participant, or when there is no video stream.
    • 4073 SET_QUALITY_FAILED when the server refuses the request.

Example​

const { setQuality } = useParticipant(participantId);

async function receiveLowQuality() {
  try {
    await setQuality("low");
  } catch (error) {
    console.log("setQuality failed", error.code, error.message);
  }
}

pin()​

  • It is used to set pin state of the participant. You can use it to pin the screen share, camera or both of the participant.
  • Every participant receives onPinStateChanged when the pin state changes.

Parameters​

  • pinType (optional): "SHARE_AND_CAM" | "CAM" | "SHARE", also available as Constants.PinType. Default is "SHARE_AND_CAM".

Returns​

  • Promise<void>. It rejects with:
    • 3068 ERROR_ACTION_NOT_SUPPORTED for an unknown pinType.
    • 4071 PIN_FAILED when the server refuses the request.

unpin()​

  • It is used to unpin participant. You can use it to unpin the screen share, camera or both of the participant.
  • Every participant receives onPinStateChanged when the pin state changes.

Parameters​

  • pinType (optional): "SHARE_AND_CAM" | "CAM" | "SHARE", also available as Constants.PinType. Default is "SHARE_AND_CAM".

Returns​

  • Promise<void>. It rejects with:
    • 3068 ERROR_ACTION_NOT_SUPPORTED for an unknown pinType.
    • 4072 UNPIN_FAILED when the server refuses the request.

remove()​

  • It is used to remove a participant from the room.

Returns​

  • Promise<void>. It rejects with 4066 REMOVE_PARTICIPANT_FAILED when the server refuses the request.

consumeMicStreams()​

  • consumeMicStreams() starts receiving the participant's mic stream on this device.
  • Takes effect only when the room was created with autoConsume set to false.
  • Use it to receive the stream again after stopConsumingMicStreams(). It does not ask the participant to do anything.

Returns​

  • Promise<void>. It rejects with 4080 CONSUME_MIC_STREAMS_FAILED when the server refuses the request.

consumeWebcamStreams()​

  • consumeWebcamStreams() starts receiving the participant's webcam stream on this device.
  • Takes effect only when the room was created with autoConsume set to false.
  • Use it to receive the stream again after stopConsumingWebcamStreams().

Returns​

  • Promise<void>. It rejects with 4081 CONSUME_WEBCAM_STREAMS_FAILED when the server refuses the request.

stopConsumingMicStreams()​

  • stopConsumingMicStreams() stops receiving the participant's mic stream on this device, to save bandwidth. The participant is not muted, and everyone else still hears them.
  • Takes effect only when the room was created with autoConsume set to false.

Returns​

  • Promise<void>. It rejects with 4082 STOP_CONSUMING_MIC_STREAMS_FAILED when the server refuses the request.

stopConsumingWebcamStreams()​

  • stopConsumingWebcamStreams() stops receiving the participant's webcam stream on this device, for example while their tile is off screen. Their webcam stays on for everyone else.
  • Takes effect only when the room was created with autoConsume set to false.

Returns​

  • Promise<void>. It rejects with 4083 STOP_CONSUMING_WEBCAM_STREAMS_FAILED when the server refuses the request.

setViewPort()​

  • setViewPort() tells the SDK the size at which you show the participant's webcam, so you receive a quality that fits it. Call it when the view is laid out and whenever its size changes.
  • It applies to the webcam only, not to screen share.

Parameters​

  • width: number - the width of the view, in pixels.
  • height: number - the height of the view, in pixels.

React Native layout sizes are not pixels. Convert them with PixelRatio.getPixelSizeForLayoutSize().

captureImage()​

  • It is used to capture image of local participant's current videoStream.

  • It will return image in a form of base64.

  • Call it only for the local participant, and only while the camera is on.

Parameters​

The options object is optional.

  • height: number (optional) - the maximum height of the image, in pixels.
  • width: number (optional) - the maximum width of the image, in pixels.
  • flash: "ON" | "OFF" (optional), also available as Constants.CaptureFlash. "ON" lights the scene before the image is captured, which adds about half a second. A back camera uses its torch. A front camera lights the screen white instead. Default is "OFF".

Returns​

  • Promise<string | null> - the image as a base64-encoded JPEG, without a data: prefix.

The promise rejects with 3062 ERROR_WEBCAM_NOT_ENABLED when the camera is off, and with 3069 ERROR_CAPTURE_IMAGE_FAILED when the capture fails or when flash is "ON" for a remote participant. 3069 is also reported on onError of useRoom().

Example​

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

const { captureImage } = useParticipant(participantId);

async function takeSnapshot() {
  const base64Image = await captureImage({
    height: 400,
    width: 400,
    flash: "ON",
  });
  // Show it with <Image source={{ uri: `data:image/jpeg;base64,${base64Image}` }} />
}

setScreenFlash()​

  • setScreenFlash() decides up front whether a front-camera capture lights the screen. Import it from @videosdk.live/react-native-sdk. It is not returned by useParticipant().
  • Pass true to turn on the SDK's white screen overlay for front-camera captures. Pass false or null to turn it off.
  • You do not need to call it before captureImage({ flash: "ON" }): the capture turns the overlay on when it needs it.

Parameters​

  • flash: boolean | null

Returns​

  • Promise<void>

Example​

import { setScreenFlash } from "@videosdk.live/react-native-sdk";

await setScreenFlash(true);

getVideoStats()​

  • getVideoStats() will return an array which will contain details regarding the participant's video metrics such as Jitter, Packet Loss, Bitrate etc.

  • It has one entry per video layer: one for each layer your own webcam sends, and one for a remote participant's webcam.

Returns​

  • Promise<Array<object> | null> - each entry contains:
    • jitter : It represents the variation in packet arrival time, in milliseconds (ms). Measured only on streams this device receives, so it reads 0 for the local participant.
    • bitrate : It represents the bitrate of the stream which is being transmitted, in kbps.
    • totalPackets : It represents the packets transmitted for the stream since the previous sample, not a running total.
    • packetsLost : It represents the packets lost since the previous sample, not a running total.
    • rtt : It represents the round-trip time between this device and the server, in milliseconds (ms). Measured only on streams this device sends, so it reads 0 for a remote participant.
    • codec: It represents the codec used for the stream.
    • size: It is an object containing the width, height and, when known, framerate of the stream.
  • It resolves null or an empty array when there are no stats, for example while the participant's webcam is off.

Example​

const { getVideoStats } = useParticipant(participantId);

async function logVideoStats() {
  const videoStats = await getVideoStats();
  videoStats?.forEach((layer) => {
    console.log("Video bitrate (kbps):", layer.bitrate, "size:", layer.size);
  });
}
note

getVideoStats() will return the metrics for the participant at that given point of time and not average data of the complete session.

To view the metrics for the complete session using the stats API documented here.

info

If you are getting rtt greater than 300ms, try using a different region which is nearest to your user. To know more about changing region visit here.

getAudioStats()​

  • getAudioStats() will return an array which will contain details regarding the participant's audio metrics such as Jitter, Packet Loss, Bitrate etc.

Returns​

  • Promise<Array<object> | null> - each entry contains:
    • jitter : It represents the variation in packet arrival time, in milliseconds (ms). Measured only on streams this device receives, so it reads 0 for the local participant.
    • bitrate : It represents the bitrate of the stream which is being transmitted, in kbps.
    • totalPackets : It represents the packets transmitted for the stream since the previous sample, not a running total.
    • packetsLost : It represents the packets lost since the previous sample, not a running total.
    • rtt : It represents the round-trip time between this device and the server, in milliseconds (ms). Measured only on streams this device sends, so it reads 0 for a remote participant.
    • codec: It represents the codec used for the stream.
  • It resolves null or an empty array when there are no stats.
note

getAudioStats() will return the metrics for the participant at that given point of time and not average data of the complete session.

To view the metrics for the complete session using the stats API documented here.

info

If you are getting rtt greater than 300ms, try using a different region which is nearest to your user. To know more about changing region visit here.

getShareStats()​

  • getShareStats() will return an array which will contain details regarding the participant's screen share metrics such as Jitter, Packet Loss, Bitrate etc.

Returns​

  • Promise<Array<object> | null> - each entry contains:
    • jitter : It represents the variation in packet arrival time, in milliseconds (ms). Measured only on streams this device receives, so it reads 0 for the local participant.
    • bitrate : It represents the bitrate of the stream which is being transmitted, in kbps.
    • totalPackets : It represents the packets transmitted for the stream since the previous sample, not a running total.
    • packetsLost : It represents the packets lost since the previous sample, not a running total.
    • rtt : It represents the round-trip time between this device and the server, in milliseconds (ms). Measured only on streams this device sends, so it reads 0 for a remote participant.
    • codec: It represents the codec used for the stream.
    • size: It is an object containing the width, height and, when known, framerate of the stream.
  • It resolves null or an empty array when there are no stats, for example while the participant is not sharing their screen.
note

getShareStats() will return the metrics for the participant at that given point of time and not average data of the complete session.

To view the metrics for the complete session using the stats API documented here.

info

If you are getting rtt greater than 300ms, try using a different region which is nearest to your user. To know more about changing region visit here.

getTransportStats()​

  • getTransportStats() will return the participant's network transport metrics: how much data flows in and out over their connection, for all their streams together.

Returns​

  • Promise<object | null> - an object containing:
    • send : the data the participant sends.
      • outgoingBitrate : the send bitrate, in kbps.
      • totalSentBytes : the total bytes sent.
    • receive : the data the participant receives.
      • incomingBitrate : the receive bitrate, in kbps.
      • totalReceivedBytes : the total bytes received.
  • It resolves null before the connection is set up, or when the stats could not be read. Right after joining, before media flows, the values can be null.

Example​

const { getTransportStats } = useParticipant(participantId);

async function logTransportStats() {
  const transportStats = await getTransportStats();
  console.log(
    "Upload (kbps):",
    transportStats?.send.outgoingBitrate,
    "Download (kbps):",
    transportStats?.receive.incomingBitrate,
  );
}

Got a Question? Ask us on discord

Last updated on by saksham-videosdk
Previous
useParticipant Hook Event Callbacks
Next

Was this helpful?

Not helpfulHelpful