MediaStreamTrack: getCapabilities() method

The getCapabilities() method of the 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 user agent.

Once you know what the browser's capabilities are, your script can use applyConstraints() to ask for the track to be configured to match ideal or acceptable settings. See Capabilities, constraints, and settings for details of how to work with constrainable properties.

Syntax

js
getCapabilities()

Parameters

None.

Return value

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 object containing the device ID.

groupId

A ConstrainDOMString object containing a group ID.

autoGainControl

A 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 containing the channel count or channel count range.

echoCancellation

A 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 containing the latency or latency range.

noiseSuppression

A 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 containing the sample rate or sample rate range.

sampleSize

A ConstrainULong containing the sample size or sample size range.

aspectRatio

A ConstrainDouble containing the video aspect ratio (width in pixels divided by height in pixels) or aspect ratio range.

facingMode

A ConstrainDOMString object containing the camera facing mode. A camera may report multiple facings, for example "left" and "user".

frameRate

A ConstrainDouble containing the frame rate or range of frame rates which are acceptable.

height

A ConstrainULong containing the video height or height range, in pixels.

width

A ConstrainULong containing the video width or width range, in pixels.

resizeMode

A 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 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

Specification
Media Capture and Streams
# dom-mediastreamtrack-getcapabilities

Browser compatibility

BCD tables only load in the browser

See also