Screen Capture API

The Screen Capture API introduces additions to the existing Media Capture and Streams API to let the user select a screen or portion of a screen (such as a window) to capture as a media stream. This stream can then be recorded or shared with others over the network.

Screen Capture API concepts and usage

The Screen Capture API is relatively simple to use. Its sole method is MediaDevices.getDisplayMedia(), whose job is to ask the user to select a screen or portion of a screen to capture in the form of a MediaStream.

See the article Using the Screen Capture API for a more in-depth look at how to use the API to capture screen contents as a stream.

Additions to existing interfaces

The Screen Capture API doesn't have any interfaces of its own; instead, it adds one method to the existing MediaDevices interface.

MediaDevices interface

MediaDevices.getDisplayMedia()
The getDisplayMedia() method is added to the MediaDevices interface. Similar to getUserMedia(), this method creates a promise that resolves with a MediaStream containing the display area selected by the user, in a format that matches the specified options.

Additions to existing dictionaries

The Screen Capture API adds properties to the following dictionaries defined by other specifications.

MediaTrackConstraints

MediaTrackConstraints.cursor
A ConstrainDOMString indicating whether or not the cursor should be included in the captured display surface's stream, and if it should always be visible or if it should only be visible while the mouse is in motion.
MediaTrackConstraints.displaySurface
A ConstrainDOMString indicating what type of display surface is to be captured. The value is one of application, browser, monitor, or window.
MediaTrackConstraints.logicalSurface
Indicates whether or not the video in the stream represents a logical display surface (that is, one which may not be entirely visible onscreen, or may be completely offscreen). A value of true indicates a logical display surface is to be captured.

MediaTrackSettings

MediaTrackSettings.cursor
A string which indicates whether or not the display surface currently being captured includes the mouse cursor, and if so, whether it's only visible while the mouse is in motion or if it's always visible. The value is one of always, motion, or never.
MediaTrackSettings.displaySurface
A string indicating what type of display surface is currently being captured. The value is one of application, browser, monitor, or window.
MediaTrackSettings.logicalSurface
A Boolean value which is true if the video being captured doesn't directly correspond to a single onscreen display area.

MediaTrackSupportedConstraints

MediaTrackSupportedConstraints.cursor
A Boolean which is true if the user agent and device support the MediaTrackConstraints.cursor constraint.
MediaTrackSupportedConstraints.displaySurface
A Boolean which is true if the current environment supports the MediaTrackConstraints.displaySurface constraint.
MediaTrackSupportedConstraints.logicalSurface
A Boolean which is true if the current environment supports the constraint MediaTrackConstraints.logicalSurface.

Dictionaries

The following dictionaries are defined by the Screen Capture API.

CursorCaptureConstraint
An enumerated string type used to provide the value for the cursor property for the settings and constraints. The possible values are always, motion, and never.
DisplayCaptureSurfaceType
An enumerated string type which is used to identify the kind of display surface to capture. This type is used for the displaySurface property in the constraints and settings objects, and has the possible values application, browser, monitor, and window.

Feature Policy validation

User agents that support Feature Policy (either using HTTP's Feature-Policy header or the <iframe> attribute allow) can specify a desire to use the Screen Capture API using the policy control string display-capture.

The default allow list is self, which lets the any content within the document use Screen Capture.

See Using Feature Policy for a more in-depth explanation of how Feature Policy is used.

Specifications

Specification Status Comment
Screen Capture Working Draft Initial definition

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidEdge MobileFirefox 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 NoEdge Mobile Full support YesFirefox Android No support No
Notes
No support No
Notes
Notes API is available, but will always fail with NotAllowedError.
Opera Android ? Safari iOS No support NoSamsung Internet Android ?
Audio capture supportChrome No support NoEdge ? Firefox No support NoIE No support NoOpera ? Safari No support NoWebView Android No support NoChrome Android No support NoEdge Mobile ? Firefox 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

Document Tags and Contributors

Contributors to this page: mdnwebdocs-bot, Jib, Sheppy
Last updated by: mdnwebdocs-bot,