Media Capture and Streams Extensions

4.1 getUserMedia "user-chooses" semantics

This specification introduces slightly altered semantics to the getUserMedia () function called "user-chooses" that guarantee a picker will be shown to the user in cases where the user agent would otherwise choose for the user (that is: when application constraints do not narrow down the choices to a single device). This is orthoginal to permission, and offers a better and more consistent user experience across applications and user agents.

Unfortunately, since the "user-chooses" semantics may produce user agent prompts at different times and in different situations compared to the old semantics, they are somewhat incompatible with expectations in some existing web applications that tend to call getUserMedia () repeatedly and lazily instead of using e.g. stream.clone() .

4.2 Web compatibility and migration

User agents are encouraged to provide the new semantics as opt-in initially for web compatibility. User agents MUST deprecate (remove) label from MediaDeviceInfo over time, though specific migration strategies are left to user agents. User agents SHOULD migrate to offering the new semantics by default (opt-out) over time.

Since the constraints-model remains intact, web compatibility problems are expected to be limited to:

• Sites that never migrated show e.g. "Camera 1", "Camera 2" etc. instead of descriptive device labels
• Sites with no device management strategy provoke a picker in the user agent every visit for users with more than a singular choice of camera or microphone (a feature of sorts)

4.3 MediaDevices Interface Extensions

WebIDLpartial interface MediaDevices {
  readonly attribute GetUserMediaSemantics defaultSemantics;
};

4.4 MediaStreamConstraints dictionary extensions

WebIDLpartial dictionary MediaStreamConstraints {
  GetUserMediaSemantics semantics;
};

4.5 GetUserMediaSemantics enum

WebIDLenum GetUserMediaSemantics {
  "browser-chooses",
  "user-chooses"
};

4.6 Algorithms

When the getUserMedia () method is invoked, run the following steps before invoking the getUserMedia () algorithm:

1. Let mediaDevices be the object on which this method was invoked.

2. Let constraints be the method's first argument.

3. Let semanticsPresent be true if constraints .semantics exists , otherwise false .

4. Let semantics be constraints .semantics if present , or the value of mediaDevices . defaultSemantics otherwise.

5. Replace step 6.5.1. of the getUserMedia () algorithm in its entirety with the following two steps:

   1. Let descriptor be a PermissionDescriptor with its name member set to the permission name associated with kind (e.g. " camera " for "video" , " microphone " for "audio" ), and, optionally, consider its deviceId member set to any appropriate device's deviceId .

   2. If the number of unique devices sourcing tracks of media type kind in candidateSet is greater than 1 and semantics is "user-chooses" , then prompt the user to choose a device with descriptor , resulting in provided media. Otherwise, request permission to use a device with descriptor , while considering all devices being attached to a live and same-permission MediaStreamTrack in the current browsing context to mean having permission status " granted ", resulting in provided media.

      Same-permission in this context means a MediaStreamTrack that required the same level of permission to obtain as what is being requested.

      When asking the user’s permission, the user agent MUST disclose whether permission will be granted only to the device chosen, or to all devices of that kind .

      Let track be the provided media, which MUST be precisely one track of type kind from finalSet . If semantics is "browser-chooses" then the decision of which track to choose from finalSet is up to the User Agent, which MAY use the value of the computed "fitness distance" from the SelectSettings algorithm, the value of semanticsPresent , or any other internally-available information about the devices, as inputs to its decision. If semantics is "user-chooses" , and the application has not narrowed down the choices to one, then the user agent MUST ask the user to make the final selection.

      Once selected, the source of the MediaStreamTrack MUST NOT change.

      User Agents are encouraged to default to or present a default choice based primarily on fitness distance, and secondarily on the user's primary or system default device for kind (when possible). User Agents MAY allow users to use any media source, including pre-recorded media files.

4.7 Examples

<button id="start">Start</button>
<button id="chosenCamera" disabled>Camera: none</button>
<script>
let cameraTrack = null;
start.onclick = async () => {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      video: {deviceId: localStorage.cameraId}
    });
    setCameraTrack(stream.getVideoTracks()[0]);
  } catch (err) {
    console.error(err);
  }
}
chosenCamera.onclick = async () => {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({
      video: true,
      semantics: "user-chooses"
    });
    setCameraTrack(stream.getVideoTracks()[0]);
  } catch (err) {
    console.error(err);
  }
}
function setCameraTrack(track) {
  cameraTrack = track;
  const {deviceId, label} = track.getSettings();
  localStorage.cameraId = deviceId;
  chosenCamera.innerText = `Camera: ${label}`;
  chosenCamera.disabled = false;
}


</

script

>

6.1 Additional Dictionary MediaTrackConstraintSet Member

echoCancellationReferenceSinkId refers to a sink ID from [ AUDIO-OUTPUT ]. It controls the reference for echo cancellation. It applies only to audio MediaStreamTrack objects.

When the MediaTrackSettings object of the track contains "echoCancellation = false", this constraint has no effect.

When the echoCancellationReferenceSinkId is not specified, the default reference signal is the default system output. Specifying the sink id "" chooses the default system output.

The property is changeable with applyConstraints().