The MediaTrackConstraints
dictionary is used to describe a set of capabilities and the value or values each can take on. A constraints dictionary is passed into applyConstraints()
to allow a script to establish a set of exact (required) values or ranges and/or preferred values or ranges of values for the track, and the most recently-requested set of custom constraints can be retrieved by calling getConstraints()
.
For each constraint, you can typically specify an exact value you need, an ideal value you want, a range of acceptable values, and/or a value which you'd like to be as close to as possible. The specifics vary somewhat depending on the type of the constrainable property.
To learn more about how constraints work, see Capabilities, constraints, and settings.
Properties
Some combination—but not necessarily all—of the following properties will exist on the object. This may be because a given browser doesn't support the property, or because it doesn't apply. For example, because RTP doesn't provide some of these values during negotiation of a WebRTC connection, a track associated with a RTCPeerConnection
will not include certain values, such as facingMode
or groupId
.
Properties of all media tracks
deviceId
- A
ConstrainDOMString
object specifying a device ID or an array of device IDs which are acceptable and/or required. groupId
- A
ConstrainDOMString
object specifying a group ID or an array of group IDs which are acceptable and/or required.
Properties of audio tracks
autoGainControl
- A
ConstrainBoolean
object which specifies whether automatic gain control is preferred and/or required. channelCount
- A
ConstrainLong
specifying the channel count or range of channel counts which are acceptable and/or required. echoCancellation
- A
ConstrainBoolean
object specifying whether or not echo cancellation is preferred and/or required. latency
- A
ConstrainDouble
specifying the latency or range of latencies which are acceptable and/or required. noiseSuppression
- A
ConstrainBoolean
which specifies whether noise suppression is preferred and/or required. sampleRate
- A
ConstrainLong
specifying the sample rate or range of sample rates which are acceptable and/or required. sampleSize
- A
ConstrainLong
specifying the sample size or range of sample sizes which are acceptable and/or required. volume
- A
ConstrainDouble
specifying the volume or range of volumes which are acceptable and/or required.
Properties of image tracks
whiteBalanceMode
- A
String
specifying one of"none"
,"manual"
,"single-shot"
, or"continuous"
. exposureMode
- A
String
specifying one of"none"
,"manual"
,"single-shot"
, or"continuous"
. focusMode
- A
String
specifying one of"none"
,"manual"
,"single-shot"
, or"continuous"
. pointsOfInterest
- The pixel coordinates on the sensor of one or more points of interest. This is either an object in the form { x:value, y:value } or an array of such objects, where value is a double-precision integer.
exposureCompensation
- A
ConstrainDouble
(a double-precision integer) specifying f-stop adjustment by up to ±3. colorTemperature
- A
ConstrainDouble
(a double-precision integer) specifying a desired color temperature in degrees kelvin. iso
- A
ConstrainDouble
(a double-precision integer) specifying a desired iso setting. brightness
- A
ConstrainDouble
(a double-precision integer) specifying a desired brightness setting. contrast
- A
ConstrainDouble
(a double-precision integer) specifying the degree of difference between light and dark. saturation
- A
ConstrainDouble
(a double-precision integer) specifying the degree of color intensity. sharpness
- A
ConstrainDouble
(a double-precision integer) specifying the intensity of edges. focusDistance
- A
ConstrainDouble
(a double-precision integer) specifying distance to a focused object. zoom
- A
ConstrainDouble
(a double-precision integer) specifying the desired focal length. torch
- A
Boolean
defining whether the fill light is continuously connected, meaning it stays on as long as the track is active.
Properties of video tracks
aspectRatio
- A
ConstrainDouble
specifying the video aspect ratio or range of aspect ratios which are acceptable and/or required. facingMode
- A
ConstrainDOMString
object specifying a facing or an array of facings which are acceptable and/or required. frameRate
- A
ConstrainDouble
specifying the frame rate or range of frame rates which are acceptable and/or required. height
- A
ConstrainLong
specifying the video height or range of heights which are acceptable and/or required. width
- A
ConstrainLong
specifying the video width or range of widths which are acceptable and/or required. resizeMode
- A
ConstrainDOMString
object specifying a mode or an array of modes the UA can use to derive the resolution of a video track. Allowed values arenone
andcrop-and-scale
.none
means that the user agent uses the resolution provided by the camera, its driver or the OS.crop-and-scale
means that the user agent can use cropping and downscaling on the camera output in order to satisfy other constraints that affect the resolution.
These constraints apply to MediaTrackConstraints
objects specified as part of the DisplayMediaStreamConstraints
object's video
property when using getDisplayMedia()
to obtain a stream for screen sharing.
cursor
- A
ConstrainDOMString
which specifies whether or not to include the mouse cursor in the generated track, and if so, whether or not to hide it while not moving. The value may be a single one of the following strings, or an array of them to allow the browser flexibility in deciding what to do about the cursor.
always
- The mouse is always visible in the video content of the {domxref("MediaStream"), unless the mouse has moved outside the area of the content.
motion
- The mouse cursor is always included in the video if it's moving, and for a short time after it stops moving.
never
- The mouse cursor is never included in the shared video.
displaySurface
- A
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
- The stream's video track contains the entire contents of one or more of the user's screens.
window
- The stream contains a single window selected by the user for sharing.
logicalSurface
- A
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.
Specifications
Specification | Status | Comment |
Media Capture and Streams | Candidate Recommendation | Initial definition. |
MediaStream Image Capture | Working Draft | Adds image constraints. |
Browser compatibility
The compatibility table on this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Update compatibility data on GitHub
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
MediaTrackConstraints
|
Chrome
Full support 59 |
Edge
Full support ≤18 |
Firefox
Full support Yes |
IE
No support No |
Opera
Full support 46 |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support Yes |
Firefox Android
Full support Yes |
Opera Android
Full support 43 |
Safari iOS
? |
Samsung Internet Android
Full support Yes |
aspectRatio
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
No support No |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
Full support 29 |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
autoGainControl
|
Chrome
Full support Yes |
Edge
Full support ≤79 |
Firefox Full support 55 Full support 55 Full support 46 Prefixed' Implemented with the vendor prefix: moz |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android Full support 55 Full support 55 Full support 46 Prefixed' Implemented with the vendor prefix: moz |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support Yes |
channelCount
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
No support No |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
No support No |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
cursor
|
Chrome
No support No |
Edge
No support No |
Firefox
No support No |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
No support No |
Chrome Android
No support No |
Firefox Android
No support No |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
No support No |
deviceId
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox Full support 36 Full support 36 Notes' Prior to Firefox 69, Firefox only supported |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android Full support 36 Full support 36 Notes' Firefox for Android only supports |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
displaySurface
|
Chrome
No support No |
Edge
No support No |
Firefox
No support No |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
No support No |
Chrome Android
No support No |
Firefox Android
No support No |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
No support No |
echoCancellation
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
Full support 50 |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
Full support 50 |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
facingMode
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
Full support 50 |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
Full support 50 |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
frameRate
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
Full support 50 |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
Full support 50 |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
groupId
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
Full support 70 |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
No support No |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
height
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
Full support 50 |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
Full support 50 |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
latency
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
Full support 50 |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
Full support 50 |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
logicalSurface
|
Chrome
No support No |
Edge
No support No |
Firefox
No support No |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
No support No |
Chrome Android
No support No |
Firefox Android
No support No |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
No support No |
noiseSuppression
|
Chrome
Full support Yes |
Edge
Full support ≤79 |
Firefox Full support 55 Full support 55 Full support 46 Prefixed' Implemented with the vendor prefix: moz |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support Yes |
Chrome Android
Full support Yes |
Firefox Android Full support 55 Full support 55 Full support 46 Prefixed' Implemented with the vendor prefix: moz |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support Yes |
sampleRate
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
No support No |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
No support No |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
sampleSize
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
No support No |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
No support No |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
No support No |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
No support No |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 | |
width
|
Chrome
Full support 59 |
Edge
Full support ≤79 |
Firefox
Full support 50 |
IE
No support No |
Opera
Full support Yes |
Safari
? |
WebView Android
Full support 59 |
Chrome Android
Full support 59 |
Firefox Android
Full support 50 |
Opera Android
? |
Safari iOS
? |
Samsung Internet Android
Full support 7.0 |
Legend
- Full support
- Full support
- No support
- No support
- Compatibility unknown
- Compatibility unknown
- Non-standard. Expect poor cross-browser support.'
- Non-standard. Expect poor cross-browser support.
- Deprecated. Not for use in new websites.'
- Deprecated. Not for use in new websites.
- See implementation notes.'
- See implementation notes.
- Requires a vendor prefix or different name for use.'
- Requires a vendor prefix or different name for use.
See also
- Media Capture and Streams API
- Capabilities, constraints, and settings
- Screen Capture API
- Using the Screen Capture API
MediaDevices.getUserMedia()
MediaStreamTrack.getConstraints()
MediaStreamTrack.applyConstraints()
MediaDevices.getSupportedConstraints()
MediaTrackSupportedConstraints
MediaStreamTrack.getSettings()
MediaTrackConstraints by Mozilla Contributors is licensed under CC-BY-SA 2.5.