MediaDevices: getDisplayMedia() method

options Optional

An optional object specifying requirements for the returned MediaStream. The options for getDisplayMedia() work in the same as the constraints for the MediaDevices.getUserMedia() method, although in that case only audio and video can be specified. The list of possible option properties for getDisplayMedia() is as follows:

video Optional

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.

audio Optional

A boolean or a MediaTrackConstraints instance; the default value is false. 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.

controller Optional

A CaptureController object instance containing methods that can be used to further manipulate the capture session if included.

preferCurrentTab Non-standard Optional

A boolean; a value of true instructs the browser to offer the current tab as the most prominent capture source, i.e. as a separate "This Tab" option in the "Choose what to share" options presented to the user. This is useful as many app types generally just want to share the current tab. For example, a slide deck app might want to let the user stream the current tab containing the presentation to a virtual conference. A default value is not mandated by the spec; see the Browser compatibility section for browser-specific defaults.

selfBrowserSurface Optional

An enumerated value specifying whether the browser should allow the user to select the current tab for capture. This helps to avoid the "infinite hall of mirrors" effect experienced when a video conferencing app inadvertently shares its own display. Possible values are include, which hints that the browser should include the current tab in the choices offered for capture, and exclude, which hints that it should be excluded. A default value is not mandated by the spec; see the Browser compatibility section for browser-specific defaults.

surfaceSwitching Optional

An enumerated value specifying whether the browser should display a control to allow the user to dynamically switch the shared tab during screen-sharing. This is much more convenient than having to go through the whole sharing process again each time a user wants to switch the shared tab. Possible values are include, which hints that the browser should include the control, and exclude, which hints that it should not be shown. A default value is not mandated by the spec; see the Browser compatibility section for browser-specific defaults.

systemAudio Optional

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. A default value is not mandated by the spec; see the Browser compatibility section for browser-specific defaults.

A Promise that resolves to a MediaStream containing a video track whose contents come from a user-selected screen area, as well as an optional audio track.

AbortError DOMException

Returned if an error or failure does not match any of the other exceptions listed here.

InvalidStateError DOMException

Returned if the call to getDisplayMedia() was not made from code running due to a user action, such as an event handler. Another potential cause for this event: the document in whose context getDisplayMedia() was called is not fully active; for example, perhaps it is not the frontmost tab.

NotAllowedError DOMException

Returned if the permission to access a screen area was denied by the user (for example by a Permissions Policy), or the current browsing instance is not permitted access to screen sharing.

NotFoundError DOMException

Returned if no sources of screen video are available for capture.

NotReadableError DOMException

Returned if the user selected a screen, window, tab, or another source of screen data, but a hardware or operating system level error or lockout occurred, preventing the sharing of the selected source.

OverconstrainedError DOMException

Returned if, after creating the stream, applying any specified constraints fails because no compatible stream could be generated.

TypeError

Returned if the specified options include values that are not permitted when calling getDisplayMedia(), for example a video property set to false, or if any specified MediaTrackConstraints are not permitted. min and exact values are not permitted in constraints used in MediaDevices.getDisplayMedia() calls.

Because getDisplayMedia() could be used in nefarious ways, it can be a source of significant privacy and security concerns. For that reason, the specification details measures browsers are required to take in order to fully support getDisplayMedia().

• The specified options can't be used to limit the choices available to the user. Instead, they must be applied after the user chooses a source, in order to generate output that matches the options.
• The go-ahead permission to use getDisplayMedia() cannot be persisted for reuse. The user must be prompted for permission every time.
• Transient user activation is required. The user has to interact with the page or a UI element in order for this feature to work.
• Browsers are encouraged to provide a warning to users about sharing displays or windows that contain browsers, and to keep a close eye on what other content might be getting captured and shown to other users.

In the example below, a startCapture() method is created which initiates screen capture given a set of options specified by the displayMediaOptions parameter. The options are specified in an object which specifies the preferred stream configuration and the display surface from which video is to be captured.

async function startCapture(displayMediaOptions) {
  let captureStream;

  try {
    captureStream = await navigator.mediaDevices.getDisplayMedia(
      displayMediaOptions
    );
  } catch (err) {
    console.error(`Error: ${err}`);
  }
  return captureStream;
}

This uses await to asynchronously wait for getDisplayMedia() to resolve with a MediaStream which contains the display contents as requested by the specified options. The stream is then returned to the caller for use, perhaps for adding to a WebRTC call using RTCPeerConnection.addTrack() to add the video track from the stream.

• Screen Capture API
• Using the Screen Capture API
• Media Capture and Streams API
• WebRTC API
• getUserMedia(): Capturing media from a camera and/or microphone