Selective Subscription - React Native

By default, your app receives every participant's mic and webcam as soon as they turn them on. In a large room, most of those webcams are never on screen, yet each one still costs download bandwidth and battery.

With selective subscription, your app receives a participant's mic or webcam only when you ask for it. The participant keeps sending as usual, and everyone else in the room is unaffected.

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.

• consumeMicStreams()
• consumeWebcamStreams()
• stopConsumingMicStreams()
• stopConsumingWebcamStreams()

How it works

• Join with autoConsume: false in the config of RoomProvider. Your app then receives no participant's mic or webcam until you ask for it.
• onMediaStatusChanged of useParticipant tells you when a participant turns their mic or webcam on or off, even when your app isn't receiving it.
• consumeMicStreams() and consumeWebcamStreams() from useParticipant start receiving a participant's mic or webcam on this device. When the media arrives, onStreamEnabled fires and micStream or webcamStream is set, as usual.
• stopConsumingMicStreams() and stopConsumingWebcamStreams() stop receiving it on this device. The participant is not muted, and everyone else still receives them.
• The four consume methods take effect only when the room was joined with autoConsume set to false.

autoConsume covers the mic and the webcam. There is no consume method for screen shares.

Step 1: Join without receiving media

Pass autoConsume: false in the config of RoomProvider. It defaults to true.

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

export default function App() {
  return (
    <RoomProvider
      config={{
        roomId: "<roomId>",
        participantName: "John Doe",
        autoConsume: false,
      }}
      token={"<token>"}
    >
      <RoomView />
    </RoomProvider>
  );
}

Step 2: Receive the participants you show

Render one tile per participant, and ask for the media you want when the tile mounts.

A consume method starts receiving media that is on. If the participant turns their mic or webcam on later, call it again from onMediaStatusChanged. Ask once per participant and kind: skip a kind that is already arriving in micStream or webcamStream, or already requested.

The example below receives everyone's mic, so nobody goes unheard, and receives a webcam only while that participant's tile is on screen.

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

function ParticipantTile({ participantId, isOnScreen }) {
  const onScreen = useRef(isOnScreen);
  onScreen.current = isOnScreen;

  const { micStream, webcamStream, consumeMicStreams, consumeWebcamStreams } =
    useParticipant(participantId, {
      // they turned their mic or webcam on
      onMediaStatusChanged: ({ kind, newStatus }) => {
        if (!newStatus) return;
        if (kind === "audio") receive("audio");
        if (kind === "video" && onScreen.current) receive("video");
      },
    });

  // one request per kind: skip media already arriving or already asked for
  const requesting = useRef(new Set());

  const receive = async (kind) => {
    const arriving = kind === "audio" ? micStream : webcamStream;
    if (arriving || requesting.current.has(kind)) return;
    requesting.current.add(kind);
    try {
      await (kind === "audio" ? consumeMicStreams() : consumeWebcamStreams());
    } catch (error) {
      console.warn(`Could not receive ${kind}:`, error.code, error.message);
    } finally {
      requesting.current.delete(kind);
    }
  };

  useEffect(() => {
    receive("audio");
  }, []);

  return null;
}

Step 3: Stop receiving media you no longer show

When a tile scrolls off the screen, stop receiving that participant's webcam. When it comes back, receive it again. Add this to the tile from Step 2:

const { stopConsumingWebcamStreams } = useParticipant(participantId);

useEffect(() => {
  if (isOnScreen) {
    receive("video");
    return;
  }
  stopConsumingWebcamStreams().catch((error) =>
    console.warn("Could not stop receiving video:", error.code, error.message),
  );
}, [isOnScreen]);

When you stop receiving a participant's webcam, webcamStream becomes null and webcamOn turns false on this device, the same as when they turn it off. To show whether a participant's mic or webcam is on, keep track of onMediaStatusChanged.

note

• All four methods return a Promise. They reject when the request fails.
• They only change what this device receives. To turn a participant's mic or webcam off for everyone, see Remote Participant Media.

Selective subscription works well together with adaptive subscriptions and the other techniques for large rooms.

API Reference

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

• RoomProvider config: autoConsume
• consumeMicStreams()
• consumeWebcamStreams()
• stopConsumingMicStreams()
• stopConsumingWebcamStreams()
• onMediaStatusChanged