Add new screen capture constraints and options

files/en-us/web/api/capturecontroller/setfocusbehavior/index.md

@@ -35,7 +35,10 @@ setFocusBehavior(focusBehavior)
 ### Exceptions
 
 - `InvalidStateError` {{domxref("DOMException")}}
-  - : Thrown if the capture stream has been stopped, or if enough time has elapsed after the {{domxref("MediaDevices.getDisplayMedia()")}} `Promise` fulfills that the focus behavior has been finalized.
+  - : Thrown if:
+    - The capture stream has been stopped.
+    - The user chose to share a screen ({{domxref("MediaTrackSettings.displaySurface", "displaySurface")}} type `monitor`) rather than a `browser` tab or `window` — you can't focus a monitor. In this case the exception is thrown after the {{domxref("MediaDevices.getDisplayMedia()")}} `Promise` resolves.
+    - Enough time has elapsed after the {{domxref("MediaDevices.getDisplayMedia()")}} `Promise` fulfills that the focus behavior has been finalized.
 
 ## Examples
 

files/en-us/web/api/mediatrackconstraints/displaysurface/index.md

@@ -47,7 +47,7 @@ video {{domxref("MediaStreamTrack")}}, then checking the value of the returned
 {{domxref("MediaTrackSettings.displaySurface", "displaySurface")}} object.
 
 For example, if your app needs to know that the surface being shared is a monitor or
-application—meaning that there's possibly a non-content backdrop—it can use code similar
+window—meaning that there's possibly a non-content backdrop—it can use code similar
 to this:
 
 ```js

files/en-us/web/api/mediatrackconstraints/index.md

@@ -158,8 +158,6 @@ These constraints apply to the `video` property of the object passed into {{domx
 
   - : A [`ConstrainDOMString`](#constraindomstring) which specifies the types of display surface that may be selected by the user. This may be a single one of the following strings, or a list of them to allow multiple source surfaces:
 
-    - `application`
-      - : The stream contains all of the windows of the application chosen by the user rendered into the one video track.
     - `browser`
       - : The stream contains the contents of a single browser tab selected by the user.
     - `monitor`
@@ -170,6 +168,9 @@ These constraints apply to the `video` property of the object passed into {{domx
 - {{domxref("MediaTrackConstraints.logicalSurface", "logicalSurface")}}
   - : A [`ConstrainBoolean`](#constrainboolean) value which may contain a single Boolean value or a set of them, indicating whether or not to allow the user to choose source surfaces which do not directly correspond to display areas. These may include backing buffers for windows to allow capture of window contents that are hidden by other windows in front of them, or buffers containing larger documents that need to be scrolled through to see the entire contents in their windows.
 
+- {{domxref("MediaTrackConstraints.suppressLocalAudioPlayback", "suppressLocalAudioPlayback")}}
+  - : A [`ConstrainBoolean`](#constrainboolean) value describing the requested or mandatory constraints placed upon the value of the {{domxref("MediaTrackSettings.suppressLocalAudioPlayback","suppressLocalAudioPlayback")}} constrainable property. This property 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.
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/mediatrackconstraints/suppresslocalaudioplayback/index.md

@@ -27,13 +27,19 @@ this is unnecessary since browsers will ignore any constraints they're unfamilia
 
 ## Value
 
+`true`/`false`, or a [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) object.
+
 If this value is a simple `true` or `false`, the user agent will
 attempt to obtain media with local audio playback enabled or disabled as specified, if
-possible, but will not fail if this can't be done. If, instead, the value is given as an
-object with an `exact` field, that field's Boolean value indicates a required
-setting for the noise suppression feature; if it can't be met, then the request will
+possible, but will not fail if this can't be done.
+
+If, instead, the value is given as a [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) object
+object with an `ideal` field, that field's Boolean value indicates an ideal
+setting for the local audio playback suppression feature; if it can't be met, then the request will
 result in an error.
 
+`exact` values are not permitted in constraints used in {{domxref("MediaDevices.getDisplayMedia()")}} calls, but they are in constraints used in {{domxref("MediaStreamTrack.applyConstraints()")}} calls.
+
 ## Examples
 
 See {{SectionOnPage("/en-US/docs/Web/API/Media_Capture_and_Streams_API/Constraints", "Example: Constraint exerciser")}} for an example.

files/en-us/web/api/mediatracksettings/suppresslocalaudioplayback/index.md

@@ -27,9 +27,8 @@ The below function sets up the constraints object specifying the options for the
 
 ```js
 async function capture() {
-  let supportedConstraints = navigator.mediaDevices.getSupportedConstraints();
-  let displayMediaOptions = {
-    video: {},
+  const supportedConstraints = navigator.mediaDevices.getSupportedConstraints();
+  const displayMediaOptions = {
     audio: {}
   };
 

files/en-us/web/api/mediatracksupportedconstraints/suppresslocalaudioplayback/index.md

@@ -27,9 +27,8 @@ The below function sets up the constraints object specifying the options for the
 
 ```js
 async function capture() {
-  let supportedConstraints = navigator.mediaDevices.getSupportedConstraints();
-  let displayMediaOptions = {
-    video: {},
+  const supportedConstraints = navigator.mediaDevices.getSupportedConstraints();
+  const displayMediaOptions = {
     audio: {}
   };
 

files/en-us/web/api/screen_capture_api/using_screen_capture/index.md

@@ -109,15 +109,18 @@ This allows the user total freedom to select whatever they want, within the limi
 ```js
 const gdmOptions = {
   video: {
-    cursor: "always"
+    cursor: "always",
+    displaySurface: "window"
   },
   audio: {
     echoCancellation: true,
     noiseSuppression: true,
     sampleRate: 44100
+    suppressLocalAudioPlayback: true
   },
-  surfaceSwitching: true,
-  selfBrowserSurface: false
+  surfaceSwitching: "include",
+  selfBrowserSurface: "exclude",
+  systemAudio: "exclude"
 }
 ```