Docs
Get startedGuidesReferenceBlogChangelog
  1. Home
  2. Reference Docs
  3. Daily JS
  4. Instance Methods
  5. startScreenShare()

startScreenShare()

startScreenShare( { displayMediaOptions?, mediaStream?, screenVideoSendSettings? } )

Compatibility:
Prebuilt
Custom

Starting in daily-js 0.46.0, the format of the options passed in to startScreenShare have changed to support greater flexibility. Be sure to update your options. Most legacy options have simply moved and are now nested under the displayMediaOptions.

Starts a screen share from the local participant. If there is no meeting, or this is not a browser that supports screen sharing, or enable_screenshare is set to false for either the room or the meeting token, this method does nothing.

There's no way to know if the user ignores or cancels the browser's screen share confirmation dialog.

To confirm that screen sharing started, listen for participant-updated events and check the local user's tracks object for the screenVideo track information.

Returns null.

Screen share track constraints, media options, and encodings can be customized by providing an optional displayMediaOptions and screenVideoSendSettings object.

displayMediaOptions

Customize the video track constraints or screen share options by providing a displayMediaOptions object.

Web

If you're building an application for the web, you can specify the following options to select and configure a screen to share"

  • audio (boolean | MediaTrackConstraints): A boolean or a MediaTrackConstraints instance; the default value is true. For Chrome or Chromium-based browsers, a value of true results in an option to "Share tab audio" when selecting to share a browser tab. A value of false results in no option to "Share tab audio."
  • video (boolean | MediaTrackConstraints): A boolean or a MediaTrackConstraints instance; the default value is true. If this option is omitted or set to true, the stream will contain a video track. A value of true indicates that the returned MediaStream will contain a video track. Since getDisplayMedia() requires a video track, if this option is set to false the promise will reject with a TypeError.
  • selfBrowserSurface ('include' | 'exclude'): Specifies whether the browser should allow the user to select the current tab for capture. When set to 'include' the currently selected browser tab is available to share. When set to 'exclude', the currently selected browser tab is unavailable to share. Setting the value to 'exclude' avoids the "hall of mirrors" effect. The default value is 'exclude'. Supported on Chrome and Chromium-based browsers only.
  • surfaceSwitching ('include' | 'exclude'): Specifies whether users can dynamically switch between Chrome tabs. When set to 'include', the browser will display a button, allowing users to switch tabs while screen sharing. When set to 'exclude', the browser will hide that button. The default value is 'include'. Supported on Chrome and Chromium-based browsers only.
  • systemAudio ('include' | 'exclude'): An enumerated value specifying whether the browser should include the system audio among the possible audio sources offered to the user. Possible values are 'include', which hints that the browser should include the system audio in the list of choices, and 'exclude', which hints that it should be excluded. Supported on Chrome and Chromium-based browsers only.

Electron

If you're building an Electron app, you can specify the following options to select and configure a screen to share:

  • audio (boolean): A value of true indicates that the returned MediaStream will contain an audio track, if audio is supported and available for the display surface chosen by the user.
  • video:
    • maxWidth (number): Specify the max width of the screen share track.
    • maxHeight (number): Specify the max height of the screen share track.
  • chromeMediaSourceId (string): Specify chromeMediaSourceId to set the screen to be shared.

mediaStream

In general, we do not recommend you perform your own getDisplayMedia(), as our API is fully customizable and handles all of the screen share nuances for you, like cross-browser error handling. That said, we understand that sometimes this is not an option and there are use cases where you simply want to provide a stream already in hand. This field allows for that. Note: if you provide this field the displayMediaOptions field is moot.

If you provide the mediaStream, you remain responsible for stopping the track. See the snippet below for how to start/stop with a custom source.

Note: If the user uses a browser-provided UI for stopping the screenshare, Daily will do the right thing and clean up the screen track and update the state.

screenVideoSendSettings

Customize the screen share send settings by providing a screenVideoSendSettings object. The screenVideoSendSettings takes the same sendSettings object provided to the updateSendSettings() method in order to specify a preset or to provide a custom encoding. See the updateSendSettings() docs for more details.

Example

Previous
Next