Version: 2.x.x

Methods returned by useRoom Hook - React Native

note

Every method that acts on the room returns a Promise. A method called before join() rejects with ERROR_ACTION_PERFORMED_BEFORE_ROOM_JOINED (3035). Some failures are reported only through the onError callback, so handle errors both where you call the method and in onError. To see all available error codes from SDK, refer to Error Codes.

Call these methods on what useRoom() returns. The room object has most of them too, but not the toggles, setAudioDevice(), the video processor methods, getActivePresenterId() or getActiveSpeakerId().

join()

Joins the room.
If joinWithoutUserInteraction is true on <RoomProvider>, the participant joins automatically. If it is false, call join() yourself.

Events associated with `join()`:

The local participant receives onRoomJoined once joined.
Remote participants receive onParticipantJoined with the new Participant.

Participant having `ask_join` permission inside token

If the token has the ask_join permission, the participant does not join directly. Participants with the allow_join permission receive onEntryRequested, and answer with its allow() / deny() functions or with respondEntry().
Once someone decides, onEntryResponded reports the decision.

Participant having `allow_join` permission inside token

If the token has the allow_join permission, the participant joins directly.

Returns

Promise<void>

leave()

Leaves the room. Only the local participant leaves.

Events associated with `leave()`:

The local participant receives onRoomLeft.
Remote participants receive onParticipantLeft with the Participant who left.

Returns

Promise<void>

end()

Ends the room for every participant.

Events associated with `end()`:

Every participant, including the local participant, receives onRoomLeft.

Returns

Promise<void>

unmuteMic()

Turns on the local participant's microphone.
In RECV_ONLY or SIGNALLING_ONLY mode, it rejects with 3066 ERROR_ACTION_NOT_SUPPORTED_IN_MODE.

Parameters

customMicrophoneTrack (optional): a CustomStreamTrack from createMicrophoneAudioTrack(). If you do not pass one, the SDK opens the selected microphone.

Events associated with `unmuteMic()`:

Every participant receives onStreamEnabled() of useParticipant() with the RTCStream.

Returns

Promise<void>

muteMic()

Turns off the local participant's microphone.

Events associated with `muteMic()`:

Every participant receives onStreamDisabled() of useParticipant() with the RTCStream.

Returns

Promise<void>

Example

const { isMicEnabled, muteMic, unmuteMic } = useRoom();

const onMicPress = () => (isMicEnabled ? muteMic() : unmuteMic());

toggleMic()

Turns the local participant's microphone off when it is on, and on when it is off.
In RECV_ONLY or SIGNALLING_ONLY mode, turning it on rejects with 3066 ERROR_ACTION_NOT_SUPPORTED_IN_MODE.

Parameters

customMicrophoneTrack (optional): a CustomStreamTrack from createMicrophoneAudioTrack(), used when the microphone turns on.

Events associated with `toggleMic()`:

Every participant receives onStreamEnabled() when the microphone turns on, or onStreamDisabled() when it turns off.

Returns

Promise<void>

Example

const { toggleMic } = useRoom();

const onMicPress = async () => {
  try {
    await toggleMic();
  } catch (error) {
    console.log("toggleMic failed", error.code, error.message);
  }
};

enableCam()

Turns on the local participant's camera.
In RECV_ONLY or SIGNALLING_ONLY mode, it rejects with 3066 ERROR_ACTION_NOT_SUPPORTED_IN_MODE.

Parameters

customCameraTrack (optional): a CustomStreamTrack from createCameraVideoTrack(). Pass the track you previewed to keep its picture. If you do not pass one, the SDK opens the selected camera.

Events associated with `enableCam()`:

Every participant receives onStreamEnabled() of useParticipant() with the RTCStream.

Returns

Promise<void>

disableCam()

Turns off the local participant's camera.

Events associated with `disableCam()`:

Every participant receives onStreamDisabled() of useParticipant() with the RTCStream.

Returns

Promise<void>

Example

const { isCamEnabled, enableCam, disableCam } = useRoom();

const onCameraPress = () => (isCamEnabled ? disableCam() : enableCam());

toggleCam()

Turns the local participant's camera off when it is on, and on when it is off.
In RECV_ONLY or SIGNALLING_ONLY mode, turning it on rejects with 3066 ERROR_ACTION_NOT_SUPPORTED_IN_MODE.

Parameters

customCameraTrack (optional): a CustomStreamTrack from createCameraVideoTrack(), used when the camera turns on.

Events associated with `toggleCam()`:

Every participant receives onStreamEnabled() when the camera turns on, or onStreamDisabled() when it turns off.

Returns

Promise<void>

Example

const { toggleCam } = useRoom();

const onCameraPress = async () => {
  try {
    await toggleCam();
  } catch (error) {
    console.log("toggleCam failed", error.code, error.message);
  }
};

changeMic()

Switches the microphone.
Pass a deviceId from getMics(), or a track from createMicrophoneAudioTrack(). If you pass nothing, the SDK switches to the next microphone in the list, and after the last one back to the first.
A deviceId that matches no microphone rejects with ERROR_NO_MICROPHONE_DEVICE_FOUND (3059).

Parameters

deviceIdOrTrack (optional): string | CustomStreamTrack

Returns

Promise<void>

changeCam()

Switches the camera.
Pass a deviceId from getCameras(), or a track from createCameraVideoTrack(). If you pass nothing, the SDK switches to the next camera in the list, and after the last one back to the first.
A deviceId that matches no camera rejects with ERROR_NO_WEBCAM_DEVICE_FOUND (3051).

Parameters

deviceIdOrTrack (optional): string | CustomStreamTrack

Returns

Promise<void>

Example

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

const { changeCam } = useRoom();
const { getCameras } = useMediaDevice();

const switchToBackCamera = async () => {
  const cameras = await getCameras();
  const backCamera = cameras.find((camera) => camera.facingMode === "back");

  if (backCamera) {
    await changeCam(backCamera.deviceId);
  }
};

setWebcamQuality()

Sets the quality of the camera video you send.

Parameters

quality: "low" | "med" | "high", the values of Constants.VideoQuality

Returns

Promise<void>

enableScreenShare()

Starts sharing the local participant's screen.
In RECV_ONLY or SIGNALLING_ONLY mode, it rejects with 3066 ERROR_ACTION_NOT_SUPPORTED_IN_MODE.
It takes one optional argument: a track from createScreenShareVideoTrack(). To choose the encoder profile, create the track with encoderConfig.
On Android, the screen capture consent dialog appears when you create the track. If you call enableScreenShare() without a track, it shows the dialog itself and, on Android 10 and later, also shares the device audio mixed into your microphone track. To share without device audio, pass a track from createScreenShareVideoTrack().
On iOS, enableScreenShare() shows the system broadcast sheet. Screen capture starts when the user taps Start Broadcast.

Parameters

customScreenShareTrack (optional): CustomStreamTrack

Events associated with `enableScreenShare()`:

Every participant receives onStreamEnabled() of useParticipant() with the share RTCStream. This tells you that sharing has started.
onPresenterChanged() receives the presenter's id.

Returns

Promise<void>

Example

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

const { enableScreenShare } = useRoom();

const startScreenShare = async () => {
  const screenShareTrack = await createScreenShareVideoTrack({
    encoderConfig: "h720p_15fps",
  });

  await enableScreenShare(screenShareTrack);
};

caution

For React Native iOS Screen Share feature, your app needs a Broadcast Upload Extension. Follow this guide to set it up: React Native iOS Screen Share

disableScreenShare()

Stops sharing the local participant's screen.

Events associated with `disableScreenShare()`:

Every participant receives onStreamDisabled() of useParticipant() with the share RTCStream.
onPresenterChanged() receives null.

Returns

Promise<void>

toggleScreenShare()

Starts the screen share when it is off and stops it when it is on.
In RECV_ONLY or SIGNALLING_ONLY mode, it rejects with 3066 ERROR_ACTION_NOT_SUPPORTED_IN_MODE.
It takes the same optional argument as enableScreenShare(), used when sharing starts.
Only useRoom() has it. The room object does not.

Parameters

customScreenShareTrack (optional): CustomStreamTrack

Returns

Promise<void>

caution

For React Native iOS Screen Share feature, your app needs a Broadcast Upload Extension. Follow this guide to set it up: React Native iOS Screen Share

setAudioDevice()

Routes audio to a device from getMics(), such as the speaker, earpiece or a Bluetooth headset. It does not change whether the microphone is muted.
Call it after join().

Parameters

device: MicrophoneDeviceInfo | "SPEAKER_PHONE" | "EARPIECE" | "WIRED_HEADSET" | "BLUETOOTH"

Returns

Promise<void>

Example

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

const { setAudioDevice } = useRoom();
const { getMics } = useMediaDevice();

const useFirstDevice = async () => {
  const devices = await getMics();
  if (devices.length > 0) await setAudioDevice(devices[0]);
};

setVideoProcessor()

Applies a video processor that your app registered natively under name. See Video Processor.
Applying a name that has no registered processor rejects with ERROR_INVALID_PARAMETER (3073).

Parameters

name: string

Returns

Promise<void>

removeVideoProcessor()

Removes the video processor in use.

Returns

Promise<void>

startRecording()

Starts recording the room.
webhookUrl is called when the recording is complete and stored. Read more about webhooks here.
awsDirPath is the folder in your own cloud storage where the recording is stored. To store recordings in your AWS S3, Azure Blob or GCP storage, set it up as described in Recording Storage Config.
config.mode records video and audio, or only audio. The default is video and audio.
config.quality applies only to video-and-audio.
transcription turns on a transcript of the recording, made after the recording ends.

Parameters

webhookUrl (optional): String
awsDirPath (optional): String
config (optional):
- layout: ConfigLayout
  - type: "GRID" | "SPOTLIGHT" | "SIDEBAR"
  - priority: "SPEAKER" | "PIN"
  - gridSize: Number max 4
- theme: "DARK" | "LIGHT" | "DEFAULT"
- mode: "video-and-audio" | "audio"
- quality: "low" | "med" | "high"
- orientation: "landscape" | "portrait"
transcription (optional):
- enabled: Boolean
- summary: { enabled: Boolean, prompt: String }
- modelId: String

Events associated with `startRecording()`:

Every participant receives onRecordingStarted().
The returned Promise resolves once the request is sent, not when the recording has started. The recording has started when onRecordingStateChanged() reports RECORDING_STARTED.

Returns

Promise<void>

Example

const webhookUrl = "https://webhook.your-api-server.com";

const awsDirPath = "/room-recordings/";

const { startRecording } = useRoom();

startRecording(webhookUrl, awsDirPath, {
  layout: {
    type: "SPOTLIGHT",
    priority: "PIN",
    gridSize: 4,
  },
  theme: "DEFAULT",
  mode: "video-and-audio",
  quality: "high",
  orientation: "landscape",
});

stopRecording()

Stops the recording.

Events associated with `stopRecording()`:

Every participant receives onRecordingStopped().

Returns

Promise<void>

startLivestream()

Starts live streaming the room to platforms that support RTMP, such as YouTube or Facebook.

Parameters

outputs: Array<{ url: String, streamKey: String }>
config (optional):
- layout: ConfigLayout
  - type: "GRID" | "SPOTLIGHT" | "SIDEBAR"
  - priority: "SPEAKER" | "PIN"
  - gridSize: Number max 4
- theme: "DARK" | "LIGHT" | "DEFAULT"
- recording: { enabled: Boolean }, whether the livestream is also recorded

Events associated with `startLivestream()`:

Every participant receives onLivestreamStarted().

Returns

Promise<void>

Example

const outputs = [
  {
    url: "rtmp://a.rtmp.youtube.com/live2",
    streamKey: "<STREAM_KEY>",
  },
  {
    url: "rtmps://",
    streamKey: "<STREAM_KEY>",
  },
];

const { startLivestream } = useRoom();

startLivestream(outputs, {
  layout: {
    type: "SPOTLIGHT",
    priority: "PIN",
    gridSize: 4,
  },
  theme: "DEFAULT",
});

stopLivestream()

Stops the live stream.

Events associated with `stopLivestream()`:

Every participant receives onLivestreamStopped().

Returns

Promise<void>

startHLS()

Starts HLS streaming of the room.
config.mode streams video and audio, or only audio. The default is video and audio.
config.quality applies only to video-and-audio.

Parameters

config (optional):
- layout: ConfigLayout
  - type: "GRID" | "SPOTLIGHT" | "SIDEBAR"
  - priority: "SPEAKER" | "PIN"
  - gridSize: Number max 25
- theme: "DARK" | "LIGHT" | "DEFAULT"
- mode: "video-and-audio" | "audio"
- quality: "low" | "med" | "high"
- orientation: "landscape" | "portrait"
- recording: { enabled: Boolean }, whether the HLS stream is also recorded
transcription (optional): the same as for startRecording().

Events associated with `startHLS()`:

Every participant receives onHlsStateChanged() as HLS starts. The HLS URLs arrive with the HLS_PLAYABLE state.

Returns

Promise<void>

Example

const { startHLS } = useRoom();

startHLS({
  layout: {
    type: "SPOTLIGHT",
    priority: "PIN",
    gridSize: 9,
  },
  theme: "DEFAULT",
  mode: "video-and-audio",
  quality: "high",
  orientation: "portrait",
});

stopHLS()

Stops HLS streaming.

Events associated with `stopHLS()`:

Every participant receives onHlsStateChanged() with HLS_STOPPING, then HLS_STOPPED.

Returns

Promise<void>

changeMode()

Changes the local participant's mode.

The modes are:
- SEND_AND_RECV: The participant sends and receives audio and video.
- SIGNALLING_ONLY: The participant neither sends nor receives audio and video, but stays in the room.
- RECV_ONLY: The participant receives audio and video but sends none.

Parameters

mode: one of Constants.Mode: "SEND_AND_RECV" | "SIGNALLING_ONLY" | "RECV_ONLY"

Events associated with `changeMode()`:

Every participant receives onParticipantModeChanged().

Returns

Promise<void>

respondEntry()

Answers an entry request from onEntryRequested. The request's own allow() and deny() functions do the same.
Pass "allowed" to let the participant in, or "denied" to refuse.

Parameters

participantId: String, the participantId from the entry request
decision: "allowed" | "denied"

Events associated with `respondEntry()`:

The participant who asked to join, and the participants with the allow_join permission, receive onEntryResponded() with the decision.

Returns

Promise<void>

Example

const { respondEntry } = useRoom({
  onEntryRequested: ({ participantId, name }) => {
    console.log(`${name} requested to join the room.`);

    // To let them in
    respondEntry(participantId, "allowed");

    // To refuse
    // respondEntry(participantId, "denied");
  },
});

send()

Sends a message to every other participant over the room's data channel.
The message can be a string, an ArrayBuffer or a typed array such as Uint8Array. A Blob is not supported.
The Promise resolves once the message is sent. It does not confirm that the other participants received it. It rejects when the message did not go out.

Parameters

message: String | ArrayBuffer | typed array
reliable (optional): boolean. true (the default) delivers every message in order. false sends the message once, so it can be lost.

Events associated with `send()`:

Every other participant receives onDataReceived() with the message.

Returns

Promise<void>

Example

const { send } = useRoom();

const sendGreeting = async () => {
  await send("Hello everyone!");
};

const sendPosition = async () => {
  await send(new Uint8Array([10, 20]), false);
};

pauseAllStreams()

Pauses the media streams you receive from the other participants.

Parameters

kind (optional): the kind of stream to pause. If you leave it out, every kind is paused.
- Type: String
  - Possible values:
  - "audio": Pauses audio streams.
  - "video": Pauses video streams.
  - "share": Pauses screen-share video streams.
  - "shareAudio": Pauses screen-share audio streams.
  - "all": Pauses every kind.

Events associated with `pauseAllStreams()`:

onPausedAllStreams() is called with the kind that was paused. If you omit kind, it is called once for each kind or once with "all", depending on the platform.

Returns

Promise<void>

resumeAllStreams()

Resumes the media streams you paused.

Parameters

kind (optional): the kind of stream to resume. If you leave it out, every kind is resumed. Takes the same values as pauseAllStreams().

Events associated with `resumeAllStreams()`:

onResumedAllStreams() is called with the kind that was resumed. If you omit kind, it is called once for each kind or once with "all", depending on the platform.

Returns

Promise<void>

enableAdaptiveSubscription()

Turns on adaptive subscription. The quality of each video stream you receive then follows how large you show that participant and your network conditions.
Report the size you show each participant at with setViewPort() of the useParticipant() hook.

Returns

Promise<void>

disableAdaptiveSubscription()

Turns off adaptive subscription. Every video stream you receive then comes at the quality its publisher sends, whatever its size on screen or the network conditions.

Returns

Promise<void>

requestMediaRelay()

Starts relaying your media, such as camera video, microphone audio or screen share, from this room into another room.

Parameters

It takes one object with these fields:

destinationRoomId (String) – Required: ID of the room to relay into.
token (String) – Optional: Authentication token for the destination room.
kinds (Array of Strings) – Optional: The media to relay. Every kind is relayed when you leave it out.
- Possible values:
  - "audio": Relays audio streams.
  - "video": Relays video streams.
  - "share": Relays screen-share streams.

Events associated with `requestMediaRelay()`:

The participants of the destination room receive onMediaRelayRequestReceived().
You receive onMediaRelayRequestResponse() with their decision, and onMediaRelayStarted() when the relay starts.

Returns

Promise<void>

Example

const { requestMediaRelay } = useRoom();

const relayToRoom = async (destinationRoomId) => {
  await requestMediaRelay({
    destinationRoomId,
    kinds: ["audio", "video"],
  });
};

stopMediaRelay()

Stops relaying your media into one room.

Parameters

destinationRoomId (String) – Required: ID of the room to stop relaying into.

Events associated with `stopMediaRelay()`:

You receive onMediaRelayStopped().

Returns

Promise<void>

switchTo()

Moves you from this room into another room without leaving and joining again.

Parameters

roomId (String) – Required: ID of the room to switch to.
token (String) – Optional: Authentication token for the new room. Without it, the current token is used.

Events associated with `switchTo()`:

You receive onRoomJoined() once you are in the new room.

Returns

Promise<void>

Example

const { switchTo } = useRoom();

const moveToRoom = async (roomId, token) => {
  await switchTo(roomId, token);
};

getActivePresenterId()

Returns the id of the participant sharing their screen, or null when nobody is.
Calling it while rendering re-renders the component when the presenter changes.

Returns

string | null

getActiveSpeakerId()

Returns the id of the participant speaking, or null when nobody is.
Calling it while rendering re-renders the component when the speaker changes.

Returns

string | null

Example

const { getActiveSpeakerId, getActivePresenterId } = useRoom();

const speakerId = getActiveSpeakerId();
const presenterId = getActivePresenterId();

Transcription, translation and whiteboard

To start and stop transcription, translation and the whiteboard, use the useTranscription(), useTranslation() and useWhiteboard() hooks.

Got a Question? Ask us on discord

join()​

Events associated with join():​

Participant having ask_join permission inside token​

Participant having allow_join permission inside token​

Returns​

leave()​

Events associated with leave():​

Returns​

end()​

Events associated with end():​

Returns​

unmuteMic()​

Parameters​

Events associated with unmuteMic():​

Returns​

muteMic()​

Events associated with muteMic():​

Returns​

Example​

toggleMic()​

Parameters​

Events associated with toggleMic():​

Returns​

Example​

enableCam()​

Parameters​

Events associated with enableCam():​

Returns​

disableCam()​

Events associated with disableCam():​

Returns​

Example​

toggleCam()​

Parameters​

Events associated with toggleCam():​

Returns​

Example​

changeMic()​

Parameters​

Returns​

changeCam()​

Parameters​

Returns​

Example​

setWebcamQuality()​

Parameters​

Returns​

enableScreenShare()​

Parameters​

Events associated with enableScreenShare():​

Returns​

Example​

disableScreenShare()​

Events associated with disableScreenShare():​

Returns​

toggleScreenShare()​

Parameters​

Returns​

setAudioDevice()​

Parameters​

Returns​

Example​

setVideoProcessor()​

Parameters​

Returns​

removeVideoProcessor()​

Returns​

startRecording()​

Parameters​

Events associated with startRecording():​

Returns​

Example​

stopRecording()​

Events associated with stopRecording():​

Returns​

startLivestream()​

Parameters​

Events associated with startLivestream():​

Returns​

Example​

join()

Events associated with `join()`:

Participant having `ask_join` permission inside token

Participant having `allow_join` permission inside token

Returns

leave()

Events associated with `leave()`:

Returns

end()

Events associated with `end()`:

Returns

unmuteMic()

Parameters

Events associated with `unmuteMic()`:

Returns

muteMic()

Events associated with `muteMic()`:

Returns

Example

toggleMic()

Parameters

Events associated with `toggleMic()`:

Returns

Example

enableCam()

Parameters

Events associated with `enableCam()`:

Returns

disableCam()

Events associated with `disableCam()`:

Returns

Example

toggleCam()

Parameters

Events associated with `toggleCam()`:

Returns

Example

changeMic()

Parameters

Returns

changeCam()

Parameters

Returns

Example

setWebcamQuality()

Parameters

Returns

enableScreenShare()

Parameters

Events associated with `enableScreenShare()`:

Returns

Example

disableScreenShare()

Events associated with `disableScreenShare()`:

Returns

toggleScreenShare()

Parameters

Returns

setAudioDevice()

Parameters

Returns

Example

setVideoProcessor()

Parameters

Returns

removeVideoProcessor()

Returns

startRecording()

Parameters

Events associated with `startRecording()`:

Returns

Example

stopRecording()

Events associated with `stopRecording()`:

Returns

startLivestream()

Parameters

Events associated with `startLivestream()`:

Returns

Example