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 returnedMediaStream
. SincegetDisplayMedia()
requires a video track, the returned stream will have one even if no video track is expressly requested by theconstraints
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: thedocument
in whose contextgetDisplayMedia()
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 callinggetDisplayMedia()
. These unsupported constraints areadvanced
and any constraints which in turn have a member namedmin
orexact
.
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 Capture The definition of 'MediaDevices.getDisplayMedia()' in that specification. |
Working Draft | Initial definition |
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
getDisplayMedia() | Chrome
Full support
72
| Edge
Full support
79
| Firefox
Full support
66
| IE No support No | Opera
Full support
60
| Safari Full support 13 | 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 |
Audio capture support | Chrome
Full support
74
| Edge
Full support
≤79
| 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.
See also
- Screen Capture API
- Using the Screen Capture API
- Media Capture and Streams API
- WebRTC API
getUserMedia()
: Capturing media from a camera and/or microphone