MediaDevices.getDisplayMedia() | fix apiref & add param & update ex…

…ception (mdn#31160)

files/en-us/web/api/mediadevices/getdisplaymedia/index.md

@@ -6,9 +6,9 @@ page-type: web-api-instance-method
 browser-compat: api.MediaDevices.getDisplayMedia
 ---
 
-{{DefaultAPISidebar("Screen Capture API")}}
+{{APIRef("Screen Capture API")}}
 
-The {{domxref("MediaDevices")}} interface's **`getDisplayMedia()`** method prompts the user to select and
+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")}}.
 
 The resulting stream can then be
@@ -31,16 +31,18 @@ getDisplayMedia(options)
       - : A boolean or a {{domxref("MediaTrackConstraints")}} instance; the default value is `true`. If this option is omitted or set to `true`, the stream will contain a video track A value of `true` indicates that 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`.
     - `audio` {{optional_inline}}
       - : 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.
-    - `controller` {{optional_inline}}
+    - `controller` {{Experimental_Inline}} {{optional_inline}}
       - : A {{domxref("CaptureController")}} object instance containing methods that can be used to further manipulate the capture session if included.
-    - `preferCurrentTab` {{non-standard_inline}} {{optional_inline}}
+    - `preferCurrentTab` {{non-standard_inline}} {{Experimental_Inline}} {{optional_inline}}
       - : 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.
-    - `selfBrowserSurface` {{optional_inline}}
+    - `selfBrowserSurface` {{Experimental_Inline}} {{optional_inline}}
       - : 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.
-    - `surfaceSwitching` {{optional_inline}}
+    - `surfaceSwitching` {{Experimental_Inline}} {{optional_inline}}
       - : 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.
-    - `systemAudio` {{optional_inline}}
+    - `systemAudio` {{Experimental_Inline}} {{optional_inline}}
       - : 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.
+    - `monitorTypeSurfaces` {{Experimental_Inline}} {{optional_inline}}
+      - : An enumerated value specifying whether the application would like the user agent to offer the user the option to choose display surfaces whose type is monitor. Possible values are `include`, which hints that the browser should include the display surfaces whose type is monitor, 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.
 
 > **Note:** 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.
 
@@ -55,26 +57,26 @@ audio track.
 ### Exceptions
 
 - `AbortError` {{domxref("DOMException")}}
-  - : Returned if an error or failure does not match any of the other exceptions listed here.
+  - : Thrown if an error or failure does not match any of the other exceptions listed here.
 - `InvalidStateError` {{domxref("DOMException")}}
-  - : Returned if the call to `getDisplayMedia()` was not made from code running due to a
-    user action, such as an event handler. Another potential cause for this event: the
-    {{domxref("document")}} in whose context `getDisplayMedia()` was called is
-    not fully active; for example, perhaps it is not the frontmost tab.
+  - : Thrown if the call to `getDisplayMedia()` was not made from code running due to a
+    {{glossary("transient activation")}}, such as an event handler. Or if the browser context is
+    not fully active or does not focused. Or if the `controller` options has been already used in creating
+    another {{domxref("MediaStream")}}.
 - `NotAllowedError` {{domxref("DOMException")}}
-  - : Returned if the permission to access a screen area was denied by the user (for example by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy)), or the current browsing instance is not permitted access to screen sharing.
+  - : 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/Permissions_Policy)).
 - `NotFoundError` {{domxref("DOMException")}}
-  - : Returned if no sources of screen video are available for capture.
+  - : Thrown if no sources of screen video are available for capture.
 - `NotReadableError` {{domxref("DOMException")}}
-  - : Returned if the user selected a screen, window, tab, or another source of screen data, but a
+  - : 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.
 - `OverconstrainedError` {{domxref("DOMException")}}
-  - : Returned if, after creating the stream, applying any specified constraints fails
+  - : Thrown if, after creating the stream, applying any specified constraints fails
     because no compatible stream could be generated.
 - {{jsxref("TypeError")}}
-  - : Returned 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. `min` and `exact` values are not permitted in constraints used in {{domxref("MediaDevices.getDisplayMedia()")}} calls.
+  - : 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. `min` and `exact` values are not permitted in constraints used in `getDisplayMedia()` calls.
 
 ## Security