Custom ScreenShare Sources - React Native

Use a custom screen share track to control the quality of the screen you share to the live stream.

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.

• toggleScreenShare()
• disableScreenShare()
• enableScreenShare()

Custom Screen Share Track

This feature enables the customization of screenshare streams with predefined encoder configuration (resolution + FPS) for specific use cases, which can then be sent to other hosts and audience members.

How to Create a Custom Screen Share Track ?

• You can create a Video Track using the createScreenShareVideoTrack() method of @videosdk.live/react-native-sdk.
• This method enables the creation of a screen share track with different encoding parameters.
• On Android, the screen capture consent dialog appears when you create the track. If the user declines, the Promise rejects with ERROR_GET_DISPLAY_MEDIA_PERMISSION_DENIED (3016).
• On iOS, enableScreenShare() opens the system broadcast picker, and sharing starts when the user taps Start Broadcast. Your app needs a Broadcast Upload Extension. Follow Create Broadcast Upload Extension in iOS to set it up.

Example

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

let customShareTrack = await createScreenShareVideoTrack({
  // This will accept the  height & FPS of video you want to capture.
  encoderConfig: "h720p_15fps", //  `h360p_30fps` | `h1080p_30fps` // Default : `h720p_15fps`

  // Android only: It will also share the system audio.
  withAudio: true, // false,  Default : false
});

• encoderConfig accepts h360p_30fps, h480p_15fps, h480p_30fps, h720p_5fps, h720p_15fps, h720p_30fps, h1080p_15fps and h1080p_30fps.
• withAudio works on Android 10 and later. The system audio is mixed into your microphone track, so muting the mic mutes both. On iOS, it has no effect.

createScreenShareVideoTrack() also takes multiStream. See Custom Tracks for every parameter.

How to Setup a Custom Screen Share Track ?

During the live stream, you can update the screenshare track by passing the CustomStreamTrack into enableScreenShare() or toggleScreenShare() methods from the useRoom hook.

Sharing has started when onStreamEnabled() of useParticipant() fires with the share stream.

note

Make sure to call the disableScreenShare() method before you create a new track. While you are sharing, enableScreenShare() rejects with ERROR_ALREADY_IN_REQUESTED_STATE (3054), and toggleScreenShare() turns screen share off without using the track.

Example

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

const RoomControls = () => {
  const {
    isScreenSharing,
    enableScreenShare,
    disableScreenShare,
    toggleScreenShare,
  } = useRoom();

  const handleToggleScreenShare = async () => {
    if (isScreenSharing) {
      try {
        await toggleScreenShare();
      } catch (err) {
        console.error("toggleScreenShare failed:", err);
      }
    } else {
      try {
        let customTrack = await createScreenShareVideoTrack({
          encoderConfig: "h720p_15fps",
        });

        await toggleScreenShare(customTrack);
      } catch (err) {
        console.error("toggleScreenShare failed:", err);
      }
    }
  };

  const handleEnableScreenShare = async () => {
    if (isScreenSharing) {
      try {
        await disableScreenShare();
      } catch (err) {
        console.error("disableScreenShare failed:", err);
      }
    }

    try {
      let customTrack = await createScreenShareVideoTrack({
        encoderConfig: "h720p_15fps",
      });

      await enableScreenShare(customTrack);
    } catch (err) {
      console.error("enableScreenShare failed:", err);
    }
  };

  return (
    <>
      <TouchableOpacity onPress={handleToggleScreenShare}>
        <Text>Toggle ScreenShare</Text>
      </TouchableOpacity>
      <TouchableOpacity onPress={handleEnableScreenShare}>
        <Text>Enable ScreenShare</Text>
      </TouchableOpacity>
    </>
  );
};

API Reference

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

• Custom Screen Share Track