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 and in terms of the source of the audio. 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 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, prevenging 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.

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 Capture
The definition of 'MediaDevices.getDisplayMedia()' in that specification.
Working Draft Initial definition

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung 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 17
Notes
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 whitelist.
IE No support NoOpera ? Safari No support NoWebView Android No support No
Notes
No support No
Notes
Notes API is available, but will always fail with NotAllowedError.
Chrome Android No support NoFirefox Android No support No
Notes
No support No
Notes
Notes API is available, but will always fail with NotAllowedError.
Opera Android Full support YesSafari iOS No support NoSamsung Internet Android ?
Audio capture supportChrome Full support 74
Notes
Full support 74
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.
Edge ? Firefox No support NoIE No support NoOpera ? Safari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android ? Safari iOS No support NoSamsung 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.

See also