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
.
To start capturing video from the screen, you call getDisplayMedia()
on the instance of Media
navigator.mediaDevices
:
captureStream = await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
The Promise
returned by getDisplayMedia()
resolves to a MediaStream
which streams the captured media.
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 theMediaDevices
interface. Similar togetUserMedia()
, this method creates a promise that resolves with aMediaStream
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 ofapplication
,browser
,monitor
, orwindow
. 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
, ornever
. MediaTrackSettings.displaySurface
- A string indicating what type of display surface is currently being captured. The value is one of
application
,browser
,monitor
, orwindow
. 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 theMediaTrackConstraints.cursor
constraint. MediaTrackSupportedConstraints.displaySurface
- A Boolean which is
true
if the current environment supports theMediaTrackConstraints.displaySurface
constraint. MediaTrackSupportedConstraints.logicalSurface
- A Boolean which is
true
if the current environment supports the constraintMediaTrackConstraints.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 arealways
,motion
, andnever
. 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 valuesapplication
,browser
,monitor
, andwindow
.
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 directive display-capture
:
<iframe allow="display-capture" src="/some-other-document.html">
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
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
getDisplayMedia()
|
Chrome Full support 72 Full support 72 No support 70 — 72 Notes' Available as a member of |
Edge Full support 79 Full support 79 Full support 17 Notes' Available as a member of |
Firefox Full support 66 Full support 66 No support 33 — 66 Notes' Since Firefox 33 you can capture screen data using |
IE
No support No |
Opera Full support 60 Full support 60 No support 57 — 60 Notes' Available as a member of |
Safari
Full support 13 |
WebView Android No support No No support No Notes' API is available, but will always fail with |
Chrome Android
No support No |
Firefox Android No support No No support No Notes' API is available, but will always fail with |
Opera Android
No support No |
Safari iOS
No support No |
Samsung Internet Android
No support No |
Audio capture support |
Chrome Full support 74 Full support 74 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 Full support ≤79 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.
See also
Screen Capture API by Mozilla Contributors is licensed under CC-BY-SA 2.5.