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`:


```js
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.

Interfaces
----------

`CaptureController`

Provides methods that can be used to further manipulate a capture session separate from its initiation via `MediaDevices.getDisplayMedia()`. A `CaptureController` object is associated with a capture session by passing it into a `getDisplayMedia()` call as the value of the options object's `controller` property.

Additions to the 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.displaySurface`

A `ConstrainDOMString` indicating what type of display surface is to be captured. The value is one of `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.

`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`, or `never`.

`MediaTrackSettings.displaySurface`

A string indicating what type of display surface is currently being captured. The value is one of `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.

`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 the `MediaTrackConstraints.displaySurface` constraint.

`MediaTrackSupportedConstraints.logicalSurface`

A boolean, which is `true` if the current environment supports the constraint `MediaTrackConstraints.logicalSurface`.

`MediaTrackSupportedConstraints.suppressLocalAudioPlayback`

A boolean, which is `true` if the current environment supports the constraint `MediaTrackConstraints.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`:


```html
<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 # dom-mediadevices-getdisplaymedia |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Using the Screen Capture API
* `MediaDevices.getDisplayMedia()`