Editorial review: Add docs for restrictOwnAudio constraint

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

@@ -203,6 +203,10 @@ These constraints apply to the `video` property of the object passed into {{domx
   - : 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.
 
+- {{domxref("MediaTrackConstraints.restrictOwnAudio", "restrictOwnAudio")}} {{Experimental_Inline}}
+  - : A [`ConstrainBoolean`](#constrainboolean) value that specifies the requested or mandatory constraints placed on the value of the {{domxref("MediaTrackSettings.restrictOwnAudio","restrictOwnAudio")}} constrainable property.
+    This property controls whether the system audio originating from the capturing tab is filtered out of the screen capture.
+
 ## Specifications
 
 {{Specifications}}

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

@@ -0,0 +1,60 @@
+---
+title: "MediaTrackConstraints: restrictOwnAudio property"
+short-title: restrictOwnAudio
+slug: Web/API/MediaTrackConstraints/restrictOwnAudio
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.MediaStreamTrack.applyConstraints.restrictOwnAudio_constraint
+---
+
+{{APIRef("Media Capture and Streams")}}{{SeeCompatTable}}
+
+The {{domxref("MediaTrackConstraints")}} dictionary's **`restrictOwnAudio`** property is a [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) that specifies the requested or mandatory constraints placed on the value of the {{domxref("MediaTrackSettings.restrictOwnAudio","restrictOwnAudio")}} constrainable property.
+
+This property controls whether system audio originating from the capturing tab is filtered out of screen capture, allowing for cleaner screen recordings in some cases. For example, if the capturing web page itself is playing embedded audio or video, that audio would be included in the capture. Since this could lead to an undesirable echo or interfere with the intended audio sources from other tabs or applications, removing it from the capture is desirable.
+
+If needed, you can determine whether or not this constraint is supported by checking
+the value of {{domxref("MediaTrackSupportedConstraints.restrictOwnAudio")}}, as returned
+by {{domxref("MediaDevices.getSupportedConstraints()")}}. However,
+this is rarely necessary since browsers typically ignore any constraints they don't recognize.
+
+## Value
+
+A [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) value.
+
+If the value is `true`, the user agent will attempt to remove any audio originating from the tab that called {{domxref("MediaDevices.getDisplayMedia()")}} to initiate screen capture. If removal of audio via processing fails, the user agent may exclude all audio originating from the capturing tab.
+
+> [!NOTE]
+> If the captured display surface doesn't include system audio, this setting will have no effect.
+
+If the value is given as `exact`, that field's boolean value indicates an exact requirement for the `restrictOwnAudio` feature; if the user agent can't meet this requirement, the request will result in an error.
+
+If the value is `false`, the user agent will not attempt to restrict any system audio originating from the capturing tab.
+
+## Examples
+
+```js
+let isCapturingTabSystemAudioRestricted = displayStream
+  .getAudioTracks()[0]
+  .getSettings().restrictOwnAudio;
+```
+
+The [Constraint exerciser](/en-US/docs/Web/API/Media_Capture_and_Streams_API/Constraints#example_constraint_exerciser) example shows how to use media track constraints.
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Media Capture and Streams API](/en-US/docs/Web/API/Media_Capture_and_Streams_API)
+- [Capabilities, constraints, and settings](/en-US/docs/Web/API/Media_Capture_and_Streams_API/Constraints)
+- {{domxref("MediaTrackConstraints")}}
+- {{domxref("MediaDevices.getSupportedConstraints()")}}
+- {{domxref("MediaTrackSupportedConstraints")}}
+- {{domxref("MediaStreamTrack")}}

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

@@ -35,7 +35,9 @@ Some or all of the following will be included in the object, either because it's
 - {{domxref("MediaTrackSettings.latency", "latency")}}
   - : A double-precision floating point value indicating the current value of the {{domxref("MediaTrackConstraints.latency", "latency")}} property, specifying the audio latency, in seconds. Latency is the amount of time which elapses between the start of processing the audio and the data being available to the next stop in the audio utilization process. This value is a target value; actual latency may vary to some extent for various reasons.
 - {{domxref("MediaTrackSettings.noiseSuppression", "noiseSuppression")}}
-  - : A Boolean which indicates the current value of the {{domxref("MediaTrackConstraints.noiseSuppression", "noiseSuppression")}} property, which is `true` if noise suppression is enabled and is `false` otherwise.
+  - : A Boolean indicating the current value of the {{domxref("MediaTrackConstraints.noiseSuppression", "noiseSuppression")}} property: `true` if noise suppression is enabled, and is `false` otherwise.
+- {{domxref("MediaTrackSettings.restrictOwnAudio", "restrictOwnAudio")}}
+  - : A Boolean indicating the current value of the {{domxref("MediaTrackConstraints.restrictOwnAudio", "restrictOwnAudio")}} property: `true` if the browser will attempt to filter out system audio originating from the capturing tab during screen capture, and `false` otherwise.
 - {{domxref("MediaTrackSettings.sampleRate", "sampleRate")}}
   - : A long integer value indicating the current value of the {{domxref("MediaTrackConstraints.sampleRate", "sampleRate")}} property, specifying the sample rate in samples per second of the audio data. Standard CD-quality audio, for example, has a sample rate of 41,000 samples per second.
 - {{domxref("MediaTrackSettings.sampleSize", "sampleSize")}}

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

@@ -0,0 +1,68 @@
+---
+title: "MediaTrackSettings: restrictOwnAudio property"
+short-title: restrictOwnAudio
+slug: Web/API/MediaTrackSettings/restrictOwnAudio
+page-type: web-api-instance-property
+status:
+  - experimental
+browser-compat: api.MediaStreamTrack.applyConstraints.restrictOwnAudio_constraint
+---
+
+{{APIRef("Media Capture and Streams")}}{{SeeCompatTable}}
+
+The {{domxref("MediaTrackSettings")}} dictionary's **`restrictOwnAudio`** property controls whether system audio originating from the capturing tab is filtered out of screen capture, allowing for cleaner screen recordings in some cases.
+
+For example, if the capturing web page itself is playing embedded audio or video, that audio would be included in the capture. Since this could lead to an undesirable echo or interfere with the intended audio sources from other tabs or applications, removing it from the capture is desirable.
+
+## Value
+
+A boolean value, where `true` enables the capturing tab's system audio restriction and `false` disables it.
+
+If the value is `true`, the user agent will attempt to remove any audio originating from the captured audio produced by the tab that called {{domxref("MediaDevices.getDisplayMedia()")}} to initiate screen capture. If removal of audio via processing fails, the user agent may exclude all audio originating from the capturing tab.
+
+> [!NOTE]
+> If the captured display surface doesn't include system audio, this setting will have no effect.
+
+## Examples
+
+The following function sets up a constraints object that specifies the options for a call to {{domxref("MediaDevices.getDisplayMedia", "getDisplayMedia()")}}.
+It adds the `restrictOwnAudio` constraint (requesting that system audio originating from the capturing tab be filtered out of the screen capture) only if it is known to be supported by the browser.
+Capture then starts by calling `getDisplayMedia()` and attaching the returned stream to the {{htmlelement("video")}} element referenced by the variable `videoElem`.
+
+```js
+async function capture() {
+  const supportedConstraints = navigator.mediaDevices.getSupportedConstraints();
+  const displayMediaOptions = {
+    audio: {},
+  };
+
+  if (supportedConstraints.restrictOwnAudio) {
+    displayMediaOptions.audio.restrictOwnAudio = true;
+  }
+
+  try {
+    videoElem.srcObject =
+      await navigator.mediaDevices.getDisplayMedia(displayMediaOptions);
+  } catch (err) {
+    /* handle the error */
+  }
+}
+```
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Screen Capture API](/en-US/docs/Web/API/Screen_Capture_API)
+- [Using the screen capture API](/en-US/docs/Web/API/Screen_Capture_API/Using_Screen_Capture)
+- [Capabilities, constraints, and settings](/en-US/docs/Web/API/Media_Capture_and_Streams_API/Constraints)
+- {{domxref("MediaDevices.getDisplayMedia()")}}
+- {{domxref("MediaStreamTrack.getConstraints()")}}
+- {{domxref("MediaStreamTrack.applyConstraints()")}}
+- {{domxref("MediaStreamTrack.getSettings()")}}

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

@@ -19,44 +19,46 @@ To learn more about how constraints work, see [Capabilities, constraints, and se
 
 Some combination—but not necessarily all—of the following properties will exist on the object.
 
-- {{domxref("MediaTrackSupportedConstraints.autoGainControl", "autoGainControl")}}
-  - : A Boolean that is `true` if the [`autoGainControl`](/en-US/docs/Web/API/MediaTrackConstraints/autoGainControl) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.width", "width")}}
-  - : A Boolean that is `true` if the [`width`](/en-US/docs/Web/API/MediaTrackConstraints/width) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.height", "height")}}
-  - : A Boolean that is `true` if the [`height`](/en-US/docs/Web/API/MediaTrackConstraints/height) constraint is supported in the current environment.
 - {{domxref("MediaTrackSupportedConstraints.aspectRatio", "aspectRatio")}}
   - : A Boolean that is `true` if the [`aspectRatio`](/en-US/docs/Web/API/MediaTrackConstraints/aspectRatio) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.frameRate", "frameRate")}}
-  - : A Boolean that is `true` if the [`frameRate`](/en-US/docs/Web/API/MediaTrackConstraints/frameRate) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.autoGainControl", "autoGainControl")}}
+  - : A Boolean that is `true` if the [`autoGainControl`](/en-US/docs/Web/API/MediaTrackConstraints/autoGainControl) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.channelCount", "channelCount")}}
+  - : A Boolean that is `true` if the [`channelCount`](/en-US/docs/Web/API/MediaTrackConstraints/channelCount) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.deviceId", "deviceId")}}
+  - : A Boolean that is `true` if the [`deviceId`](/en-US/docs/Web/API/MediaTrackConstraints/deviceId) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.echoCancellation", "echoCancellation")}}
+  - : A Boolean that is `true` if the [`echoCancellation`](/en-US/docs/Web/API/MediaTrackConstraints/echoCancellation) constraint is supported in the current environment.
 - {{domxref("MediaTrackSupportedConstraints.facingMode", "facingMode")}}
   - : A Boolean that is `true` if the [`facingMode`](/en-US/docs/Web/API/MediaTrackConstraints/facingMode) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.frameRate", "frameRate")}}
+  - : A Boolean that is `true` if the [`frameRate`](/en-US/docs/Web/API/MediaTrackConstraints/frameRate) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.groupId", "groupId")}}
+  - : A Boolean that is `true` if the [`groupId`](/en-US/docs/Web/API/MediaTrackConstraints/groupId) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.height", "height")}}
+  - : A Boolean that is `true` if the [`height`](/en-US/docs/Web/API/MediaTrackConstraints/height) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.latency", "latency")}}
+  - : A Boolean that is `true` if the [`latency`](/en-US/docs/Web/API/MediaTrackConstraints/latency) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.noiseSuppression", "noiseSuppression")}}
+  - : A Boolean that is `true` if the [`noiseSuppression`](/en-US/docs/Web/API/MediaTrackConstraints/noiseSuppression) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.restrictOwnAudio", "restrictOwnAudio")}}
+  - : A Boolean that is `true` if the {{domxref("MediaTrackConstraints.restrictOwnAudio", "restrictOwnAudio")}} constraint is supported in the current environment.
 - {{domxref("MediaTrackSupportedConstraints.resizeMode", "resizeMode")}}
   - : A Boolean that is `true` if the [`resizeMode`](/en-US/docs/Web/API/MediaTrackConstraints/resizeMode) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.volume", "volume")}} {{Deprecated_Inline}} {{Non-standard_Inline}}
-  - : A Boolean that is `true` if the [`volume`](/en-US/docs/Web/API/MediaTrackConstraints/volume) constraint is supported in the current environment.
 - {{domxref("MediaTrackSupportedConstraints.sampleRate", "sampleRate")}}
   - : A Boolean that is `true` if the [`sampleRate`](/en-US/docs/Web/API/MediaTrackConstraints/sampleRate) constraint is supported in the current environment.
 - {{domxref("MediaTrackSupportedConstraints.sampleSize", "sampleSize")}}
   - : A Boolean that is `true` if the [`sampleSize`](/en-US/docs/Web/API/MediaTrackConstraints/sampleSize) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.echoCancellation", "echoCancellation")}}
-  - : A Boolean that is `true` if the [`echoCancellation`](/en-US/docs/Web/API/MediaTrackConstraints/echoCancellation) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.latency", "latency")}}
-  - : A Boolean that is `true` if the [`latency`](/en-US/docs/Web/API/MediaTrackConstraints/latency) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.noiseSuppression", "noiseSuppression")}}
-  - : A Boolean that is `true` if the [`noiseSuppression`](/en-US/docs/Web/API/MediaTrackConstraints/noiseSuppression) constraint is supported in the current environment.
 - {{domxref("MediaTrackSupportedConstraints.suppressLocalAudioPlayback", "suppressLocalAudioPlayback")}}
   - : A Boolean that is `true` if the [`suppressLocalAudioPlayback`](/en-US/docs/Web/API/MediaTrackConstraints/suppressLocalAudioPlayback) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.channelCount", "channelCount")}}
-  - : A Boolean that is `true` if the [`channelCount`](/en-US/docs/Web/API/MediaTrackConstraints/channelCount) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.deviceId", "deviceId")}}
-  - : A Boolean that is `true` if the [`deviceId`](/en-US/docs/Web/API/MediaTrackConstraints/deviceId) constraint is supported in the current environment.
-- {{domxref("MediaTrackSupportedConstraints.groupId", "groupId")}}
-  - : A Boolean that is `true` if the [`groupId`](/en-US/docs/Web/API/MediaTrackConstraints/groupId) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.volume", "volume")}} {{Deprecated_Inline}} {{Non-standard_Inline}}
+  - : A Boolean that is `true` if the [`volume`](/en-US/docs/Web/API/MediaTrackConstraints/volume) constraint is supported in the current environment.
+- {{domxref("MediaTrackSupportedConstraints.width", "width")}}
+  - : A Boolean that is `true` if the [`width`](/en-US/docs/Web/API/MediaTrackConstraints/width) constraint is supported in the current environment.
 
 ### Instance properties specific to shared screen tracks
 
-For tracks containing video sources from the user's screen contents, the following additional properties are may be included in addition to those available for video tracks.
+For tracks containing video sources from the user's screen, the following additional properties may be included, in addition to those available for video tracks:
 
 - {{domxref("MediaTrackSupportedConstraints.displaySurface", "displaySurface")}}
   - : A Boolean that is `true` if the {{domxref("MediaTrackConstraints.displaySurface", "displaySurface")}} constraint is supported in the current environment.

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

@@ -0,0 +1,57 @@
+---
+title: "MediaTrackSupportedConstraints: restrictOwnAudio property"
+short-title: restrictOwnAudio
+slug: Web/API/MediaTrackSupportedConstraints/restrictOwnAudio
+page-type: web-api-instance-property
+browser-compat: api.MediaStreamTrack.applyConstraints.restrictOwnAudio_constraint
+---
+
+{{APIRef("Media Capture and Streams")}}
+
+The {{domxref("MediaTrackSupportedConstraints")}} dictionary's **`restrictOwnAudio`** property is a read-only boolean value which is present (and set to `true`) in the object returned by {{domxref("MediaDevices.getSupportedConstraints()")}} if and only if the {{Glossary("user agent")}} supports the `restrictOwnAudio` constraint. If the constraint isn't supported, it's not included in the list, so this value will never be `false`.
+
+You can access the supported constraints dictionary by calling {{domxref("MediaDevices.getSupportedConstraints()", "navigator.mediaDevices.getSupportedConstraints()")}}.
+
+## Value
+
+This property is present in the dictionary (and its value is always `true`) if the user agent supports the `restrictOwnAudio` constraint. If the property isn't present, this property is missing from the supported constraints dictionary, and you'll get {{jsxref("undefined")}} if you try to access its value.
+
+## Examples
+
+```html hidden
+<div id="result"></div>
+```
+
+```css hidden
+#result {
+  font:
+    14px "Arial",
+    sans-serif;
+}
+```
+
+```js
+const result = document.getElementById("result");
+const supported =
+  navigator.mediaDevices.getSupportedConstraints().restrictOwnAudio;
+result.textContent = supported ? "Supported!" : "Not supported!";
+```
+
+### Result
+
+{{EmbedLiveSample('Examples', 600, 80)}}
+
+## Specifications
+
+{{Specifications}}
+
+## Browser compatibility
+
+{{Compat}}
+
+## See also
+
+- [Media Capture and Streams API](/en-US/docs/Web/API/Media_Capture_and_Streams_API)
+- {{domxref("MediaDevices.getSupportedConstraints()")}}
+- {{domxref("MediaTrackSupportedConstraints")}}
+- {{domxref("MediaStreamTrack")}}