MediaDevices: getDisplayMedia() method
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
The getDisplayMedia()
method of the MediaDevices
interface 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
getDisplayMedia()
getDisplayMedia(options)
Parameters
options
Optional-
An optional object specifying requirements for the returned
MediaStream
. The options forgetDisplayMedia()
work in the same as the constraints for theMediaDevices.getUserMedia()
method, although in that case onlyaudio
andvideo
can be specified. The list of possible option properties forgetDisplayMedia()
is as follows:video
Optional-
A boolean or a
MediaTrackConstraints
instance; the default value istrue
. If this option is omitted or set totrue
, the stream will contain a video track A value oftrue
indicates that the returnedMediaStream
will contain a video track. SincegetDisplayMedia()
requires a video track, if this option is set tofalse
the promise will reject with aTypeError
. audio
Optional-
A boolean or a
MediaTrackConstraints
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. controller
Experimental Optional-
A
CaptureController
object instance containing methods that can be used to further manipulate the capture session if included. monitorTypeSurfaces
Optional-
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
, which hints that the browser should include screen options, andexclude
, which hints that they should be excluded. A default value is not mandated by the spec; see the Browser compatibility section for browser-specific defaults.Note: You cannot set
monitorTypeSurfaces: "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
. preferCurrentTab
Non-standard Experimental 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
Experimental 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, andexclude
, 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
Experimental 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, andexclude
, 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
Experimental 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, andexclude
, 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. monitorTypeSurfaces
Experimental Optional-
An enumerated value specifying whether the application would like the user agent to offer the user the option to choose display surfaces whose type is monitor. Possible values are
include
, which hints that the browser should include the display surfaces whose type is monitor, andexclude
, 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.
Note: See the article Capabilities, constraints, and settings for a lot more detail on how these options work.
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 audio sources supported. Check the compatibility table for details for each browser.
Exceptions
AbortError
DOMException
-
Thrown if an error or failure does not match any of the other exceptions listed here.
InvalidStateError
DOMException
-
Thrown if the call to
getDisplayMedia()
was not made from code running due to a transient 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
. NotAllowedError
DOMException
-
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 a Permissions Policy).
NotFoundError
DOMException
-
Thrown if no sources of screen video are available for capture.
NotReadableError
DOMException
-
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.
OverconstrainedError
DOMException
-
Thrown if, after creating the stream, applying any specified constraints fails because no compatible stream could be generated.
TypeError
-
Thrown if the specified
options
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
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.
Examples
In the example below a startCapture()
method is created, which initiates
screen capture given a set of options specified by the displayMediaOptions
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 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.
Note: The Screen sharing controls demo provides a complete implementation that allows you to create a screen capture with your choice of getDisplayMedia()
constraints and options.
Specifications
Specification |
---|
Screen Capture # dom-mediadevices-getdisplaymedia |
Browser compatibility
BCD tables only load in the browser
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