Web/API/MediaDevices/getDisplayMedia

The MediaDevices interface's getDisplayMedia() method prompts the user to select and grant permission to capture the contents of a display or portion thereof (such as a window) as a MediaStream. The resulting stream can then be recorded using the MediaStream Recording API or transmitted as part of a WebRTC session.

See Using the Screen Capture API for more details and an example.

Syntax

var promise = navigator.mediaDevices.getDisplayMedia(constraints);

Parameters

constraints Optional: An optional MediaStreamConstraints object specifying requirements for the returned MediaStream. Since getDisplayMedia() requires a video track, the returned stream will have one even if no video track is expressly requested by the constraints object.

Return value

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.

Note: Browser support for audio tracks varies, both in terms of whether or not they're supported at all by the media recorder and in terms of the which audio source or sourcoes are supported. Check the compatibility table for details for each browser.

Exceptions

Rejections of the returned promise are made by passing a DOMException error object to the promise's failure handler. Possible errors are:

AbortError: An error or failure that doesn't match any of the other exceptions below occurred.
InvalidStateError: 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: Permission to access a screen area was denied by the user, or the current browsing instance is not permitted access to screen sharing.
NotFoundError: No sources of screen video are available for capture.
NotReadableError: The user selected a screen, window, tab, or other source of screen data, but a hardware or operating system level error or lockout occurred, preventing the sharing of the selected source.
OverconstrainedError: After creating the stream, applying the specified constraints fails because no compatible stream could be generated.
TypeError: The specified constraints include constraints which are not permitted when calling getDisplayMedia(). These unsupported constraints are advanced and any constraints which in turn have a member named min or exact.

Usage notes

Privacy and security

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 constraints can't be used to limit the options available to the user. Instead, they must be applied after the user chooses a source, in order to generate output that matches the constraints.
The go-ahead permission to use getDisplayMedia() cannot be persisted for reuse. The user must be prompted for permission every time.
The call to getDisplayMedia() must be made from code which is running in response to a user action, such as in an event handler.
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.

Example

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 the form of a MediaStreamConstraints object which specifies the preferred stream configuration and the display surface from which video is to be captured.

async function startCapture(displayMediaOptions) {
  let captureStream = null;

  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.

Specifications

Specification	Status	Comment
Screen CaptureThe definition of 'MediaDevices.getDisplayMedia()' in that specification.	Working Draft	Initial definition

Browser compatibility

Update compatibility data on GitHub

	Desktop						Mobile
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	Android webview	Chrome for Android	Firefox for Android	Opera for Android	Safari on iOS	Samsung Internet
`getDisplayMedia()`	Chrome Full support 72 Full support 72 No support 70 — 72 Notes' Disabled' Notes' Available as a member of `Navigator` instead of `MediaDevices` in Chrome 70 and 71. Disabled' From version 70 until version 72 (exclusive): this feature is behind the `Experimental Web Platform features` preference (needs to be set to `Enabled`). To change preferences in Chrome, visit chrome://flags.	Edge Full support 79 Full support 79 Full support 17 Notes' Notes' Available as a member of `Navigator` instead of `MediaDevices`.	Firefox Full support 66 Full support 66 No support 33 — 66 Notes' Notes' Since Firefox 33 you can capture screen data using `getUserMedia()`, with a `video` constraint called `mediaSource`. Prior to 52 it relied on a client-configurable list of allowed sites.	IE No support No	Opera Full support 60 Full support 60 No support 57 — 60 Notes' Disabled' Notes' Available as a member of `Navigator` instead of `MediaDevices` in Opera 57 and 58. Disabled' From version 57 until version 60 (exclusive): this feature is behind the `Experimental Web Platform features` preference (needs to be set to `Enabled`).	Safari Full support 13	WebView Android No support No Notes' No support No Notes' Notes' API is available, but will always fail with `NotAllowedError`.	Chrome Android No support No	Firefox Android No support No Notes' No support No Notes' Notes' API is available, but will always fail with `NotAllowedError`.	Opera Android No support No	Safari iOS No support No	Samsung Internet Android No support No
Audio capture support	Chrome Full support 74 Notes' Full support 74 Notes' Notes' On Windows and Chrome OS the entire system audio can be captured, but on Linux and Mac only the audio of a tab can be captured.	Edge Full support ≤79 Notes' Full support ≤79 Notes' Notes' On Windows, the entire system audio can be captured, but on Linux and Mac only the audio of a tab can be captured.	Firefox No support No	IE No support No	Opera ?	Safari No support No	WebView Android No support No	Chrome Android No support No	Firefox Android No support No	Opera Android No support No	Safari iOS No support No	Samsung Internet Android No support No

Legend

Full support: Full support
No support: No support
Compatibility unknown: Compatibility unknown
See implementation notes.': See implementation notes.
User must explicitly enable this feature.': User must explicitly enable this feature.