Media Capture and Streams

https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/
Admin
Media Capture and Streams is a W3C specification that defines JavaScript APIs for requesting access...
Tokens:97,011
Snippets:290
Trust Score:10
Update:10 months ago
Show doc for...
Tokens:
Raw
### Settings Dictionary Example with Video Track

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Example Settings dictionary showing actual values chosen by the User Agent for a video track. Contains single values for each applicable constrainable property, with values matching those defined in the corresponding Capabilities dictionary.

```JSON
{
  frameRate: 30.0,
  facingMode: 'user'
}
```

--------------------------------

### Capabilities Dictionary Example with Video Source

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Example Capabilities dictionary for a video source showing frameRate range constraints and discrete facingMode options. Demonstrates how range-based properties use min/max values while enumerated properties use arrays.

```JSON
{
  frameRate: {min: 1.0, max: 60.0},
  facingMode: ['user', 'left']
}
```

--------------------------------

### Capabilities Dictionary Example with Resolution Ranges

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Example Capabilities dictionary showing width, height, and aspectRatio constraints for a video source supporting 640x480 and 800x600 resolutions. Illustrates that individual property ranges are reported separately, not as combinations, and aspectRatio constraints indicate which combinations are actually supported.

```JSON
{
  width: {min: 640, max: 800},
  height: {min: 480, max: 600},
  aspectRatio: {min: 4/3, max: 4/3}
}
```

--------------------------------

### Get Media Device with Advanced Constraints (JavaScript)

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

This example shows how to use `getUserMedia` with more advanced constraints, including minimum and ideal values for resolution, and a minimum frame rate. It uses a try-catch block to handle potential constraint violations.

```javascript
try {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: {
      width: {min: 640, ideal: 1280},
      // The code snippet provided is incomplete in the input.
      // Assuming it would continue with height and frameRate constraints.
    }
  });
} catch (error) {
  console.error("Error applying constraints: ", error);
}
```

--------------------------------

### getUserMedia with Advanced ConstraintSets

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Requests video stream with basic constraints and multiple advanced ConstraintSets for fallback strategies. Advanced ConstraintSets are tried in order and must be satisfied together or skipped together. This example demonstrates a backoff strategy for resolution and frame rate preferences.

```javascript
try {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: {
      width: {min: 640, ideal: 1280},
      height: {min: 480, ideal: 720},
      frameRate: {min: 30},
      advanced: [
        {width: 1920, height: 1280},
        {aspectRatio: 4/3},
        {frameRate: {min: 50}},
        {frameRate: {min: 40}}
      ]
    }
  });
} catch (error) {
  if (error.name != "OverconstrainedError") {
    throw error;
  }
  // Overconstrained. Try again with a different combination (no prompt was shown)
}
```

--------------------------------

### navigator.mediaDevices.getUserMedia API

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

This section details the usage of `navigator.mediaDevices.getUserMedia` to request access to media input devices such as a camera or microphone. It includes examples of how to handle the returned media stream and manage track events.

```APIDOC
## GET /mediaDevices/getUserMedia

### Description
Requests access to a media input device, such as a camera or microphone. It returns a Promise that resolves with a `MediaStream` containing the requested tracks.

### Method
`navigator.mediaDevices.getUserMedia(constraints)`

### Parameters
#### Query Parameters
- **constraints** (MediaTrackConstraints) - Required - An object specifying the types of media that should be captured and any constraints on the captured media (e.g., resolution, frame rate).

### Request Example
```javascript
const constraints = {
  audio: true,
  video: true
};

navigator.mediaDevices.getUserMedia(constraints)
  .then(stream => {
    // Use the stream
  })
  .catch(err => {
    console.error(err);
  });
```

### Response
#### Success Response (Promise resolves with MediaStream)
- **MediaStream** - An object representing the stream of media data.

#### Response Example
```javascript
// On success, the promise resolves with a MediaStream object
// Example structure of MediaStream (internal details vary):
// {
//   id: "some-stream-id",
//   active: true,
//   getTracks: () => [...] // Array of MediaStreamTrack objects
// }
```
```

--------------------------------

### Apply Constraints with Ideal Values - JavaScript

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Demonstrates applying ideal constraints to a MediaStreamTrack to request specific camera settings like resolution and frame rate. The browser will attempt to match these values as best effort, potentially returning different values if exact settings are unavailable. The example retrieves and logs the resulting settings.

```javascript
await track.applyConstraints({
  width: 1920,
  height: 1080,
  frameRate: 30,
});
const {width, height, frameRate} = track.getSettings();

console.log(`${width}x${height}x${frameRate}`); // 1920x1080x30, or it might be e.g.
                                                // 1280x720x30 as best effort
```

--------------------------------

### Basic getUserMedia Constraint with Multiple Properties

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Demonstrates a basic constraint structure with three individual property constraints (width, height, aspectRatio) for video stream acquisition. The User Agent will attempt to satisfy all constraints individually and may satisfy a subset if full satisfaction is not possible. This example shows ideal value constraints without minimum requirements.

```JavaScript
const stream = await navigator.mediaDevices.getUserMedia({
  video: {
    width: 1280,
    height: 720,
    aspectRatio: 3/2
  }
});
```

--------------------------------

### InputDeviceInfo Interface

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Represents an input media device and provides access to its capabilities. It extends MediaDeviceInfo and offers a method to get track capabilities.

```WebIDL
[Exposed=Window, SecureContext]
interface InputDeviceInfo : MediaDeviceInfo {
  MediaTrackCapabilities getCapabilities();
};
```

--------------------------------

### GET enumerateDevices()

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Retrieves a list of all available media input and output devices. Returns a Promise that resolves with an array of MediaDeviceInfo objects describing each device's kind, label, and groupId, filtered based on user permissions.

```APIDOC
## GET enumerateDevices()

### Description
Enumerates all media input and output devices available to the User Agent. Returns detailed information about each device, with visibility and labels determined by user permissions.

### Method
GET (asynchronous)

### Endpoint
MediaDevices.enumerateDevices()

### Parameters
None

### Request Example
```javascript
const devices = await navigator.mediaDevices.enumerateDevices();
```

### Response
#### Success Response (Promise resolves)
- **sequence<MediaDeviceInfo>** (Array) - Array of MediaDeviceInfo objects
  - **deviceId** (String) - Unique identifier for the device
  - **kind** (String) - Device kind: "audioinput", "audiooutput", or "videoinput"
  - **label** (String) - Human-readable device name (empty string if no permission)
  - **groupId** (String) - Identifier grouping devices belonging to the same physical device

#### Response Example
```json
[
  {
    "deviceId": "default",
    "kind": "videoinput",
    "label": "Front Camera",
    "groupId": "group1"
  },
  {
    "deviceId": "abc123",
    "kind": "audioinput",
    "label": "Microphone",
    "groupId": "group1"
  },
  {
    "deviceId": "def456",
    "kind": "audiooutput",
    "label": "Speaker",
    "groupId": "group2"
  }
]
```

### Notes
- Device enumeration respects user permissions; labels are only exposed if permission is granted
- The promise rejects if device enumeration cannot proceed
- Results may be empty if no devices are available or user has denied permissions
```

--------------------------------

### GET /media/getUserMedia

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Requests access to media devices (camera/microphone) with optional constraints. Constraints can be passed to influence device selection and help find suitable replacement devices if preferred devices become unavailable.

```APIDOC
## GET /media/getUserMedia

### Description
Requests user permission to access media devices (camera and/or microphone) with optional constraint specifications for device selection and capability requirements.

### Method
GET

### Endpoint
/media/getUserMedia

### Parameters

#### Query Parameters
- **audio** (boolean|object) - Optional - Request audio device with optional constraints
- **video** (boolean|object) - Optional - Request video device with optional constraints
- **deviceId** (string) - Optional - Preferred device identifier from previous sessions

### Request Body (Constraints Object)
- **width** (number|object) - Optional - Video width requirements
- **height** (number|object) - Optional - Video height requirements
- **frameRate** (number|object) - Optional - Frame rate requirements
- **echoCancellation** (boolean) - Optional - Audio echo cancellation requirement
- **noiseSuppression** (boolean) - Optional - Audio noise suppression requirement
- **autoGainControl** (boolean) - Optional - Audio auto-gain control requirement
- **channelCount** (number|object) - Optional - Audio channel count (mono/stereo/surround)

### Request Example (Device Preference with Constraints)
```javascript
await navigator.mediaDevices.getUserMedia({
  audio: {
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true
  },
  video: {
    deviceId: {exact: "previousCameraId"},
    width: {min: 640, ideal: 1920, max: 1920},
    height: {min: 480, ideal: 1080, max: 1080},
    frameRate: {ideal: 30}
  }
});
```

### Response

#### Success Response (200)
Returns MediaStream object containing requested tracks
- **id** (string) - Stream identifier
- **active** (boolean) - Stream active status
- **getTracks()** (function) - Get all tracks in stream
- **getAudioTracks()** (function) - Get audio tracks
- **getVideoTracks()** (function) - Get video tracks

#### Response Example
```javascript
const stream = await navigator.mediaDevices.getUserMedia({
  audio: true,
  video: {width: 1920, height: 1080}
});
const videoTrack = stream.getVideoTracks()[0];
const audioTrack = stream.getAudioTracks()[0];
```

#### Error Responses
- **NotAllowedError** (403) - User denied permission
- **NotFoundError** (404) - Requested device not available
- **OverconstrainedError** (422) - Device cannot satisfy constraints
- **TypeError** (400) - Invalid constraint specification

### Use Cases

#### Device Selection with Fallbacks
Use constraints to prefer specific devices from previous sessions while enabling fallback to compatible alternatives if preferred devices are unavailable or overridden by user.

#### Quality Requirements
Specify dimensional requirements and frame rate needs for video quality while allowing flexibility through min/ideal/max constraint specification.

#### Audio Processing
Request specific audio processing features (echo cancellation, noise suppression) and channel configurations based on application requirements.
```

--------------------------------

### MediaStream Constructor Overloads

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

The MediaStream constructor can be invoked in three ways: with no arguments to create an empty stream, with an existing MediaStream object to copy its tracks, or with a sequence of MediaStreamTrack objects to initialize the new stream with specified tracks. The User Agent manages the internal track set.

```WebIDL
interface MediaStream : EventTarget {
  constructor();
  constructor(MediaStream stream);
  constructor(sequence<MediaStreamTrack> tracks);
  readonly attribute DOMString id;
  sequence<MediaStreamTrack> getAudioTracks();
  sequence<MediaStreamTrack> getVideoTracks();
  sequence<MediaStreamTrack> getTracks();
  MediaStreamTrack? getTrackById(DOMString trackId);
  undefined addTrack(MediaStreamTrack track);
  undefined removeTrack(MediaStreamTrack track);
  MediaStream clone();
  readonly attribute boolean active;
  attribute EventHandler onaddtrack;
  attribute EventHandler onremovetrack;
};
```

--------------------------------

### Check Constraint Support and Get Front Camera

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Verifies browser support for specific video constraints ('facingMode', 'aspectRatio', 'resizeMode') using `getSupportedConstraints`. If any required constraint is not supported, it throws an `OverconstrainedError`. If supported, it attempts to get the front camera with advanced constraints for specific aspect ratios and resolutions.

```javascript
async function getFrontCameraRes() {
  const supports = navigator.mediaDevices.getSupportedConstraints();

  for (const constraint of ["facingMode", "aspectRatio", "resizeMode"]) {
    if (!(constraint in supports)) {
      throw new OverconstrainedError(constraint, "Not supported");
    }
  }
  return await navigator.mediaDevices.getUserMedia({
    video: {
      facingMode: {exact: 'user'},
      advanced: [
        {aspectRatio: 16/9, height: 1080, resizeMode: "none"},
        {aspectRatio: 4/3, width: 1280, resizeMode: "none"}
      ]
    }
  });
}
```

--------------------------------

### Initialize DeviceChangeEventInit Dictionary

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Defines the DeviceChangeEventInit dictionary that extends EventInit with a sequence of MediaDeviceInfo objects. This dictionary is used to initialize device change events with information about available media devices. The devices member defaults to an empty array if not specified.

```WebIDL
dictionary DeviceChangeEventInit : EventInit {
  sequence<MediaDeviceInfo> devices = [];
};
```

--------------------------------

### GET /mediastream/track/:trackId

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Retrieves a specific MediaStreamTrack by its ID. Returns the track object if found, or null if no track with the given ID exists in the stream.

```APIDOC
## getTrackById(DOMString trackId)

### Description
Returns a MediaStreamTrack object with the specified ID, or null if not found.

### Method
GET

### Signature
```
MediaStreamTrack? getTrackById(DOMString trackId)
```

### Parameters
#### Query Parameters
- **trackId** (DOMString) - Required - The unique identifier of the track to retrieve

### Return Value
- **Type**: MediaStreamTrack or null
- **Description**: The MediaStreamTrack object with the matching ID, or null if no such track exists in the stream's track set

### Response Example
```javascript
const track = mediaStream.getTrackById("track-id-123");
// Returns: MediaStreamTrack object or null
```
```

--------------------------------

### enumerateDevices Method

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Collects information about the User Agent's available media input and output devices. Returns a promise that resolves with a sequence of MediaDeviceInfo objects representing available media input and output devices. Input devices are represented as InputDeviceInfo which extends MediaDeviceInfo.

```APIDOC
## enumerateDevices()

### Description
Collects information about the User Agent's available media input and output devices. This method returns a promise that resolves with a sequence of MediaDeviceInfo objects. Elements representing input devices will be of type InputDeviceInfo.

### Method
GET

### Endpoint
navigator.mediaDevices.enumerateDevices()

### Return Type
Promise<MediaDeviceInfo[]>

### Response
#### Success Response (200)
Array of MediaDeviceInfo objects containing:
- **deviceId** (string) - Unique identifier for the device
- **groupId** (string) - Identifier for the group of devices
- **kind** (string) - Type of device: "audioinput", "audiooutput", or "videoinput"
- **label** (string) - Human-readable label describing the device

#### Response Example
[
  {
    "deviceId": "default",
    "groupId": "group1",
    "kind": "audioinput",
    "label": "Default Audio Input"
  },
  {
    "deviceId": "camera123",
    "groupId": "group1",
    "kind": "videoinput",
    "label": "Front Camera"
  },
  {
    "deviceId": "speaker456",
    "groupId": "group1",
    "kind": "audiooutput",
    "label": "Speakers"
  }
]

### Algorithm Steps
1. Create a new promise
2. Check if device enumeration can proceed
3. Build lists of microphones, cameras, and other devices
4. Filter devices based on document permissions for "microphone" and "camera" features
5. Apply exposure decision algorithm for non-camera/microphone devices
6. Combine and return device lists in order: microphones, cameras, other devices

### Privacy Considerations
- This method adds to the fingerprinting surface exposed by the User Agent
- Exposure is limited to two bits of information (camera availability, microphone availability) until getUserMedia() is called
- User Agents may mitigate fingerprinting by pretending the system has a camera and microphone until getUserMedia() is invoked with reasonable constraints

### Device Handling Rules
- System default microphone is prepended to microphoneList
- System default camera is prepended to cameraList
- System default audio output receives a special "default" deviceId
- Camera and microphone sources SHOULD be enumerable
- Information exposure can be truncated based on mediaDevices exposure policies
```

--------------------------------

### GET /mediastream/tracks

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Retrieves all tracks (both audio and video) currently in the MediaStream's track set. Returns a complete sequence of MediaStreamTrack objects in the stream.

```APIDOC
## getTracks()

### Description
Returns a sequence of all tracks in the MediaStream, regardless of type.

### Method
GET

### Signature
```
sequence<MediaStreamTrack> getTracks()
```

### Parameters
None

### Return Value
- **Type**: sequence<MediaStreamTrack>
- **Description**: An ordered sequence containing all MediaStreamTrack objects in the track set

### Response Example
```javascript
const allTracks = mediaStream.getTracks();
// Returns: [MediaStreamTrack, MediaStreamTrack, ...]
```
```

--------------------------------

### getSettings

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Retrieves the current settings of all constrainable properties.

```APIDOC
## GET /settings

### Description
Returns the current settings of all the constrainable properties, including platform defaults and those set by ApplyConstraints.

### Method
GET

### Endpoint
/settings

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **settings** (dictionary) - A dictionary containing the current settings for all constrainable properties.

#### Response Example
```json
{
  "settings": {
    "width": 1280,
    "height": 720,
    "frameRate": 30
  }
}
```
```

--------------------------------

### GET /mediastream/videoTracks

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Retrieves all video tracks currently in the MediaStream's track set. Returns a sequence of MediaStreamTrack objects where the kind attribute is 'video'.

```APIDOC
## getVideoTracks()

### Description
Returns a sequence of all video tracks in the MediaStream.

### Method
GET

### Signature
```
sequence<MediaStreamTrack> getVideoTracks()
```

### Parameters
None

### Return Value
- **Type**: sequence<MediaStreamTrack>
- **Description**: An ordered sequence containing all MediaStreamTrack objects in the track set where the kind is "video"

### Response Example
```javascript
const videoTracks = mediaStream.getVideoTracks();
// Returns: [MediaStreamTrack, MediaStreamTrack, ...]
```
```

--------------------------------

### GET /mediastream/audioTracks

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Retrieves all audio tracks currently in the MediaStream's track set. Returns a sequence of MediaStreamTrack objects where the kind attribute is 'audio'.

```APIDOC
## getAudioTracks()

### Description
Returns a sequence of all audio tracks in the MediaStream.

### Method
GET

### Signature
```
sequence<MediaStreamTrack> getAudioTracks()
```

### Parameters
None

### Return Value
- **Type**: sequence<MediaStreamTrack>
- **Description**: An ordered sequence containing all MediaStreamTrack objects in the track set where the kind is "audio"

### Response Example
```javascript
const audioTracks = mediaStream.getAudioTracks();
// Returns: [MediaStreamTrack, MediaStreamTrack, ...]
```
```

--------------------------------

### Audio Constraints - Latency

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Defines the latency constraint property for audio MediaStreamTrack objects, specifying the time between audio processing start and data availability to the next processing step.

```APIDOC
## Audio Constraint: latency

### Description
Specifies the latency or latency range for audio processing in seconds.

### Property
**latency** (double)

### Definition
Latency is the time between start of processing (for instance, when sound occurs in the real world) to the data being available to the next step in the process.

### Value
- Represents the target latency of the configuration
- Actual latency may show some variation from the target
- Expressed in seconds

### Use Cases

#### Low Latency (Critical)
- Real-time voice communication
- Interactive audio applications
- Live audio monitoring

#### High Latency (Acceptable)
- Batch audio processing
- Power-constrained applications
- Non-interactive audio recording

### Notes
- Low latency is critical for some applications
- High latency may be acceptable for others due to power constraints
```

--------------------------------

### getSettings()

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Returns the current, active settings of all constrainable properties. This reflects the actual current state of the media object.

```APIDOC
## GET /settings

### Description
Returns the current settings of all the constrainable properties of the object, whether they are platform defaults or have been set by the ApplyConstraints algorithm.

### Method
GET

### Endpoint
/settings

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **settings** (dictionary) - A dictionary containing the current settings for each constrainable property.

#### Response Example
```json
{
  "width": 1280,
  "height": 720,
  "frameRate": 30,
  "facingMode": "user"
}
```
```

--------------------------------

### MediaDevices.enumerateDevices()

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Enumerates all available input and output media devices on the system. Returns a promise that resolves to an array of MediaDeviceInfo objects describing available cameras, microphones, and other media devices.

```APIDOC
## GET enumerateDevices

### Description
Enumerates all available input and output media devices on the system, including cameras, microphones, and speakers.

### Method
Asynchronous - Returns a Promise

### Endpoint
navigator.mediaDevices.enumerateDevices()

### Parameters
No parameters required

### Request Example
```javascript
navigator.mediaDevices.enumerateDevices()
```

### Response
#### Success Response (Promise resolves)
- **deviceId** (string) - Unique identifier for the device
- **groupId** (string) - Group identifier for related devices
- **kind** (string) - Device type: "audioinput", "audiooutput", or "videoinput"
- **label** (string) - Device name (empty if not permitted)

#### Response Example
```javascript
[
  {
    "deviceId": "default",
    "groupId": "group1",
    "kind": "videoinput",
    "label": "Front Camera"
  },
  {
    "deviceId": "device2",
    "groupId": "group1",
    "kind": "audioinput",
    "label": "Built-in Microphone"
  }
]
```
```

--------------------------------

### GET navigator.mediaDevices

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Retrieves the MediaDevices object associated with the current Window. This object provides access to connected media input and output devices such as cameras and microphones for device enumeration and media stream configuration.

```APIDOC
## GET navigator.mediaDevices

### Description
Retrieves the MediaDevices object associated with the current Window. This object enables scripts to query the User Agent about connected media input and output devices.

### Method
GET

### Endpoint
navigator.mediaDevices

### Context
Navigator Interface Extensions

### Interface Definition
```
partial interface Navigator {
  [SameObject, SecureContext] readonly attribute MediaDevices mediaDevices;
};
```

### Requirements
- **SecureContext**: Required - Must be accessed from a secure context (HTTPS)
- **SameObject**: The returned MediaDevices object is the same object on repeated accesses

### Response

#### Success Response
- **Type**: MediaDevices
- **Description**: Returns the Window object's associated MediaDevices object
- **Access**: Read-only

### Return Value
- Returns the relevant global object's associated MediaDevices object

### Usage Notes
- Each Window has an associated MediaDevices object created upon Window object creation
- The MediaDevices object is created with the Window object's relevant realm
- Used to enumerate local media devices and configure media streams
```

--------------------------------

### Define Capabilities Dictionary WebIDL

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Template for creating a Capabilities dictionary in WebIDL. Capabilities contain key-value pairs where keys are constrainable properties and values are subsets of allowed values for those properties. Returned by the User Agent to describe available media track properties.

```WebIDL
dictionary Capabilities {};
```

--------------------------------

### ConstrainablePattern Interface Definition

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Defines the WebIDL interface template for objects that support constrainable properties. This pattern provides methods to get capabilities, constraints, and settings, as well as apply new constraints to media stream objects.

```APIDOC
## ConstrainablePattern Interface

### Description
A WebIDL interface template that defines the pattern for constrainable objects in media capture streams. This interface cannot be directly inherited but serves as a template that other interfaces (such as MediaStreamTrack) implement by providing their own copy of the WebIDL definitions.

### Interface Definition
```
[Exposed=Window]
interface ConstrainablePattern {
  Capabilities  getCapabilities();
  Constraints   getConstraints();
  Settings      getSettings();
  Promise<undefined> applyConstraints(optional Constraints constraints = {});
};
```

### Methods

#### getCapabilities()
- **Returns**: `Capabilities` - A dictionary describing the aggregate allowable values for each constrainable property exposed
- **Description**: Returns the capabilities object containing all possible values for constrainable properties
- **Internal Slot Used**: [[Capabilities]]

#### getConstraints()
- **Returns**: `Constraints` - A dictionary of currently applied constraints
- **Description**: Returns the constraints dictionary containing the currently set constraints
- **Internal Slot Used**: [[Constraints]]

#### getSettings()
- **Returns**: `Settings` - A dictionary describing the currently active settings values for each constrainable property
- **Description**: Returns the settings object containing the current active values for all constrainable properties
- **Internal Slot Used**: [[Settings]]

#### applyConstraints(optional Constraints constraints)
- **Parameters**: 
  - **constraints** (Constraints, optional) - New constraints to apply, defaults to empty dictionary {}
- **Returns**: `Promise<undefined>` - A promise that resolves when constraints are applied
- **Description**: Applies new constraints to the constrainable object asynchronously

### Internal Slots

Constrainable objects implementing this pattern must define three internal slots:

1. **[[Capabilities]]** (Capabilities dictionary)
   - Initialized to a Capabilities dictionary describing aggregate allowable values for each constrainable property
   - Set to empty dictionary if no constrainable properties are exposed

2. **[[Constraints]]** (Constraints dictionary)
   - Initialized to an empty Constraints dictionary
   - Updated when applyConstraints() is called

3. **[[Settings]]** (Settings dictionary)
   - Initialized to a Settings dictionary describing currently active setting values
   - Set to empty dictionary if no constrainable properties are exposed

### Implementation Notes

- This is a template pattern, not a directly inheritable interface
- Implementing interfaces must provide their own copy of the WebIDL definitions
- The semantics defined in this pattern remain consistent across all implementations
- Example implementation: MediaStreamTrack Interface
```

--------------------------------

### getUserMedia with Min/Ideal Constraints and Error Handling

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Demonstrates an advanced constraint structure combining minimum requirements (min) with ideal target values for video properties including frameRate. The promise will reject if minimum constraints cannot be satisfied. Otherwise, the User Agent attempts to satisfy ideal values while respecting all minimum requirements.

```JavaScript
try {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: {
      width: {min: 640, ideal: 1280},
```

--------------------------------

### MediaStream Assignment to Media Elements

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Describes how to assign a MediaStream to media elements using the srcObject attribute and the initialization requirements for audio and video tracks. MediaStreams are non-preloadable, non-seekable linear media timelines that start at 0 and increment in real time.

```APIDOC
## MediaStream Assignment to Media Elements

### Description
Assign a MediaStream to an HTMLMediaElement using the srcObject attribute. MediaStreams represent linear media timelines starting at 0 that increment in real time during playback.

### Implementation Requirements

#### Track Initialization
When an `AudioTrack` or `VideoTrack` is created from a MediaStream:
- **id** - Must be initialized to the corresponding MediaStreamTrack id
- **label** - Must be initialized to the corresponding MediaStreamTrack label
- **kind** - Must be initialized to `"main"`
- **language** - Must be initialized to empty string

#### Playback Behavior
- User Agent MUST always play current data from the MediaStream
- User Agent MUST NOT buffer MediaStream data
- Timeline does not increment when playback is paused
- No ordering requirements for AudioTrackList and VideoTrackList

#### Usage Example
```javascript
const mediaElement = document.getElementById('video');
const mediaStream = await navigator.mediaDevices.getUserMedia({ video: true });
mediaElement.srcObject = mediaStream;
mediaElement.play();
```
```

--------------------------------

### Legacy getUserMedia Interface - WebIDL

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Defines the legacy callback-based getUserMedia method on the Navigator interface for backwards compatibility. This method accepts constraints and success/error callbacks, though the modern Promise-based approach via MediaDevices is now recommended. Requires SecureContext.

```webidl
partial interface Navigator {
  [SecureContext] undefined getUserMedia(MediaStreamConstraints constraints,
                                    NavigatorUserMediaSuccessCallback successCallback,
                                    NavigatorUserMediaErrorCallback errorCallback);
};
```

--------------------------------

### Define Settings Dictionary WebIDL

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Template for creating a Settings dictionary in WebIDL. Settings contain the actual single values chosen by the User Agent for each constrainable property, and must correspond to values defined in the Capabilities dictionary.

```WebIDL
dictionary Settings {};
```

--------------------------------

### Apply Custom Frame Rate to Native Resolution

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

First, gets the camera stream at its native resolution and frame rate. Then, it derives constraints from the current settings (handling potential rotation) and applies a specific, exact frame rate (10 FPS) using `applyConstraints`, potentially changing the `resizeMode`.

```javascript
async function nativeResolutionButDecimatedFrameRate() {
  const stream = await navigator.mediaDevices.getUserMedia({
    video: {
      resizeMode: 'none', // means native resolution and frame rate
      width: 1280,
      height: 720,
      aspectRatio: 16 / 9 // aspect ratios may not be exactly accurate
    }
  });
  const [track] = stream.getVideoTracks();
  const {width, height, aspectRatio} = track.getSettings();

  // Constraints are in landscape, while settings may be rotated (portrait)
  if (width < height) {
    [width, height] = [height, width];
    aspectRatio = 1 / aspectRatio;
  }

  await track.applyConstraints({
    resizeMode: 'crop-and-scale',
    width: {exact: width},
    height: {exact: height},
    frameRate: {exact: 10},
    aspectRatio,
  });

  return stream;
}
```

--------------------------------

### Extend MediaDevices Interface with getUserMedia and getSupportedConstraints

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Extends the MediaDevices interface with two key methods: getSupportedConstraints() returns the constraints recognized by the User Agent, and getUserMedia() is a Promise-based method that requests permission to access media input devices with optional constraints. This is the official recommended definition replacing the callback-based Navigator.getUserMedia method.

```WebIDL
partial interface MediaDevices {
  MediaTrackSupportedConstraints getSupportedConstraints();
  Promise<MediaStream> getUserMedia(optional MediaStreamConstraints constraints = {});
};
```

--------------------------------

### Query Media Stream Constraints and Settings

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Use getConstraints() to retrieve the currently applied constraint specifications and getSettings() to query the actual Settings values chosen by the User Agent for each constrainable property.

```javascript
// Query the current constraints
const currentConstraints = stream.getVideoTracks()[0].getConstraints();

// Query the actual settings chosen by the User Agent
const currentSettings = stream.getVideoTracks()[0].getSettings();

// Example: currentSettings might return {frameRate: 35, width: 1280, height: 720}
```

--------------------------------

### Settings Dictionary Structure (WebIDL)

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

The basic structure of the Settings dictionary defined using WebIDL, serving as a template for specific implementations.

```webidl
WebIDLdictionary Settings {};
```

--------------------------------

### Get User Media Stream with Track Event Handling

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Demonstrates how to request audio and video streams from the user's device using getUserMedia API. The code disables a button during the request, handles successful stream acquisition, and re-enables the button when all tracks end. Includes error handling for permission denials or device unavailability.

```JavaScript
const startBtn = document.getElementById('startBtn');

startBtn.onclick = async () => {
  try {
    startBtn.disabled = true;
    const constraints = {
      audio: true,
      video: true
    };

    const stream = await navigator.mediaDevices.getUserMedia(constraints);

    for (const track of stream.getTracks()) {
      track.onended = () => {
        startBtn.disabled = stream.getTracks().some((t) => t.readyState == 'live');
      };
    }
  } catch (err) {
    console.error(err);
  }
};
```

--------------------------------

### Legacy `getUserMedia` Interface

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

This section details the legacy `getUserMedia` interface on the `Navigator` object, provided for backward compatibility. It uses callbacks for success and error handling.

```APIDOC
## Legacy `getUserMedia` Interface

### Description
Provides a legacy callback-based interface for `getUserMedia` for backward compatibility. Developers are encouraged to use `navigator.mediaDevices.getUserMedia()`.

### Method
`getUserMedia`

### Endpoint
`navigator.getUserMedia()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Arguments
- **constraints** (`MediaStreamConstraints`) - Required - An object specifying the media types and settings to be captured.
- **successCallback** (`NavigatorUserMediaSuccessCallback`) - Required - A function called with the `MediaStream` upon successful acquisition.
- **errorCallback** (`NavigatorUserMediaErrorCallback`) - Required - A function called with a `DOMException` if an error occurs.
```

--------------------------------

### getCapabilities()

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Retrieves a dictionary of supported constrainable property names for the media object. This helps in understanding what properties can be configured.

```APIDOC
## GET /capabilities

### Description
Returns the dictionary of the names of the constrainable properties that the object supports.

### Method
GET

### Endpoint
/capabilities

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **capabilities** (dictionary) - A dictionary where keys are constrainable property names and values describe their capabilities.

#### Response Example
```json
{
  "width": {
    "min": 640,
    "max": 1920
  },
  "height": {
    "min": 480,
    "max": 1080
  },
  "frameRate": {
    "min": 15,
    "max": 60
  }
}
```
```

--------------------------------

### Apply Exact Constraints with Error Handling - JavaScript

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Demonstrates applying exact constraints to a MediaStreamTrack with minimum, maximum, and ideal values for fine-grained control. Includes error handling for OverconstrainedError when the camera cannot satisfy the exact constraints. Retrieves settings and logs results or constraint failure details.

```javascript
try {
  await track.applyConstraints({
    width: {exact: 1920},
    height: {exact: 1080},
    frameRate: {min: 25, ideal: 30, max: 30},
  });
  const {width, height, frameRate} = track.getSettings();

  console.log(`${width}x${height}x${frameRate}`); // 1920x1080x25-30!

} catch (error) {
  if (error.name != "OverconstrainedError") {
    throw error;
  }
  console.log(`This camera cannot produce the requested ${error.constraint}.`);
}
```

--------------------------------

### getUserMedia Method Definition

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

The getUserMedia method prompts users for permission to access their webcam or audio input devices. It accepts MediaStreamConstraints, a success callback, and an error callback. The method returns a promise that resolves with a MediaStream object when permission is granted, or rejects if permission is denied or valid tracks cannot be found.

```WebIDL
getUserMedia(constraints: MediaStreamConstraints, successCallback: NavigatorUserMediaSuccessCallback, errorCallback: NavigatorUserMediaErrorCallback): void
```

--------------------------------

### Capabilities Dictionary Structure (WebIDL)

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

The basic structure of the Capabilities dictionary defined using WebIDL, serving as a template for specific implementations.

```webidl
WebIDLdictionary Capabilities {};
```

--------------------------------

### Define ConstrainablePattern WebIDL Interface Template

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

WebIDL interface template defining the ConstrainablePattern structure for media capture constraints. This template cannot be directly inherited but provides a pattern for other interfaces to implement. Includes methods to retrieve capabilities, constraints, and settings, plus apply new constraints asynchronously. Each implementing interface must provide its own WebIDL copy while referencing the semantics defined here.

```webidl
[Exposed=Window]
interface ConstrainablePattern {
  Capabilities  getCapabilities();
  Constraints   getConstraints();
  Settings      getSettings();
  Promise<undefined> applyConstraints(optional Constraints constraints = {});
};
```

--------------------------------

### getSupportedConstraints Method

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Returns a dictionary containing all constrainable properties supported by the User Agent. The returned dictionary only includes properties that the browser implements, and remains constant during a browsing session.

```APIDOC
## getSupportedConstraints

### Description
Returns a dictionary whose members are the constrainable properties known to the User Agent. A supported constrainable property MUST be represented and any constrainable properties not supported by the User Agent MUST NOT be present in the returned dictionary.

### Method
GET

### Endpoint
navigator.mediaDevices.getSupportedConstraints()

### Parameters
No parameters required.

### Response
#### Success Response
- **Dictionary** (Object) - A dictionary object containing supported constrainable properties as keys, with each key mapped to a boolean value of `true`

#### Response Example
```json
{
  "width": true,
  "height": true,
  "aspectRatio": true,
  "frameRate": true,
  "facingMode": true,
  "volume": true,
  "sampleRate": true,
  "echoCancellation": true,
  "noiseSuppression": true,
  "autoGainControl": true
}
```

### Notes
- The values returned represent what the User Agent implements
- The returned dictionary will not change during a browsing session
- Only supported constrainable properties are included in the response
```

--------------------------------

### getUserMedia Method

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Prompts the user for permission to use their webcam or other video or audio input device. Returns a promise that resolves with a MediaStream object if the user grants permission and valid tracks are found, or rejects if permission is denied or valid tracks cannot be found.

```APIDOC
## getUserMedia

### Description
Prompts the user for permission to use their Web cam or other video or audio input. This method returns a promise that will be fulfilled with a suitable MediaStream object if the user accepts valid tracks, or rejected if there is a failure in finding valid tracks or if the user denies permission.

### Method
POST

### Endpoint
navigator.mediaDevices.getUserMedia(constraints)

### Parameters
#### Request Body
- **constraints** (MediaStreamConstraints) - Required - A dictionary specifying the types of media requested and any constraints on those media types. Must contain at least one of "audio" or "video" properties set to either `true` or a constraints dictionary.

#### Constraint Properties
- **audio** (boolean|AudioConstraints) - Optional - Request audio track. Set to `true` for default audio, or provide specific constraints.
- **video** (boolean|VideoConstraints) - Optional - Request video track. Set to `true` for default video, or provide specific constraints.

### Request Example
```javascript
const constraints = {
  audio: true,
  video: {
    width: { min: 640, ideal: 1280, max: 1920 },
    height: { min: 480, ideal: 720, max: 1080 },
    facingMode: "user"
  }
};

navigator.mediaDevices.getUserMedia(constraints)
  .then(mediaStream => {
    // Handle successful stream
  })
  .catch(error => {
    // Handle error
  });
```

### Response
#### Success Response (200)
- **MediaStream** (Object) - A MediaStream object containing the requested audio and/or video tracks
  - **getTracks()** (Function) - Returns all tracks in the stream
  - **getAudioTracks()** (Function) - Returns only audio tracks
  - **getVideoTracks()** (Function) - Returns only video tracks

#### Response Example
```javascript
{
  "id": "stream-id-123",
  "active": true,
  "getTracks": function() { /* ... */ },
  "getAudioTracks": function() { /* ... */ },
  "getVideoTracks": function() { /* ... */ }
}
```

### Error Handling

#### TypeError
- Returned when requestedMediaTypes is empty (no audio or video requested)
- Returned when a required constraint name is not in the list of allowed required constraints for device selection

#### InvalidStateError (DOMException)
- Returned when the document is not fully active

#### NotFoundError
- Returned when no suitable media input devices are found (candidateSet is empty after device enumeration)

#### NotAllowedError / PermissionDenied
- Returned when user denies permission for microphone ("microphone" permission)
- Returned when user denies permission for camera ("camera" permission)
- Returned when all devices of a requested type have permission state set to "denied"

#### OverconstrainedError
- Returned when specified constraints cannot be satisfied by any available device
- Includes failedConstraint property indicating which constraint caused the failure

### Processing Steps
1. Validate that at least one media type (audio or video) is requested
2. Verify the document is fully active
3. Check permission state for microphone (if audio requested) and camera (if video requested)
4. Wait until the document is in view before proceeding
5. For each requested media type, enumerate candidate devices
6. Apply constraints using the SelectSettings algorithm
7. Remove candidates that don't satisfy constraints
8. Check permission state for each candidate device
9. Prompt user for permission if needed
10. Return promise with MediaStream or rejection reason

### Notes
- The argument is required despite optional appearing in WebIDL
- Audio-only constraints in video requests are ignored (and vice versa)
- Constraint failure information can be used for fingerprinting purposes
- User preference, security reasons, or platform limitations may cause permission failure
- The method must wait until the document is in view before accessing media devices
```

--------------------------------

### MediaDevices WebIDL Interface Definition

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/index

Defines the MediaDevices interface as an EventTarget exposed to Window context with SecureContext requirement. Provides methods for enumerating devices and event handling for device changes. The ondevicechange attribute allows listening to device availability changes.

```webidl
[Exposed=Window, SecureContext]
interface MediaDevices : EventTarget {
  attribute EventHandler ondevicechange;
  Promise<sequence<MediaDeviceInfo>> enumerateDevices();
};
```

--------------------------------

### InputDeviceInfo Interface

Source: https://www.w3.org/TR/2025/CRD-mediacapture-streams-20251009/TR/mediacapture-streams

Provides access to the capabilities of an input media device.

```APIDOC
## InputDeviceInfo Interface

### Description
Provides access to the capabilities of an input media device (audio or video).

### Inheritance
Inherits from `MediaDeviceInfo`.

### Methods

#### `getCapabilities()`
- **Description**: Returns a `MediaTrackCapabilities` object describing the primary capabilities of the device's associated media track (audio or video) without any user-defined constraints. These capabilities should match those obtained from `getUserMedia` for the same device ID. If no device access has been granted or the device info has been filtered, an empty dictionary is returned.
- **Method**: GET
- **Endpoint**: N/A (Method on `InputDeviceInfo` object)
- **Return Value**: `MediaTrackCapabilities` object or an empty dictionary.
```
Tokens:
Raw