ThegetDisplayMedia() method of theMediaDevices interface prompts the user to select and grant permission to capture the contents of a display or portion thereof (such as a window) as aMediaStream.

The resulting stream can then be recorded using theMediaStream Recording API or transmitted as part of aWebRTC session.

SeeUsing the Screen Capture API for more details and an example.

Syntax

getDisplayMedia()getDisplayMedia(options)

Parameters

optionsOptional

An object specifying requirements for the returnedMediaStream.The options forgetDisplayMedia() work in the same as theconstraints for theMediaDevices.getUserMedia() method, although in that case onlyaudio andvideo can be specified.The list of possible option properties forgetDisplayMedia() is as follows:

videoOptional

A boolean or aMediaTrackConstraints instance; the default value istrue.If this option is omitted or set totrue, the returnedMediaStream will contain a video track.SincegetDisplayMedia() requires a video track, if this option is set tofalse the promise will reject with aTypeError.

audioOptional

A boolean or aMediaTrackConstraints instance; the default value isfalse.A value oftrue indicates that the returnedMediaStream will contain an audio track, if audio is supported and available for the display surface chosen by the user.

controllerExperimentalOptional

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

monitorTypeSurfacesExperimentalOptional

An enumerated value specifying whether the browser should offer entire screens in the screen capture options presented to the user alongside tab and window options.This option is intended to protect companies from leakage of private information through employee error when using video conferencing apps.Possible values are:

• include: Hints that the browser should include screen options.
• exclude: Hints that screen options should be excluded.

Note:You cannot setmonitorTypeSurfaces: "exclude" at the same time asdisplaySurface: "monitor" as the two settings are contradictory.Trying to do so will result in thegetDisplayMedia() call failing with aTypeError.

preferCurrentTabNon-standardExperimentalOptional

A boolean; a value oftrue instructs the browser to offer the current tab as the most prominent capture source, that is, 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.

selfBrowserSurfaceExperimentalOptional

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: Hints that the browser should include the current tab in the choices offered for capture.
• exclude: Hints that the current tab should be excluded from the choices.

surfaceSwitchingExperimentalOptional

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 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: Hints that the browser should include the control.
• exclude: Hints that the control should not be shown.

systemAudioExperimentalOptional

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: Hints that the browser should include the system audio in the list of choices.
• exclude: Hints that system audio should be excluded from the choices shown.

windowAudioExperimentalOptional

An enumerated value that hints to the browser what audio sharing option the user should be presented with alongside window sharing options. Possible values are:

• exclude: Hints that audio should not be shareable when a window sharing option is chosen.
• window: Hints that when a window sharing option is chosen, only audio originating from that window should be shared.
• system: Hints that when a window sharing option is chosen, all system audio should be shared.

Return value

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

Exceptions

AbortErrorDOMException

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

InvalidStateErrorDOMException

Thrown if the call togetDisplayMedia() was not made from code running due to atransient activation, such as an event handler.Or if the browser context is not fully active or does not focused.Or if thecontroller options has been already used in creating anotherMediaStream.

NotAllowedErrorDOMException

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

NotFoundErrorDOMException

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

NotReadableErrorDOMException

Thrown 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.

OverconstrainedErrorDOMException

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

TypeError

Thrown if the specifiedoptions include values that are not permitted when callinggetDisplayMedia(), for example avideo property set to false, or if any specifiedMediaTrackConstraints are not permitted.min andexact values are not permitted in constraints used ingetDisplayMedia() calls.

Security

BecausegetDisplayMedia() 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 supportgetDisplayMedia().

• 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 usegetDisplayMedia() 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.

Examples

In the example below astartCapture() method is created, which initiates screen capture given a set of options specified by thedisplayMediaOptions parameter.

const displayMediaOptions = {  video: {    displaySurface: "browser",  },  audio: {    suppressLocalAudioPlayback: false,  },  preferCurrentTab: false,  selfBrowserSurface: "exclude",  systemAudio: "include",  surfaceSwitching: "include",  monitorTypeSurfaces: "include",};async function startCapture(displayMediaOptions) {  let captureStream;  try {    captureStream =      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);  } catch (err) {    console.error(`Error: ${err}`);  }  return captureStream;}

This usesawait to asynchronously wait forgetDisplayMedia() to resolve with aMediaStream 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 usingRTCPeerConnection.addTrack() to add the video track from the stream.

Specifications

Browser compatibility

See also

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