# Screen Sharing

Control and configure screen sharing in your application.

## Best Practices

- Check for `screenshare` capability before showing screen share controls.
- Configure appropriate bitrate and framerate based on content type (presentation vs video).
- Use `screenShare.setSettings()` before enabling to optimize for your use case.
- Handle browser compatibility, especially for screen share audio on different platforms.

>
> **Note:** Screen Sharing is supported only on Desktop browsers. For more details,
> please refer to the [Browser Compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture#browser_compatibility) section.
>

For a user to be able to share their screen, they must have the `screenshare` capability
(provided through the `Screenshare` permission) configured for the call they are in.

Screen sharing can be enabled or disabled on the dashboard for your call type:

![Screenshot shows screensharing dashboard setting](https://getstream.io/docs-assets/images/b5bd0fcec9e5.png)

## Start/Stop Screen Sharing

```ts
await call.screenShare.toggle();

// or
await call.screenShare.enable();
await call.screenShare.disable();

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

const { useScreenShareState } = useCallStateHooks();
const { screenShare } = useScreenShareState();
await screenShare.toggle();
```

## Screen Sharing Status

Here is how you can access the status of screen sharing:

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

call.screenShare.state.status; // enabled, disabled or undefined

// or, if you want to subscribe to changes
const { useScreenShareState } = useCallStateHooks();
const { status } = useScreenShareState();

console.log("Screen sharing is:", status === "enabled" ? "active" : "inactive");
```

## Screen Sharing Settings

The behavior of the screen share video track can be customized, and a few parameters can be set:

```ts
call.screenShare.setSettings({
  maxFramerate: 15, // will be clamped between 1 and 15 fps
  maxBitrate: 1500000, // will use at most 1.5Mbps
});

await call.screenShare.enable();
```

## Screen Sharing optimization hints

### Content Hint

Optimize shared content by setting the `contentHint` based on content type:

- **`motion`** - Higher fps for video content
- **`detail`** - Sharp rendering for presentations, images, fine art
- **`text`** - Optimized for text-heavy content
- **`""`** (empty) - General content (default)

See the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack/contentHint) for details.

```typescript
// one of "motion", "detail", "text", or "" (default)
call.screenShare.setSettings({ contentHint: "motion" });
await call.screenShare.enable();
```

>
> **Note:** Set `contentHint` before enabling screen sharing.
>

### Resolution and frame rate

Default screen share is capped at `2560x1440` at `30` fps, balancing quality, bandwidth, and CPU usage.

Adjust limits as needed:

```ts
// will lift the limit up to 4k@30fps.
call.screenShare.setDefaultConstraints({
  video: {
    width: { max: 3840 },
    height: { max: 2160 },
    frameRate: { ideal: 30 },
  },
});

// will put the limit down to 1080p@25fps.
call.screenShare.setDefaultConstraints({
  video: {
    width: { max: 1920 },
    height: { max: 1080 },
    frameRate: { ideal: 25 },
  },
});

// will remove the limitations completely,
// and will use the system native resolution
call.screenShare.setDefaultConstraints({ video: true });

// constraints need to be updated before enabling the screenshare
await call.screenShare.enable();
```

>
> **Warning:** Modifying constraints is an advanced operation. Aggressive values may cause performance degradation, especially on lower-end devices.
>

## Render Screen Share

Our SDK provided [`ParticipantView`](https://getstream.io/video/docs/react/v2/ui-components/participants/participant-view/) component can automatically render the screen share video track.

## Screen Share Audio

### Start/Stop Screen Share Audio

```ts
// enable it
call.screenShare.enableScreenShareAudio();

// publish video and audio (if available, and supported by the browser)
await call.screenShare.enable();

// disable it
call.screenShare.disableScreenShareAudio();
```

### Play Screen Share Audio

Our SDK provided [`ParticipantView`](https://getstream.io/video/docs/react/v2/ui-components/participants/participant-view/) component can automatically play the screen share audio track.

### Stereo Screen Share Audio

By default, Screen Share Audio will be published in higher bitrate and in stereo, when the device supports it.
Similar to the [microphone hi-fi modes](https://getstream.io/video/docs/react/v2/guides/camera-and-microphone/#hi-fi-and-stereo-audio) one can select one of the following modes:

- `VOICE_STANDARD_UNSPECIFIED`: standard quality mono audio, suitable for sharing speech
- `VOICE_HIGH_QUALITY`: high-quality mono audio, suitable for podcasts
- `MUSIC_HIGH_QUALITY`: high-quality stereo audio, suitable for sharing music content (default)

To update the audio mode, use the `setAudioBitrateProfile` method exposed on the `screenShare` object:

```tsx
import { useCallStateHooks, SfuModels } from "@stream-io/video-react-sdk";

const { useScreenShareState } = useCallStateHooks();
const { screenShare } = useScreenShareState();

await screenShare.setAudioBitrateProfile(
  SfuModels.AudioBitrateProfile.VOICE_HIGH_QUALITY,
);
```

### Caveats

Screen Share Audio has limited support across browsers and platforms.
For most up-to-date information, please take a look at [Browser Compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture#browser_compatibility).

In addition to that, there are a [few caveats](https://caniuse.com/?search=getDisplayMedia) that you should be aware of:

- On Windows, the entire system audio can be captured, but on MacOS and Linux, only the audio of a tab can be captured.

---

For the most recent version of this documentation, visit [https://getstream.io/video/docs/react/v2/guides/screensharing/](https://getstream.io/video/docs/react/v2/guides/screensharing/).