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 main method isMediaDevices.getDisplayMedia(), whose job is to ask the user to select a screen or portion of a screen to capture in the form of aMediaStream.

To start capturing video from the screen, you callgetDisplayMedia() onnavigator.mediaDevices:

captureStream =  await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);

ThePromise returned bygetDisplayMedia() resolves to aMediaStream which streams the captured display surface.

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

Screen capture extensions

The Screen Capture API has additional features that extend its capabilities:

Limiting the screen area captured in the stream

• TheElement Capture API restricts the captured region to a specified rendered DOM element and its descendants.
• TheRegion Capture API crops the captured region to the area of the screen in which a specified DOM element is rendered.

SeeUsing the Element Capture and Region Capture APIs to learn more.

Controlling the captured screen area

TheCaptured Surface Control API allows the capturing application to provide limited control over the captured display surface, for example zooming and scrolling its contents.

SeeUsing the Captured Surface Control API to learn more.

Interfaces

BrowserCaptureMediaStreamTrack

Represents a single video track; extends theMediaStreamTrack 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 captured display surface (captured viaMediaDevices.getDisplayMedia()). ACaptureController object is associated with a captured display surface 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()

ThegetDisplayMedia() 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

AConstrainDOMString 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 oftrue 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 oftrue 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 ofalways,motion, ornever.

MediaTrackSettings.displaySurface

A string indicating what type of display surface is currently being captured. The value is one ofbrowser,monitor, orwindow.

MediaTrackSettings.logicalSurface

A boolean value, which istrue if the video being captured doesn't directly correspond to a single onscreen display area.

MediaTrackSettings.suppressLocalAudioPlayback

A boolean value, which istrue if the audio being captured is not played out of the user's local speakers.

MediaTrackSettings.screenPixelRatio

A number representing the ratio of the physical size of a pixel on the captured display surface (displayed at its physical resolution) to the logical size of a CSS pixel on the capturing screen (displayed at its logical resolution). It cannot be used as a constraint or capability.

MediaTrackSupportedConstraints

MediaTrackSupportedConstraints.displaySurface

A boolean, which istrue if the current environment supports theMediaTrackConstraints.displaySurface constraint.

MediaTrackSupportedConstraints.logicalSurface

A boolean, which istrue if the current environment supports the constraintMediaTrackConstraints.logicalSurface.

MediaTrackSupportedConstraints.suppressLocalAudioPlayback

A boolean, which istrue if the current environment supports the constraintMediaTrackConstraints.suppressLocalAudioPlayback.

Security considerations

Websites that supportPermissions Policy (either using the HTTPPermissions-Policy header or the<iframe> attributeallow) can specify a desire to use the Screen Capture API using the directivedisplay-capture:

<iframe allow="display-capture" src="/some-other-document.html">…</iframe>

A site can also specify a desire to use theCaptured Surface Control API via thecaptured-surface-control directive. Specifically, theforwardWheel(),increaseZoomLevel(),decreaseZoomLevel(), andresetZoomLevel() methods are controlled by this directive.

The default allowlist for both directives isself, which permits any content within the same origin use Screen Capture.

These methods are consideredpowerful features, which means that even if permission is allowed via aPermissions-Policy, the user will still be prompted for permission to use them. ThePermissions API can be used to query the aggregate permission (from both the website and the user) for using the listed features.

In addition, the specification requires that a user has recently interacted with the page to use these features — this means thattransient activation is required. See the individual method pages for more details.

Specifications

Browser compatibility

api.MediaDevices.getDisplayMedia

api.CropTarget

api.RestrictionTarget

See also

• Using the Screen Capture API
• Using the Element Capture and Region Capture APIs
• Using the Captured Surface Control API
• MediaDevices.getDisplayMedia()