媒体捕获与流 (Media Capture and Streams)

MediaStream

参见 MediaStream 构造函数算法

无参数。

MediaStream

参见 MediaStream 构造函数算法

MediaStream

参见 MediaStream 构造函数算法

id，类型为 DOMString，只读

id 属性 MUST 返回对象创建时被初始化到的值。

当创建一个 MediaStream 时，用户代理 MUST 生成一个标识符字符串，并 MUST 将对象的 id 属性初始化为该字符串，除非对象是作为规定流 ID 如何初始化的特殊用途算法的一部分而创建的。一个好的做法是使用 UUID [rfc4122]，其规范形式为 36 个字符长。为避免指纹识别，实现 SHOULD 在生成 UUID 时使用 RFC 4122 第 4.4 或 4.5 节中的形式。

指定流 ID 如何初始化的算法的一个例子是关联传入网络组件与 MediaStream 对象的算法。 [WEBRTC]

active，类型为 boolean，只读

如果此 MediaStream 是 活跃 (active) 的，则 active 属性 MUST 返回 true，否则返回 false。

onaddtrack，类型为 EventHandler

此事件处理程序的事件类型为 addtrack。

onremovetrack，类型为 EventHandler

此事件处理程序的事件类型为 removetrack。

getAudioTracks()

返回表示此流中音频轨道的 MediaStreamTrack 对象序列。

getAudioTracks 方法 MUST 返回一个序列，该序列表示此流 轨道集 中所有 [[Kind]] 等于 "audio" 的 MediaStreamTrack 对象的快照。从 轨道集 到序列的转换是由 用户代理 定义的，顺序不必在调用之间保持稳定。

getVideoTracks()

返回表示此流中视频轨道的 MediaStreamTrack 对象序列。

getVideoTracks 方法 MUST 返回一个序列，该序列表示此流 轨道集 中所有 [[Kind]] 等于 "video" 的 MediaStreamTrack 对象的快照。从 轨道集 到序列的转换是由 用户代理 定义的，顺序不必在调用之间保持稳定。

getTracks()

返回表示此流中所有轨道的 MediaStreamTrack 对象序列。

getTracks 方法 MUST 返回一个序列，该序列表示此流 轨道集 中所有 MediaStreamTrack 对象的快照，与 [[Kind]] 无关。从 轨道集 到序列的转换是由用户代理定义的，顺序不必在调用之间保持稳定。

getTrackById()

getTrackById 方法 MUST 返回来自此流 轨道集 中 [[Id]] 等于 trackId 的 MediaStreamTrack 对象，或者如果不存在此类轨道，则返回 null。

addTrack()

将给定的 MediaStreamTrack 添加到此 MediaStream 中。

当调用 addTrack 方法时，用户代理 MUST 运行以下步骤

1. 设 track 为方法参数，stream 为调用此方法的 MediaStream 对象。

2. 如果 track 已在 stream 的 轨道集 中，则终止这些步骤。

3. 添加 track 到 stream 的 轨道集 中。

removeTrack()

从该 MediaStream 中移除给定的 MediaStreamTrack 对象。

当调用 removeTrack 方法时，用户代理 MUST 运行以下步骤

1. 设 track 为方法参数，stream 为调用此方法的 MediaStream 对象。

2. 如果 track 不在 stream 的 轨道集 中，则终止这些步骤。

3. 移除 track 从 stream 的 轨道集 中。

clone()

克隆给定的 MediaStream 及其所有轨道。

当调用 clone() 方法时，用户代理 MUST 运行以下步骤

1. 设 streamClone 为新构建的 MediaStream 对象。

2. 将 streamClone.MediaStream.id 初始化为新生成的值。

3. 克隆此 MediaStream 对象中的每个轨道，并将结果添加到 streamClone 的 轨道集 中。

4. 返回 streamClone。

期望触发 addtrack 或 removetrack 事件的用户代理代码，应该通过来自另一个对象的引用来保持目标 MediaStream 对象处于存活状态。在尝试对 MediaStream 对象进行垃圾回收时，不需要考虑 addtrack 或 removetrack 事件监听器的存在。

constructor()

构造一个新的 MediaStreamTrackEvent。

track 类型为 MediaStreamTrack，只读

track 属性表示与事件关联的 MediaStreamTrack 对象。

track 类型为 MediaStreamTrack，必填

mediaDevices 类型为 MediaDevices，只读

返回 此 相关全局对象 的 关联的 MediaDevices。

ondevicechange 类型为 EventHandler

此事件处理程序的事件类型为 devicechange。

enumerateDevices

收集关于 用户代理 可用的媒体输入和输出设备的信息。

此方法返回一个 promise。如果枚举成功，该 promise 将以表示 用户代理 可用媒体输入和输出设备的 MediaDeviceInfo 对象序列进行 完成。

此序列中表示输入设备的元素将是 InputDeviceInfo 类型，它扩展了 MediaDeviceInfo。

摄像头和麦克风源 应该 是可枚举的。添加其他类型源的规范将提供关于源类型是否应该可枚举的建议。

当调用 enumerateDevices() 方法时，用户代理 必须运行以下步骤

1. 令 p 为一个新的 promise。

2. 令 proceed 为 设备枚举可以进行 (此) 的结果。

3. 令 mediaDevices 为 此。

4. 并行执行以下步骤

   1. 当 proceed 为 false 时，用户代理 必须 等待继续执行下一步，直到排队执行一个任务将 proceed 设置为 设备枚举可以进行 (mediaDevices) 的结果，该结果会将 proceed 设置为 true。

   2. 令 resultList 为 创建设备信息对象列表 (mediaDevices 和 mediaDevices.[[storedDeviceList]]) 的结果。

   3. 解析 p 为 resultList。

5. 返回 p。

要执行 创建设备信息对象列表，给定 mediaDevices 和 deviceList，运行以下步骤

1. 令 resultList 为一个空列表。

2. 令 microphoneList、cameraList 和 otherDeviceList 为空列表。

3. 令 document 为 mediaDevices 的 相关全局对象 的 关联 Document。

4. 对 deviceList 中的每个已发现设备 device 运行以下子步骤

   1. 如果 device 不是麦克风，或者 document 不 允许使用 由 "microphone" 标识的功能，则中止这些子步骤并继续处理下一个设备（如果有）。

   2. 令 deviceInfo 为 创建设备信息对象 (device, mediaDevices) 以表示 device 的结果。

   3. 如果 device 是系统默认麦克风，则将 deviceInfo 预置到 microphoneList。否则，将 deviceInfo 追加到 microphoneList。

5. 对 deviceList 中的每个已发现设备 device 运行以下子步骤

   1. 如果 device 不是相机，或者 document 不 允许使用 由 "camera" 标识的功能，则中止这些子步骤并继续处理下一个设备（如果有）。

   2. 令 deviceInfo 为 创建设备信息对象 (device, mediaDevices) 以表示 device 的结果。

   3. 如果 device 是系统默认相机，则将 deviceInfo 预置到 cameraList。否则，将 deviceInfo 追加到 cameraList。

6. 如果 mediaDevices 上 麦克风信息可以被公开 为 false，则将 microphoneList 截断为其第一项。

7. 如果 mediaDevices 上 相机信息可以被公开 为 false，则将 cameraList 截断为其第一项。

8. 对 deviceList 中的每个已发现设备 device 运行以下子步骤

   1. 如果 device 是麦克风或相机，则中止这些子步骤并继续处理下一个设备（如果有）。

   2. 运行 针对除相机和麦克风之外设备的暴露决策算法，并将 device、microphoneList、cameraList 和 mediaDevices 作为输入。如果该算法的结果为 false，则中止这些子步骤并继续处理下一个设备（如果有）。

   3. 令 deviceInfo 为 创建设备信息对象 (device, mediaDevices) 以表示 device 的结果。

   4. 将 deviceInfo 追加到 otherDeviceList。

   5. 如果 device 是系统默认音频输出，运行以下子步骤

      1. 令 defaultAudioOutputInfo 为 创建设备信息对象 (device, mediaDevices) 以表示 device 的结果。

      2. 设置 defaultAudioOutputInfo 的 deviceId 为 "default"。

      3. 用户代理 应该 更新 defaultAudioOutputInfo 的 label，以明确它是系统默认音频输出。

      4. 将 defaultAudioOutputInfo 预置到 otherDeviceList。

9. 将 microphoneList 中的所有设备按顺序追加到 resultList。

10. 将 cameraList 中的所有设备按顺序追加到 resultList。

11. 将 otherDeviceList 中的所有设备按顺序追加到 resultList。

12. 返回 resultList。

由于此方法通过媒体捕获设备的可用性在浏览会话和来源之间返回持久信息，它增加了 用户代理 公开的指纹识别表面。

只要相关全局对象的关联 Document 未进行捕获，此方法将仅限于暴露两比特的信息：是否有摄像头以及是否有麦克风。用户代理可以通过假定系统拥有摄像头和麦克风来减轻此风险，例如在相关全局对象的关联 Document 使用被认为合理的约束调用 getUserMedia() 之前。

当相关全局对象的关联 Document 开始捕获后，它会通过所有媒体捕获设备的列表提供额外的持久跨源信息，包括它们的分组和与捕获设备关联的人类可读标签，这进一步增加了指纹识别的攻击面。

用户代理可以通过清理设备标签来限制信息暴露。例如，这可能意味着移除标签中包含的用户姓名，但保留设备制造商或型号信息。重要的是，清理后的标签应允许用户识别对应的设备。

deviceId 类型为 DOMString，只读

所表示设备的标识符。该设备 必须 由其标识符及其 kind 唯一标识。

为了确保存储的标识符被识别，在顶层可遍历对象中，同源 Document 中的标识符 必须 相同。在子可导航对象中，是否在跨文档中保持标识符相同的决定 必须 遵循用户代理的存储分区规则（如 localStorage），以避免干扰跨站点关联的缓解措施。如果标识符能够唯一地识别用户，则它在来自其他源的文档中 必须 是不可猜测的，以防止标识符被用于在不同源之间关联同一用户。标识符可以在不同源之间重用，只要它不与用户绑定且可以通过其他方式（如 User-Agent 字符串）猜测出来即可。

如果任何本地设备已挂载到来自此源的页面中的活动 MediaStreamTrack 上，或者已授予此源访问本地设备的存储权限，则该标识符 必须 被持久化，除非下文另有详细说明。唯一且稳定的标识符让应用程序能够跨多次访问保存、识别可用性并直接请求特定的源。

然而，只要没有任何本地设备挂载到来自此源的页面中的活动 MediaStreamTrack，并且没有授予此源访问本地设备的存储权限，则用户代理 可以 在来自此源的最后一次浏览会话关闭后清除该标识符。如果用户代理选择在这种情况下不清除该标识符，则它 必须 提供让用户能够像查看和删除 Cookie 一样显式查看和删除该标识符的途径。

由于 deviceId 可能会在浏览会话之间持久存在，为了减少其作为指纹识别机制的可能性，deviceId 应被视为像 Cookie [COOKIES] 一样的其他持久化存储机制，即用户代理 不得 为被禁止使用 Cookie 的站点持久化设备标识符，并且用户代理 必须 在清除其他持久化存储时轮换跨源设备标识符。

kind 类型为 MediaDeviceKind，只读

所表示设备的种类。

label 类型为 DOMString，只读

描述此设备的标签（例如 "External USB Webcam"）。此标签旨在让最终用户能够区分不同设备。应用程序不能假设标签包含任何特定信息，例如设备类型或型号。如果设备没有关联的标签，则此属性 必须 返回空字符串。

groupId 类型为 DOMString，只读

所表示设备的组标识符。如果两个设备属于同一物理设备，它们具有相同的组标识符。例如，代表同一耳机扬声器和麦克风的音频输入和输出设备具有相同的 groupId。

组标识符 必须 为每个 文档 唯一生成。

toJSON

当被调用时，执行 [WEBIDL] 的 默认 toJSON 步骤。

getCapabilities

返回一个 MediaTrackCapabilities 对象，描述设备 MediaStream（根据其 kind 值）的主音频或视频轨道，在没有任何用户提供的约束的情况下。这些能力 必须 与通过在 getUserMedia({deviceId: id}) 返回的 MediaStream 中的此类第一个 MediaStreamTrack 上调用 getCapabilities() 所获得的能力完全一致，其中 id 是该 MediaDeviceInfo 的 deviceId 属性值。

如果尚未授予对任何本地设备的访问权限，且此 InputDeviceInfo 已就唯一识别信息进行了过滤（参见上述 enumerateDevices() 结果的描述），则此方法返回一个空字典。

constructor()

将 this.devices 初始化为从 eventInitDict.devices 创建冻结数组 的结果。

devices 类型为 FrozenArray<MediaDeviceInfo>，只读

devices 属性返回一个 MediaDeviceInfo 对象数组，表示此时可用设备的列表。

userInsertedDevices 类型为 FrozenArray<MediaDeviceInfo>，只读

userInsertedDevices 属性返回一个仅包含 devices 中用户最近物理插入或激活的 MediaDeviceInfo 对象的数组，且这些对象是作为结果新暴露的。否则，返回一个空列表。

用户代理 可以 包含用户在调用 getUserMedia() 之前插入或激活的设备，前提是此事件标志着它们的首次暴露，且用户未在 getUserMedia() 中选择设备。

如果存在 MediaDeviceInfo 对象，它们也 必须 存在于 devices 中。

注

用户在调用期间（或紧接在调用之前）插入设备可能是他们希望立即使用该设备的强烈信号。

鼓励应用程序依赖此属性将此信号与因设备信息暴露变化而可能发生的 devices 差异区分开来。

注

如果该属性缺失，则意味着此用户代理尚未升级以实现此版本的规范。

devices 类型为 sequence<MediaDeviceInfo>，默认值为 []

devices 成员是一个 MediaDeviceInfo 对象数组，表示可用设备。

getSupportedConstraints

返回一个字典，其成员是 用户代理 已知的可约束属性。受支持的可约束属性 必须 被表示，而 用户代理 不支持的任何可约束属性 不得 出现在返回的字典中。返回的值代表 用户代理 所实现的内容，并且在浏览会话期间不会改变。

getUserMedia

提示用户授予使用其摄像头或其他视频或音频输入设备的权限。

constraints 参数是一个 MediaStreamConstraints 类型的字典。

此方法返回一个 Promise。如果用户接受了下述有效轨道，该 Promise 将被兑现（fulfilled），并返回一个合适的 MediaStream 对象。

如果未能找到有效的轨道或用户拒绝权限（如下所述），该 Promise 将被拒绝（rejected）。

当调用 getUserMedia() 方法时，用户代理 必须 运行以下步骤

1. 令 constraints 为该方法的第一个参数。

2. 令 requestedMediaTypes 为 constraints 中值为字典或 true 的媒体类型集合。

3. 如果 requestedMediaTypes 是空集，返回一个被 TypeError 拒绝的 Promise。根据 WebIDL 规则，“optional”一词出现在 WebIDL 中，但调用成功必须提供该参数。

4. 令 document 为 相关全局对象 的关联 Document。

5. 如果 document 不完全活跃，返回一个被 DOMException 对象 拒绝的 Promise，其 name 属性值为 "InvalidStateError"。

6. 如果 requestedMediaTypes 包含 "audio" 且 document 未被允许使用“麦克风”权限名称标识的功能，跳转到下方的 Permission Failure 步骤。

7. 如果 requestedMediaTypes 包含 "video" 且 document 未被允许使用“摄像头”权限名称标识的功能，跳转到下方的 Permission Failure 步骤。

8. 令 mediaDevices 为 此。

9. 令 isInView 为 是否在视图中 算法的结果。

10. 令 p 为一个新的 promise。

11. 并行执行以下步骤

    1. 当 isInView 为 false 时，用户代理 必须 等待，直到排队的任务将 isInView 设置为 是否在视图中 算法的结果，并使 isInView 为 true，然后才进入下一步。

    2. 令 finalSet 为一个（初始时）空集。

    3. 对于 requestedMediaTypes 中的每种媒体类型 kind，运行以下步骤

       1. 对于每种类型为 kind 的每个可能源设备的配置，设想一个 候选者 作为最终 MediaStreamTrack 的占位符，该轨道持有一个源设备并配置有由其特定设置组成的设置字典。

          将此候选集合称为 candidateSet。

          如果 candidateSet 是空集，跳转到下方的 NotFound Failure 步骤。

       2. 如果 constraints 中 kind 条目的值为 true，则将 CS 设置为空约束集（无约束）。否则，继续并将 CS 设置为 constraints 中 kind 条目的值。
       3. 移除 CS 中任何未为类型为 kind 的 MediaStreamTrack 对象定义的可约束属性。这意味着 "video" 中的纯音频约束和 "audio" 中的纯视频约束会被直接忽略，而不会导致 OverconstrainedError。

       4. 如果 CS 包含一个必要约束成员，且其名称不在设备选择的允许必要约束列表中，则用 TypeError 拒绝 p，并终止这些步骤。

       5. 对 candidateSet 中的每个候选者执行 SelectSettings 算法，并以 CS 作为约束集。如果该算法返回 undefined，从 candidateSet 中移除该候选者。这通过验证至少存在一个满足约束的设置字典，来排除无法满足约束的设备。

          如果 candidateSet 为空集，令 failedConstraint 为任何在执行 SelectSettings 算法时检查的所有设置字典中适应度距离为无穷大的必要约束，若无则为 ""，并跳转到下方的 Constraint Failure 步骤。

          此错误在用户给出任何设备授权之前，提供了有关底层设备无法生成什么的信息，因此可以用作指纹识别攻击面。

       6. 读取当前 Document 中所有未挂载到活动 MediaStreamTrack 上的 candidateSet 中候选设备的当前权限状态。从 candidateSet 中移除设备权限状态为 "denied" 的任何候选者。

          如果 candidateSet 现在为空，表明该类型的所有设备都处于 "denied" 状态，跳转到下方的 Permission Failure 步骤。

       7. 根据之前确定的用户偏好、出于安全原因或平台限制，可选择跳转到下方的 Permission Failure 步骤。

       8. 将 candidateSet 中的所有候选者添加到 finalSet。

    4. 令 stream 为一个新的空 MediaStream 对象。

    5. 对于 requestedMediaTypes 中的每种媒体类型 kind，最好同时运行以下子步骤

       注

       鼓励 用户代理 将对不同种类媒体的并发请求捆绑为单个面向用户的权限提示。

       1. 请求使用 PermissionDescriptor 的权限，将其 name 成员设置为与 kind 关联的权限名称（例如，"video" 的 "camera"，"audio" 的 "microphone"），同时将当前 Document 中挂载到活动且 相同权限 MediaStreamTrack 上的所有设备视为具有 "granted" 的权限状态，从而得到一组提供的媒体。相同权限 在此上下文中意味着获得该 MediaStreamTrack 所需的权限级别与当前请求的相同（例如，未隔离）。

          在询问用户权限时，用户代理 必须 披露权限是仅授予所选设备，还是授予该 kind 的所有设备。

          注

          如果用户从未响应，此算法在此步骤停滞。

       2. 如果请求的结果为 "denied"，跳转到下方的 Permission Failure 步骤。

    6. 令 hasSystemFocus 为 false。

    7. 当 hasSystemFocus 为 false 时，用户代理 必须 等待，直到排队的任务将 hasSystemFocus 设置为 系统是否有焦点 算法的结果，并使 hasSystemFocus 为 true，然后才进入下一步。

    8. 设置设备信息暴露（在 mediaDevices 上，使用 requestedMediaTypes 和 true）。

    9. 对于 requestedMediaTypes 中的每种媒体类型 kind，运行以下子步骤

       1. 令 finalCandidate 为所提供的媒体，它 必须 精确地是 finalSet 中类型为 kind 的一个 候选者。从 finalSet 中选择哪一个候选者的决定完全由 用户代理 决定，并可以通过询问用户来确定。

          用户代理 应当 使用来自 SelectSettings 算法的计算出的 适应度距离 值作为选择算法的输入。然而，它 可以 也使用关于设备的其他内部可用信息，例如用户偏好。

          注

          这意味着不保证满足非必要约束的值。

          鼓励 用户代理 默认使用用户针对该 kind 的首选或系统默认设备（如果可能）。用户代理 可以 允许用户使用任何媒体源，包括预录制的媒体文件。

       2. 请求的结果为 "granted"。如果操作系统/程序/网页锁等硬件错误阻止了访问，则从 finalSet 中移除对应的候选者。如果 finalSet 中没有类型为 kind 的候选者，用一个新的 DOMException 对象 拒绝 p，其 name 属性值为 "NotReadableError"，并终止这些步骤。否则，用更新后的 finalSet 重启这些子步骤。

          如果设备访问因上述原因之外的任何其他原因失败，从 finalSet 中移除对应的候选者。如果 finalSet 中没有类型为 kind 的候选者，用一个新的 DOMException 对象 拒绝 p，其 name 属性值为 "AbortError"，并终止这些步骤。否则，用更新后的 finalSet 重启这些子步骤。

       3. 令 grantedDevice 为 finalCandidate 的源设备。

       4. 使用 grantedDevice 的 deviceId（即 deviceId），将 mediaDevices.[[devicesLiveMap]][deviceId] 设置为 true（如果尚未为 true），并将 mediaDevices.[[devicesAccessibleMap]][deviceId] 设置为 true（如果尚未为 true）。

       5. 令 track 为使用 grantedDevice 和 mediaDevices 创建 MediaStreamTrack 的结果。MediaStreamTrack 的源 不得 改变。

       6. 将 track 添加到 stream 的轨道集中。

    10. 对 stream 中的所有轨道运行 ApplyConstraints 算法，并使用适当的约束。如果其中任何一个返回除 undefined 之外的结果，令 failedConstraint 为该结果，并跳转到下方的 Constraint Failure 步骤。

    11. 对于 stream 中的每个 track，使用 track.[[Source]] 和 mediaDevices 将轨道源绑定到 MediaDevices。

    12. 解析 p 并返回 stream，然后终止这些步骤。

    13. NotFound Failure:

        1. 如果 getUserMedia 特殊失败是允许的（给定 requestedMediaTypes）返回 false，跳转到下方的 Permission Failure 步骤。

        2. 用一个新的 DOMException 对象 拒绝 p，其 name 属性值为 "NotFoundError"。

    14. Constraint Failure:

        1. 如果 getUserMedia 特殊失败是允许的（给定 requestedMediaTypes）返回 false，跳转到下方的 Permission Failure 步骤。

        2. 令 message 为 undefined 或一个信息性的人类可读消息，令 constraint 为 failedConstraint（如果 设备信息可以被暴露 为 true），否则为 ""。

        3. 拒绝 p，并返回一个新的 OverconstrainedError，它是通过调用 OverconstrainedError(constraint, message) 创建的。

    15. Permission Failure: 拒绝 p，并返回一个新的 DOMException 对象，其 name 属性值为 "NotAllowedError"。

12. 返回 p。

video 类型为 (boolean or MediaTrackConstraints)，默认值为 false

如果为 true，则请求返回的 MediaStream 包含一个视频轨道。如果提供了 Constraints 结构，则进一步指定该视频轨道的性质和设置。如果为 false，则 MediaStream 不得 包含视频轨道。

audio 类型为 (boolean or MediaTrackConstraints)，默认值为 false

如果为 true，则请求返回的 MediaStream 包含一个音频轨道。如果提供了 Constraints 结构，则进一步指定该音频轨道的性质和设置。如果为 false，则 MediaStream 不得 包含音频轨道。

getCapabilities

getCapabilities() 方法返回对象支持的可约束属性名称字典。调用时，用户代理 必须 返回 [[Capabilities]] 内部槽位的值。

注

底层硬件可能无法精确映射到为可约束属性定义的范围。如果可能，条目 应当 定义如何将硬件设置转换和缩放到为该属性定义的值上。例如，假设一个假设的 fluxCapacitance 属性范围从 -10（最小值）到 10（最大值），但普通硬件设备仅支持“关”、“中”和“全”的值。可约束属性定义可能会指定，对于此类硬件，用户代理 应将范围值 -10 映射到“关”，10 映射到“全”，0 映射到“中”。它还可能指出，当 ConstraintSet 强制要求值为 3 时，用户代理 应尝试在硬件上设置“中”值，并且 getSettings() 应返回 fluxCapacitance 为 0，因为这是定义为对应于“中”的值。

getConstraints

getConstraints() 方法返回该对象最近一次成功调用 ApplyConstraints 算法 时的参数 Constraints，并保持指定的顺序。注意，返回的一些高级 ConstraintSet 可能当前并未满足。要检查哪些 ConstraintSet 当前生效，应用程序应使用 getSettings。UA 可以 返回一个在所有情况下与所应用约束效果相同的约束集，而不是返回如上所述的确切约束。调用时，用户代理 必须 返回 [[Constraints]] 内部槽位的值。

getSettings

getSettings() 方法返回对象所有可约束属性的当前设置，无论它们是平台默认值还是由 ApplyConstraints 算法 设置的。注意，设置是一个符合约束的目标值，因此有时可能与测得的性能不同。调用时，用户代理 必须 返回 [[Settings]] 内部槽位的值。

applyConstraints

当 applyConstraints 模板方法 被调用时，用户代理 必须 执行以下步骤：

1. 令 object 为调用此方法的对象。

2. 令 newConstraints 为此方法的参数。

3. 令 p 为一个新的 promise。

4. 并行运行以下步骤，如果多次调用此方法，需保持调用顺序：

   1. 令 failedConstraint 为以 newConstraints 为参数运行 ApplyConstraints 算法 的结果。

   2. 令 successfulSettings 为上述步骤中的算法完成后 object 的当前设置。

   3. 排队执行一个运行以下步骤的任务

      1. 如果 failedConstraint 不为 undefined，令 message 为 undefined 或人类可读的提示信息，拒绝 p，并传入由调用 OverconstrainedError(failedConstraint, message) 创建的新 OverconstrainedError，然后终止这些步骤。在这种情况下，现有约束保持有效。

      2. 将 object 的 [[Constraints]] 内部槽位设置为 newConstraints 或一个在所有情况下效果与 newConstraints 相同的 Constraints 字典。

      3. 将 object 的 [[Settings]] 内部槽位设置为 successfulSettings。

      4. 解析 (resolve) p 为 undefined。

5. 返回 p。

用于应用约束的 ApplyConstraints 算法 如下所述。以下是一些用于算法陈述的初步定义。

我们使用术语 设置字典（settings dictionary） 来表示可能作为设置应用于对象的一组值。

对于字符串值约束，若序列中的一个值与被比较的值完全相同，则定义下文中的 "==" 为真。

我们定义 适应度距离（fitness distance） 为 设置字典 与约束集 CS 之间，对于 CS 中 存在 的每个成员（由 constraintName 和 constraintValue 对表示）的下列值的总和：

1. 如果 constraintName 不受 用户代理 支持，适应度距离为 0。

2. 如果该约束是 必要（required） 的（即 constraintValue 包含一个或多个名为 'min'、'max' 或 'exact' 的成员，或者其本身是高级 ConstraintSet 中的裸值），且 设置字典 的 constraintName 成员的值不满足该约束或不 存在，则适应度距离为正无穷大。

3. 如果约束不适用于此类对象，适应度距离为 0（即该约束不影响适应度距离）。

4. 如果 constraintValue 是布尔值，但可约束属性不是，则适应度距离基于 设置字典 的 constraintName 成员是否 存在，根据公式计算。

   (constraintValue == exists) ? 0 : 1

5. 如果 设置字典 的 constraintName 成员 不存在，适应度距离为 1。

6. 如果未指定理想值（即 constraintValue 不包含名为 'ideal' 的成员，或者若将裸值视为 'ideal' 且其不是裸值），适应度距离为 0。
7. 对于所有正数值约束（如 height、width、frameRate、aspectRatio、sampleRate 和 sampleSize），适应度距离为公式计算的结果。

   (actual == ideal) ? 0 : |actual - ideal| / max(|actual|, |ideal|)

8. 对于所有字符串、枚举和布尔值约束（如 deviceId、groupId、facingMode、resizeMode、echoCancellation），适应度距离为公式计算的结果。

   (actual == ideal) ? 0 : 1

更多定义

• 我们将 ConstraintSet 的每个元素（除特殊术语 'advanced' 外）称为“约束”，因为它旨在将给定属性的可接受设置，从 ConstrainablePattern 对象相应能力中给出的完整列表或范围，限制为在该属性范围内或指定值列表内。
• 我们将对象 O 的“有效能力” C 定义为 C 可能的真子集（由 getCapabilities 返回），同时考虑到环境限制和/或其他约束施加的限制。例如，给定一个约束 aspectRatio、height 和 width 属性的 ConstraintSet，分配给其中任何两个属性的值会限制第三个属性的有效能力。有效能力的集合可能与平台有关。例如，在资源受限的设备上，可能无法将属性 P1 和 P2 同时设置为 'high'，而在另一个较少限制的设备上，这可能是可能的。
• 若对象 O 的设置字典（即一组针对对象 O 可约束属性的值）与约束集 CS 之间的 适应度距离 小于无穷大，则称其满足约束集 CS。
• 若存在对象 O 的一个设置字典可同时满足 CS1...CSn，则称对象 O 可满足一组约束集 CS1...CSn (n >= 1)。
• 将一组约束集 CS1...CSn 应用于对象 O，即选择满足 CS1...CSn 的值序列并将其分配为对象 O 属性的设置。

我们定义 SelectSettings 算法如下：

1. 每个 约束 为其属性指定一个或多个值（或值范围）。属性 可以 在 'advanced' 约束集列表中出现多次。如果约束的值给出一个空列表，则 必须 将其解释为未指定约束（换句话说，空约束 == 无约束）。

   注意，未知属性会被 WebIDL 丢弃，这意味着未知/不受支持的必要约束将静默消失。为避免这种情况带来的意外，应用程序开发者应首先如以下示例所示，使用 getSupportedConstraints() 方法。

2. 令 object 为应用此算法的 ConstrainablePattern 对象。令 copy 为 object 的无约束副本（即，copy 的行为应如同移除了所有 ConstraintSet 的 object）。

3. 针对 copy 的每个可能的 设置字典，计算其 适应度距离，将属性的裸值视为理想值。令 candidates 为适应度距离有限的 设置字典 集合。

4. 如果 candidates 为空，则返回 undefined 作为 SelectSettings 算法的结果。

5. 按照指定顺序迭代 newConstraints 中的 'advanced' 约束集。对于每个约束集：

   1. 计算它与 candidates 中每个设置字典之间的 适应度距离，将属性的裸值视为精确值（exact）。

   2. 如果一个或多个 candidates 中的设置字典的适应度距离有限，则保留这些设置字典，丢弃其他。

      如果所有 candidates 中的设置字典的适应度距离均为无限大，则忽略此约束集。

6. 从 candidates 中选择一个设置字典，并将其作为 SelectSettings 算法的结果返回。用户代理 必须 使用在步骤 3 中计算出的具有最小 适应度距离 的设置字典。如果多个设置字典具有相同的最小适应度距离，用户代理 将根据系统默认属性值和 用户代理 默认属性值选择其中一个。

对于所选设备具有系统默认值的任何属性，如果与上述算法兼容，则 应当 使用系统默认值。这通常适用于诸如 sampleRate 或 sampleSize 等属性。其他属性，如 echoCancellation 或 resizeMode 通常没有系统默认值。用户代理 为这些属性定义自己的默认值。实现者需要谨慎选择良好的默认值，因为它们通常会影响媒体内容的生成方式。

注

建议参考现有实现来选择有意义的默认值。请注意，默认值可能会因系统而异，例如桌面端与移动端。在撰写本文时，用户代理 实现倾向于使用以下默认值，这些值因其适合将 RTCPeerConnection 作为汇聚点而被选中：

1. width 设置为 640。

2. height 设置为 480。

3. frameRate 设置为 30。

4. echoCancellation 设置为 true。

要将 ApplyConstraints 算法 应用于给定的 object（参数为 newConstraints），用户代理 必须 执行以下步骤：

1. 令 successfulSettings 为以 newConstraints 为约束集运行 SelectSettings 算法的结果。

2. 如果 successfulSettings 为 undefined，令 failedConstraint 为所有在执行 SelectSettings 算法期间检查的设置字典中适应度距离均为无穷大的任意 必要约束，若无则设为 ""，然后返回 failedConstraint 并终止这些步骤。

3. 在单一操作中，移除 object 的现有约束，应用 newConstraints，并将 successfulSettings 应用为当前设置。
4. 返回 undefined。

注

如果 UA 放弃了设备，例如如果轨道处于 静音 状态，应用设置并不意味着更改设备配置。相反，UA 将在重新获取设备时将设备配置为匹配轨道设置，例如在轨道被 取消静音 时。

注

任何结果与上述算法相同的实现都是被允许的。例如，实现可以选择跟踪在所考虑约束下可行的设置的最大值和最小值，而不是跟踪设置的所有可能值。

注

在选择设置字典时，UA 可以使用其可用的任何信息。此类信息的示例包括选择是否作为 getUserMedia 中设备选择的一部分完成、摄像头的能量使用在不同的设置字典之间是否有变化，或者使用该设置字典是否会导致设备驱动程序应用重采样。

用户代理 可以 在任何时候为对象的可约束属性选择新设置。当这样做时，它 必须 以上述算法中描述的方式尝试满足所有当前约束，令 successfulSettings 为生成的最终新设置，并排队执行一个运行以下步骤的任务：

1. 令 object 为一个或多个可约束属性的新设置已更改的 ConstrainablePattern 对象。

2. 将 object 的 [[Settings]] 内部槽位设置为 successfulSettings。

max，类型为 double

此属性的最大有效值。

min，类型为 double

此属性的最小值。

exact，类型为 double

此属性所需的精确值。

ideal，类型为 double

此属性的理想（目标）值。

max，类型为 unsigned long

此属性的最大有效值。

min，类型为 unsigned long

此属性的最小值。

exact，类型为 unsigned long

此属性所需的精确值。

ideal，类型为 unsigned long

此属性的理想（目标）值。

exact，类型为 boolean

此属性所需的精确值。

ideal，类型为 boolean

此属性的理想（目标）值。

exact，类型为 (DOMString or sequence<DOMString>)

此属性所需的精确值。

ideal，类型为 (DOMString or sequence<DOMString>)

此属性的理想（目标）值。

exact，类型为 (boolean or DOMString)

此属性所需的精确值。

ideal，类型为 (boolean or DOMString)

此属性的理想（目标）值。