Add Fx132 support note for MediaStreamTrack.getCapabilities(), and im… (

mdn#36189) * Add Fx132 support note for MediaStreamTrack.getCapabilities(), and improve docs a bit * Update files/en-us/web/api/media_capture_and_streams_api/constraints/index.md Co-authored-by: Vadim Makeev <[email protected]> * Update files/en-us/web/api/mediastreamtrack/getcapabilities/index.md Co-authored-by: Vadim Makeev <[email protected]> --------- Co-authored-by: Vadim Makeev <[email protected]>
DaddynIssac7 · Oct 9, 2024 · 11135cd · 11135cd
1 parent 9af87d5
commit 11135cd
Show file tree

Hide file tree

Showing 4 changed files with 95 additions and 19 deletions.
diff --git a/files/en-us/mozilla/firefox/releases/132/index.md b/files/en-us/mozilla/firefox/releases/132/index.md
@@ -49,6 +49,8 @@ This article provides information about the changes in Firefox 132 that affect d
 
 #### Media, WebRTC, and Web Audio
 
+- The {{domxref("MediaStreamTrack.getCapabilities()")}} method is now supported. This returns an object detailing the accepted values or value range for each constrainable property of the associated {{domxref("MediaStreamTrack")}} ([Firefox bug 1179084](https://bugzil.la/1179084)).
+
 #### Removals
 
 ### WebAssembly

diff --git a/files/en-us/web/api/media_capture_and_streams_api/constraints/index.md b/files/en-us/web/api/media_capture_and_streams_api/constraints/index.md
@@ -109,7 +109,43 @@ So-called advanced constraints are created by adding an `advanced` property to t
 
 You can call {{domxref("MediaStreamTrack.getCapabilities()")}} to get a list of all of the supported capabilities and the values or ranges of values which each one accepts on the current platform and user agent. This function returns an object which lists each constrainable property supported by the browser and a value or range of values which are supported for each one of those properties.
 
-> **Note:** `getCapabilities()` hasn't been implemented yet by all major browsers. For the time being, you'll have to try to get what you need, and if you can't, decide what to do at that point. See Firefox [Firefox bug 1179084](https://bugzil.la/1179084), for example.
+For example, the following snippet will result in the user being asked for permission to access their local camera and microphone. Once permission is granted, `MediaTrackCapabilities` objects will be logged to the console that detail the capabilities of each {{domxref("MediaStreamTrack")}}:
+
+```js
+navigator.mediaDevices
+  .getUserMedia({ video: true, audio: true })
+  .then((stream) => {
+    const tracks = stream.getTracks();
+    tracks.map((t) => console.log(t.getCapabilities()));
+  });
+```
+
+An example capabilities object looks like this:
+
+```js
+{
+  "autoGainControl": [
+    true,
+    false
+  ],
+  "channelCount": {
+    "max": 1,
+    "min": 1
+  },
+  "deviceId": "jjxEMqxIhGdryqbTjDrXPWrkjy55Vte70kWpMe3Lge8=",
+  "echoCancellation": [
+    true,
+    false
+  ],
+  "groupId": "o2tZiEj4MwOdG/LW3HwkjpLm1D8URat4C5kt742xrVQ=",
+  "noiseSuppression": [
+    true,
+    false
+  ]
+}
+```
+
+The exact contents of the object will depend on the browser and media hardware.
 
 ## Applying constraints
 

diff --git a/files/en-us/web/api/mediastreamtrack/getcapabilities/index.md b/files/en-us/web/api/mediastreamtrack/getcapabilities/index.md
@@ -9,13 +9,11 @@ browser-compat: api.MediaStreamTrack.getCapabilities
 {{APIRef("Media Capture and Streams")}}
 
 The **`getCapabilities()`** method of
-the {{domxref("MediaStreamTrack")}} interface returns a
-`MediaTrackCapabilities` object which specifies the values or range of
-values which each constrainable property, based upon the platform and {{Glossary("user agent")}}.
+the {{domxref("MediaStreamTrack")}} interface returns an object detailing the accepted values or value range for each constrainable property of the associated `MediaStreamTrack`, based upon the platform and {{Glossary("user agent")}}.
 
 Once you know what the browser's capabilities are, your script can use
 {{domxref("MediaStreamTrack.applyConstraints", "applyConstraints()")}} to ask for the
-track to be configured to match ideal or acceptable settings. See [Capabilities, constraints, and settings](/en-US/docs/Web/API/Media_Capture_and_Streams_API/Constraints) for details on how to work with constrainable properties.
+track to be configured to match ideal or acceptable settings. See [Capabilities, constraints, and settings](/en-US/docs/Web/API/Media_Capture_and_Streams_API/Constraints) for details of how to work with constrainable properties.
 
 ## Syntax
 
@@ -29,42 +27,82 @@ None.
 
 ### Return value
 
-A `MediaTrackCapabilities` object which specifies the value or range of values which are supported for each of the user agent's supported constrainable properties, containing the following members:
+A `MediaTrackCapabilities` object which specifies the accepted value or range of values supported for each of the user agent's constrainable properties. This can contain the following members:
 
 - `deviceId`
   - : A [`ConstrainDOMString`](/en-US/docs/Web/API/MediaTrackConstraints#constraindomstring) object containing the device ID.
 - `groupId`
   - : A [`ConstrainDOMString`](/en-US/docs/Web/API/MediaTrackConstraints#constraindomstring) object containing a group ID.
 - `autoGainControl`
-  - : A [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) object reporting if the source can do auto gain control.
+  - : A [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) object reporting if the source can automatically control the input signal's gain.
     If the feature can be controlled by a script the source will report both true and false as possible values.
 - `channelCount`
-  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the channel count or range of channel counts.
+  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the channel count or channel count range.
 - `echoCancellation`
-  - : A [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) object reporting if the source can do echo cancellation.
-    If the feature can be controlled by a script the source will report both true and false as possible values.
+  - : A [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) object reporting if the source can provide echo cancellation.
+    If the feature can be controlled by a script the source will report both `true` and `false` as possible values.
 - `latency`
-  - : A [`ConstrainDouble`](/en-US/docs/Web/API/MediaTrackConstraints#constraindouble) containing the latency or range of latencies.
+  - : A [`ConstrainDouble`](/en-US/docs/Web/API/MediaTrackConstraints#constraindouble) containing the latency or latency range.
 - `noiseSuppression`
-  - : A [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) object reporting if the source can do noise suppression.
-    If the feature can be controlled by a script the source will report both true and false as possible values.
+  - : A [`ConstrainBoolean`](/en-US/docs/Web/API/MediaTrackConstraints#constrainboolean) object reporting if the source can provide noise suppression.
+    If the feature can be controlled by a script the source will report both `true` and `false` as possible values.
 - `sampleRate`
-  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the sample rate or range of sample rates.
+  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the sample rate or sample rate range.
 - `sampleSize`
-  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the sample size or range of sample sizes.
+  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the sample size or sample size range.
 - `aspectRatio`
-  - : A [`ConstrainDouble`](/en-US/docs/Web/API/MediaTrackConstraints#constraindouble) containing the video {{glossary("aspect ratio")}} (width in pixels divided by height in pixels) or range of aspect ratios.
+  - : A [`ConstrainDouble`](/en-US/docs/Web/API/MediaTrackConstraints#constraindouble) containing the video {{glossary("aspect ratio")}} (width in pixels divided by height in pixels) or aspect ratio range.
 - `facingMode`
   - : A [`ConstrainDOMString`](/en-US/docs/Web/API/MediaTrackConstraints#constraindomstring) object containing the camera facing mode. A camera may report multiple facings, for example "left" and "user".
 - `frameRate`
   - : A [`ConstrainDouble`](/en-US/docs/Web/API/MediaTrackConstraints#constraindouble) containing the frame rate or range of frame rates which are acceptable.
 - `height`
-  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the video height or range of heights in pixels.
+  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the video height or height range, in pixels.
 - `width`
-  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the video width or range of widths in pixels.
+  - : A [`ConstrainULong`](/en-US/docs/Web/API/MediaTrackConstraints#constrainulong) containing the video width or width range, in pixels.
 - `resizeMode`
   - : A [`ConstrainDOMString`](/en-US/docs/Web/API/MediaTrackConstraints#constraindomstring) object containing the mode or an array of modes the UA can use to derive the resolution of the video track.
 
+## Examples
+
+The following snippet will result in the user being asked for permission to access their local camera and microphone. Once permission is granted, `MediaTrackCapabilities` objects will be logged to the console that detail the capabilities of each {{domxref("MediaStreamTrack")}}:
+
+```js
+navigator.mediaDevices
+  .getUserMedia({ video: true, audio: true })
+  .then((stream) => {
+    const tracks = stream.getTracks();
+    tracks.map((t) => console.log(t.getCapabilities()));
+  });
+```
+
+An example capabilities object looks like this:
+
+```js
+{
+  "autoGainControl": [
+    true,
+    false
+  ],
+  "channelCount": {
+    "max": 1,
+    "min": 1
+  },
+  "deviceId": "jjxEMqxIhGdryqbTjDrXPWrkjy55Vte70kWpMe3Lge8=",
+  "echoCancellation": [
+    true,
+    false
+  ],
+  "groupId": "o2tZiEj4MwOdG/LW3HwkjpLm1D8URat4C5kt742xrVQ=",
+  "noiseSuppression": [
+    true,
+    false
+  ]
+}
+```
+
+The exact contents of the object will depend on the browser and media hardware.
+
 ## Specifications
 
 {{Specifications}}

diff --git a/files/en-us/web/api/mediastreamtrack/index.md b/files/en-us/web/api/mediastreamtrack/index.md
@@ -53,7 +53,7 @@ In addition to the properties listed below, `MediaStreamTrack` has constrainable
 - {{domxref("MediaStreamTrack.clone()")}}
   - : Returns a duplicate of the `MediaStreamTrack`.
 - {{domxref("MediaStreamTrack.getCapabilities()")}}
-  - : Returns the a list of constrainable properties available for the `MediaStreamTrack`.
+  - : Returns an object detailing the accepted values or value range for each constrainable property of the associated `MediaStreamTrack`.
 - {{domxref("MediaStreamTrack.getConstraints()")}}
   - : Returns a {{domxref('MediaTrackConstraints')}} object containing the currently set constraints for the track; the returned value matches the constraints last set using {{domxref("MediaStreamTrack.applyConstraints", "applyConstraints()")}}.
 - {{domxref("MediaStreamTrack.getSettings()")}}