You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Layout only fixes
* Layout only fixes
* Add info about resizeMode
* Apply suggestions from code review
Co-authored-by: wbamberg <[email protected]>
* Apply suggestions from code review
Co-authored-by: wbamberg <[email protected]>
* Specify the behaviour if not set
---------
Co-authored-by: wbamberg <[email protected]>
The **`getDisplayMedia()`** method of the {{domxref("MediaDevices")}} interface prompts the user to select and
12
-
grant permission to capture the contents of a display or portion thereof (such as a window) as a {{domxref("MediaStream")}}.
11
+
The **`getDisplayMedia()`** method of the {{domxref("MediaDevices")}} interface prompts the user to select and grant permission to capture the contents of a display or portion thereof (such as a window) as a {{domxref("MediaStream")}}.
13
12
14
-
The resulting stream can then be
15
-
recorded using the [MediaStream Recording API](/en-US/docs/Web/API/MediaStream_Recording_API) or transmitted as part of a [WebRTC](/en-US/docs/Web/API/WebRTC_API) session.
13
+
The resulting stream can then be recorded using the [MediaStream Recording API](/en-US/docs/Web/API/MediaStream_Recording_API) or transmitted as part of a [WebRTC](/en-US/docs/Web/API/WebRTC_API) session.
16
14
17
15
See [Using the Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture) for more details and an example.
18
16
@@ -26,86 +24,95 @@ getDisplayMedia(options)
26
24
### Parameters
27
25
28
26
-`options` {{optional_inline}}
29
-
- : An optional object specifying requirements for the returned {{domxref("MediaStream")}}. The options for `getDisplayMedia()` work in the same as the [constraints](/en-US/docs/Web/API/MediaDevices/getUserMedia#parameters) for the {{domxref("MediaDevices.getUserMedia()")}} method, although in that case only `audio` and `video` can be specified. The list of possible option properties for `getDisplayMedia()` is as follows:
27
+
- : An optional object specifying requirements for the returned {{domxref("MediaStream")}}.
28
+
The options for `getDisplayMedia()` work in the same as the [constraints](/en-US/docs/Web/API/MediaDevices/getUserMedia#parameters) for the {{domxref("MediaDevices.getUserMedia()")}} method, although in that case only `audio` and `video` can be specified.
29
+
The list of possible option properties for `getDisplayMedia()` is as follows:
30
30
-`video` {{optional_inline}}
31
-
- : A boolean or a {{domxref("MediaTrackConstraints")}} instance; the default value is `true`. If this option is omitted or set to `true`, the returned {{domxref("MediaStream")}} will contain a video track. Since `getDisplayMedia()` requires a video track, if this option is set to `false` the promise will reject with a `TypeError`.
31
+
- : A boolean or a {{domxref("MediaTrackConstraints")}} instance; the default value is `true`.
32
+
If this option is omitted or set to `true`, the returned {{domxref("MediaStream")}} will contain a video track.
33
+
Since `getDisplayMedia()` requires a video track, if this option is set to `false` the promise will reject with a `TypeError`.
32
34
-`audio` {{optional_inline}}
33
-
- : A boolean or a {{domxref("MediaTrackConstraints")}} instance; the default value is `false`. A value of `true` indicates that the returned {{domxref("MediaStream")}} will contain an audio track, if audio is supported and available for the display surface chosen by the user.
35
+
- : A boolean or a {{domxref("MediaTrackConstraints")}} instance; the default value is `false`.
36
+
A value of `true` indicates that the returned {{domxref("MediaStream")}} will contain an audio track, if audio is supported and available for the display surface chosen by the user.
- : An enumerated value specifying whether the browser should offer entire screens in the screen capture options presented to the user alongside tab and window options. This option is intended to protect companies from leakage of private information through employee error when using video conferencing apps. Possible values are `include`, which hints that the browser should include screen options, and `exclude`, which hints that they should be excluded. A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
40
+
- : An enumerated value specifying whether the browser should offer entire screens in the screen capture options presented to the user alongside tab and window options.
41
+
This option is intended to protect companies from leakage of private information through employee error when using video conferencing apps.
42
+
Possible values are `include`, which hints that the browser should include screen options, and `exclude`, which hints that they should be excluded.
43
+
A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
38
44
39
45
> [!NOTE]
40
-
> You cannot set `monitorTypeSurfaces: "exclude"` at the same time as [`displaySurface: "monitor"`](/en-US/docs/Web/API/MediaTrackConstraints/displaySurface) as the two settings are contradictory. Trying to do so will result in the `getDisplayMedia()` call failing with a `TypeError`.
46
+
> You cannot set `monitorTypeSurfaces: "exclude"` at the same time as [`displaySurface: "monitor"`](/en-US/docs/Web/API/MediaTrackConstraints/displaySurface) as the two settings are contradictory.
47
+
> Trying to do so will result in the `getDisplayMedia()` call failing with a `TypeError`.
- : A boolean; a value of `true` instructs the browser to offer the current tab as the most prominent capture source, i.e., as a separate "This Tab" option in the "Choose what to share" options presented to the user. This is useful as many app types generally just want to share the current tab. For example, a slide deck app might want to let the user stream the current tab containing the presentation to a virtual conference. A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
50
+
- : A boolean; a value of `true` instructs the browser to offer the current tab as the most prominent capture source, i.e., as a separate "This Tab" option in the "Choose what to share" options presented to the user.
51
+
This is useful as many app types generally just want to share the current tab.
52
+
For example, a slide deck app might want to let the user stream the current tab containing the presentation to a virtual conference.
53
+
A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
- : An enumerated value specifying whether the browser should allow the user to select the current tab for capture. This helps to avoid the "infinite hall of mirrors" effect experienced when a video conferencing app inadvertently shares its own display. Possible values are `include`, which hints that the browser should include the current tab in the choices offered for capture, and `exclude`, which hints that it should be excluded. A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
55
+
- : An enumerated value specifying whether the browser should allow the user to select the current tab for capture.
56
+
This helps to avoid the "infinite hall of mirrors" effect experienced when a video conferencing app inadvertently shares its own display.
57
+
Possible values are `include`, which hints that the browser should include the current tab in the choices offered for capture, and `exclude`, which hints that it should be excluded.
58
+
A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
- : An enumerated value specifying whether the browser should display a control to allow the user to dynamically switch the shared tab during screen-sharing. This is much more convenient than having to go through the whole sharing process again each time a user wants to switch the shared tab. Possible values are `include`, which hints that the browser should include the control, and `exclude`, which hints that it should not be shown. A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
60
+
- : An enumerated value specifying whether the browser should display a control to allow the user to dynamically switch the shared tab during screen-sharing.
61
+
This is much more convenient than having to go through the whole sharing process again each time a user wants to switch the shared tab.
62
+
Possible values are `include`, which hints that the browser should include the control, and `exclude`, which hints that it should not be shown.
63
+
A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
- : An enumerated value specifying whether the browser should include the system audio among the possible audio sources offered to the user. Possible values are `include`, which hints that the browser should include the system audio in the list of choices, and `exclude`, which hints that it should be excluded. A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
65
+
- : An enumerated value specifying whether the browser should include the system audio among the possible audio sources offered to the user.
66
+
Possible values are `include`, which hints that the browser should include the system audio in the list of choices, and `exclude`, which hints that it should be excluded.
67
+
A default value is not mandated by the spec; see the [Browser compatibility](#browser_compatibility) section for browser-specific defaults.
50
68
51
69
> [!NOTE]
52
70
> See the article [Capabilities, constraints, and settings](/en-US/docs/Web/API/Media_Capture_and_Streams_API/Constraints) for a lot more detail on how these options work.
53
71
54
72
### Return value
55
73
56
-
A {{jsxref("Promise")}} that resolves to a {{domxref("MediaStream")}} containing a
57
-
video track whose contents come from a user-selected screen area, as well as an optional
58
-
audio track.
74
+
A {{jsxref("Promise")}} that resolves to a {{domxref("MediaStream")}} containing a video track whose contents come from a user-selected screen area, as well as an optional audio track.
59
75
60
76
> [!NOTE]
61
-
> Browser support for audio tracks varies, both in terms of whether or not they're supported at all by the media recorder and in terms of the audio sources supported. Check the [compatibility table](#browser_compatibility) for details for each browser.
77
+
> Browser support for audio tracks varies, both in terms of whether or not they're supported at all by the media recorder and in terms of the audio sources supported.
78
+
> Check the [compatibility table](#browser_compatibility) for details for each browser.
62
79
63
80
### Exceptions
64
81
65
82
-`AbortError` {{domxref("DOMException")}}
66
83
- : Thrown if an error or failure does not match any of the other exceptions listed here.
67
84
-`InvalidStateError` {{domxref("DOMException")}}
68
-
- : Thrown if the call to `getDisplayMedia()` was not made from code running due to a
69
-
{{glossary("transient activation")}}, such as an event handler. Or if the browser context is
70
-
not fully active or does not focused. Or if the `controller` options has been already used in creating
71
-
another {{domxref("MediaStream")}}.
85
+
- : Thrown if the call to `getDisplayMedia()` was not made from code running due to a {{glossary("transient activation")}}, such as an event handler.
86
+
Or if the browser context is not fully active or does not focused.
87
+
Or if the `controller` options has been already used in creating another {{domxref("MediaStream")}}.
72
88
-`NotAllowedError` {{domxref("DOMException")}}
73
89
- : Thrown if the permission to access a screen area was denied by the user, or the current browsing instance is not permitted access to screen sharing (for example by a [Permissions Policy](/en-US/docs/Web/HTTP/Guides/Permissions_Policy)).
74
90
-`NotFoundError` {{domxref("DOMException")}}
75
91
- : Thrown if no sources of screen video are available for capture.
76
92
-`NotReadableError` {{domxref("DOMException")}}
77
-
- : Thrown if the user selected a screen, window, tab, or another source of screen data, but a
78
-
hardware or operating system level error or lockout occurred, preventing the sharing
79
-
of the selected source.
93
+
- : Thrown if the user selected a screen, window, tab, or another source of screen data, but a hardware or operating system level error or lockout occurred, preventing the sharing of the selected source.
- : Thrown if, after creating the stream, applying any specified constraints fails
82
-
because no compatible stream could be generated.
95
+
- : Thrown if, after creating the stream, applying any specified constraints fails because no compatible stream could be generated.
83
96
- {{jsxref("TypeError")}}
84
-
- : Thrown if the specified `options` include values that are not permitted
85
-
when calling `getDisplayMedia()`, for example a `video` property set to false, or if any specified {{domxref("MediaTrackConstraints")}} are not permitted. `min` and `exact` values are not permitted in constraints used in `getDisplayMedia()` calls.
97
+
- : Thrown if the specified `options` include values that are not permitted when calling `getDisplayMedia()`, for example a `video` property set to false, or if any specified {{domxref("MediaTrackConstraints")}} are not permitted.
98
+
`min` and `exact` values are not permitted in constraints used in `getDisplayMedia()` calls.
86
99
87
100
## Security
88
101
89
-
Because `getDisplayMedia()` could be used in nefarious ways, it can be a
90
-
source of significant privacy and security concerns. For that reason, the specification
91
-
details measures browsers are required to take in order to fully support
92
-
`getDisplayMedia()`.
93
-
94
-
- The specified options can't be used to limit the choices available
95
-
to the user. Instead, they must be applied after the user chooses a source, in order
96
-
to generate output that matches the options.
97
-
- The go-ahead permission to use `getDisplayMedia()` cannot be persisted
98
-
for reuse. The user must be prompted for permission every time.
99
-
-[Transient user activation](/en-US/docs/Web/Security/User_activation) is required. The user has to interact with the page or a UI element in order for this feature to work.
100
-
- Browsers are encouraged to provide a warning to users about sharing displays or
101
-
windows that contain browsers, and to keep a close eye on what other content might be
102
-
getting captured and shown to other users.
102
+
Because `getDisplayMedia()` could be used in nefarious ways, it can be a source of significant privacy and security concerns.
103
+
For that reason, the specification details measures browsers are required to take in order to fully support `getDisplayMedia()`.
104
+
105
+
- The specified options can't be used to limit the choices available to the user.
106
+
Instead, they must be applied after the user chooses a source, in order to generate output that matches the options.
107
+
- The go-ahead permission to use `getDisplayMedia()` cannot be persisted for reuse.
108
+
The user must be prompted for permission every time.
109
+
-[Transient user activation](/en-US/docs/Web/Security/User_activation) is required.
110
+
The user has to interact with the page or a UI element in order for this feature to work.
111
+
- Browsers are encouraged to provide a warning to users about sharing displays or windows that contain browsers, and to keep a close eye on what other content might be getting captured and shown to other users.
103
112
104
113
## Examples
105
114
106
-
In the example below a `startCapture()` method is created, which initiates
107
-
screen capture given a set of options specified by the `displayMediaOptions`
108
-
parameter.
115
+
In the example below a `startCapture()` method is created, which initiates screen capture given a set of options specified by the `displayMediaOptions` parameter.
109
116
110
117
```js
111
118
constdisplayMediaOptions= {
@@ -135,11 +142,8 @@ async function startCapture(displayMediaOptions) {
135
142
}
136
143
```
137
144
138
-
This uses {{jsxref("Operators/await", "await")}} to asynchronously wait for `getDisplayMedia()`
139
-
to resolve with a {{domxref("MediaStream")}} which contains the display contents as
140
-
requested by the specified options. The stream is then returned to the caller for use,
141
-
perhaps for adding to a WebRTC call using {{domxref("RTCPeerConnection.addTrack()")}} to
142
-
add the video track from the stream.
145
+
This uses {{jsxref("Operators/await", "await")}} to asynchronously wait for `getDisplayMedia()` to resolve with a {{domxref("MediaStream")}} which contains the display contents as requested by the specified options.
146
+
The stream is then returned to the caller for use, perhaps for adding to a WebRTC call using {{domxref("RTCPeerConnection.addTrack()")}} to add the video track from the stream.
143
147
144
148
> [!NOTE]
145
149
> The [Screen sharing controls](https://chrome.dev/screen-sharing-controls/) demo provides a complete implementation that allows you to create a screen capture with your choice of `getDisplayMedia()` constraints and options.
0 commit comments