General concepts of screen sharing

You can publish a stream that uses a video view of your screen (instead of a camera) as the source.

A client connected to the session can subscribe to the stream (and view it) as they would subscribe to a stream that uses a camera as the source.

Publishing a stream with a screen-sharing source

To publish a screen-sharing stream, set the videoSource property of the OTPublisher properties prop to "screen":

<OTPublisher
  properties={{
    videoSource: 'screen',
  }}
/>

The screen-sharing stream will capture video from the entire view of application. For this reason, you may want to disable subscribers in the local client when publishing a stream-sharing stream (to prevent them from appearing in the published stream).

Determining the video type ("screen" or "camera") for a stream

You can subscribe to a stream that uses a screen-sharing video source in the same way that you subscribe to a stream that uses a camera as the source. See Subscribing to streams.

You can detect that a stream is a screen-sharing stream, by checking the videoType property of the event object in the OTSession streamCreated event. For a screen-sharing stream, this property is set to "screen":

<OTSession
  applicationId="the API key"
  sessionId="the session ID"
  token="the token"
  eventHandlers={{
    streamCreated: event => {
      console.log(event.videoType, 'stream created', event.streamId);
    }
  }}>
  { /* ... */ }
</OTSession>

The OTSession object dispatches a streamPropertyChanged event when the dimensions of another client's stream changes. This can happen when the publishing client resizes a window being shared (such as a browser window in an app using the Vonage Video web client SDK). The changedProperty property of the event object is set to "videoDimensions". The stream.height and stream.width property of the event object are the new width and height of the video.

<OTSession
  applicationId="the API key"
  sessionId="the session ID"
  token="the token"
  eventHandlers={{
    streamPropertyChanged: event => {
      console.log(event.stream.streamId, 'stream property', event.changedProperty, 'changed:', event.stream.height, event.stream.width);
    }
  }}>
  { /* ... */ }
</OTSession>

You may use the video dimensions and videoType details for streams to adjust the size or dimensions of their corresponding subscribers in the UI. For details on customizing the layout of subscribers in the UI, see Subscribing to streams.

Subscribing to screen-sharing streams

The Stream object contains a videoType property. This can be set to one of the following values

  • "camera" — a standard video stream that uses a camera as the video source
  • "screen" — a screen sharing video stream
  • "custom" — a stream published by a web client using an HTML VideoTrack element as the video source
  • undefined — a stream is voice-only (see the Voice-only guide)

This property can change if a stream published from a mobile device changes from a camera to a screen-sharing video type. When the video type changes, the Session object dispatches a streamPropertyChanged event.

The following code subscribes to streams and adds them to different HTML DIV container elements, based on the video type:

<div id="people"></div>
<div id="screens"></div>
<script>
session.on('streamCreated', function(event) {
  var subOptions = {insertMode: 'append'};
  if(event.stream.videoType === 'screen') {
    session.subscribe(event.stream, 'screens', subOptions);
  } else {
    session.subscribe(event.stream, 'people', subOptions);
  }
});
</script>