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
.
To start capturing video from the screen, you call getDisplayMedia()
on 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.
The Screen Capture API also has features that limit the part of the screen captured in the stream:
- The Element Capture API restricts the captured region to a specified rendered DOM element and its descendants.
- The Region Capture API crops the captured region to the area of the screen in which a specified DOM element is rendered.
See Using the Element Capture and Region Capture APIs to learn more.
Interfaces
BrowserCaptureMediaStreamTrack
-
Represents a single video track; extends the
MediaStreamTrack
class with methods to limit the part of a self-capture stream (for example, a user's screen or window) that is captured. CaptureController
-
Provides methods that can be used to further manipulate a capture session separate from its initiation via
MediaDevices.getDisplayMedia()
. ACaptureController
object is associated with a capture session by passing it into agetDisplayMedia()
call as the value of the options object'scontroller
property. CropTarget
-
Provides a static method,
fromElement()
, which returns aCropTarget
instance that can be used to crop a captured video track to the area in which a specified element is rendered. RestrictionTarget
-
Provides a static method,
fromElement()
, which returns aRestrictionTarget
instance that can be used to restrict a captured video track to a specified DOM element.
Additions to the 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.displaySurface
-
A
ConstrainDOMString
indicating what type of display surface is to be captured. The value is one ofbrowser
,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. MediaTrackConstraints.suppressLocalAudioPlayback
-
Controls whether the audio playing in a tab will continue to be played out of a user's local speakers when the tab is captured, or whether it will be suppressed. A value of
true
indicates that it will be suppressed.
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
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. MediaTrackSettings.suppressLocalAudioPlayback
-
A boolean value, which is
true
if the audio being captured is not played out of the user's local speakers.
MediaTrackSupportedConstraints
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
. MediaTrackSupportedConstraints.suppressLocalAudioPlayback
-
A boolean, which is
true
if the current environment supports the constraintMediaTrackConstraints.suppressLocalAudioPlayback
.
Permissions Policy validation
User agents that support Permissions Policy (either using the HTTP Permissions-Policy
header or the <iframe>
attribute allow
) can specify a desire to use the Screen Capture API using the directive display-capture
:
<iframe allow="display-capture" src="/some-other-document.html">…</iframe>
The default allowlist is self
, which lets any content within the same origin use Screen Capture.
Specifications
Specification |
---|
Screen Capture |
Element Capture |
Region Capture |
Browser compatibility
api.MediaDevices.getDisplayMedia
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
getDisplayMedia() | ||||||||||||
Audio capture support | ||||||||||||
controller option | ||||||||||||
monitorTypeSurfaces option | ||||||||||||
preferCurrentTab option | ||||||||||||
selfBrowserSurface option | ||||||||||||
surfaceSwitching option | ||||||||||||
systemAudio option |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- Partial support
- Partial support
- No support
- No support
- Experimental. Expect behavior to change in the future.
- Non-standard. Check cross-browser support before using.
- See implementation notes.
- Has more compatibility info.
api.CropTarget
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
CropTarget | ||||||||||||
fromElement() static method |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- No support
- No support
- Experimental. Expect behavior to change in the future.
api.RestrictionTarget
Report problems with this compatibility data on GitHubdesktop | mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
RestrictionTarget | ||||||||||||
fromElement() static method |
Legend
Tip: you can click/tap on a cell for more information.
- Full support
- Full support
- In development. Supported in a pre-release version.
- In development. Supported in a pre-release version.
- No support
- No support
- Experimental. Expect behavior to change in the future.