音频输出设备 API

sinkId，类型为 DOMString，只读

此属性包含正在通过其传送输出的音频设备的 ID；如果输出是 通过用户代理默认设备传送的，则为空字符串。如果非空，则此 ID 应等于 deviceId 属性，该属性属于 enumerateDevices() 返回的某个 MediaDeviceInfo 值。

获取时，该 属性 MUST 返回 [[SinkId]] 槽的值。

setSinkId

如果应用程序被允许从给定 设备播放输出，则设置音频输出应通过其呈现的音频设备的 ID。

当调用此方法时，用户代理必须运行以下 步骤：

1. 令 globalObject 为 当前设置对象的 相关全局对象。

2. 令 document 为 globalObject 的 关联 Document。

3. 如果 document 不 被允许使用由 "speaker-selection" 标识的特性，则返回一个 使用新的 DOMException 拒绝的 promise， 其名称为 NotAllowedError。

4. 如果 globalObject 没有瞬态 激活， 则用户代理 MAY 返回一个以 DOMException 对象拒绝的 promise， 该对象的 name 属性具有 InvalidStateError 值。

5. 令 element 为调用此方法的 HTMLMediaElement 对象。

6. 令 sinkId 为该方法的第一个参数。

7. 如果 sinkId 等于 element 的 [[SinkId]]， 则返回一个以 undefined 解决的 promise。

8. 令 p 为一个新的 promise。

9. 并行运行以下子步骤：

   1. 如果 sinkId 不是空字符串，并且不匹配 enumerateDevices() 结果会提供的任何音频输出设备， 则用新的 DOMException 拒绝 p， 其名称为 NotFoundError， 并中止这些子步骤。

   2. 如果 sinkId 不是空字符串，并且 若它不是当前用户代理默认设备，则应用程序不会被允许 通过 sinkId 标识的设备播放音频输出， 则用新的 DOMException 拒绝 p， 其名称为 NotAllowedError， 并中止这些子步骤。

   3. 将 element 的底层音频输出设备切换 到由 sinkId 标识的音频设备。

      注

      如果此子步骤成功，并且媒体 元素的 paused 属性为 false，则音频 MUST 停止从该元素的 sinkId 属性所表示的设备播放输出，并将开始 从 sinkId 标识的设备播放输出

   4. 如果前一子步骤失败，则用新的 DOMException 拒绝 p， 其名称为 AbortError， 并中止这些子步骤。

   5. 排入一个任务，该任务运行以下步骤：

      1. 将 element 的 [[SinkId]] 设为 sinkId。

      2. 解决 p。

10. 返回 p。

selectAudioOutput

提示用户选择特定的音频输出设备。

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

1. 如果 相关 全局对象（属于 this）没有 瞬态 激活，则返回一个以 DOMException 对象拒绝的 promise， 该对象的 name 属性 具有 InvalidStateError 值。

2. 令 options 为该方法的第一个参数。

3. 令 deviceId 为 options.deviceId。

4. 令 mediaDevices 为 this。

5. 令 p 为一个新的 promise。

6. 并行运行以下步骤：

   1. 令 descriptor 为一个 PermissionDescriptor， 其 name 设为 "speaker-selection"

   2. 如果 descriptor 的 权限 状态为 "denied"， 则用新的 DOMException 拒绝 p， 其 name 属性具有 NotAllowedError 值， 并中止这些步骤。

   3. 探测 用户代理中 可用的音频输出设备。

   4. 如果没有音频输出设备，则用新的 DOMException 拒绝 p， 其 name 属性具有 NotFoundError 值，并中止 这些步骤。

   5. 如果 deviceId 不是 ""， 则运行以下子步骤：

      1. 如果 deviceId 匹配 先前由 selectAudioOutput 在此浏览会话或更早浏览会话中暴露的设备 ID， 或匹配某个音频输出设备的设备 ID，且该设备与先前由 getUserMedia() 在此浏览会话或更早浏览会话中暴露的音频输入设备 具有相同的 groupId， 则用户代理 MAY 根据其先前 是否为此组来源持久保存此 ID 的决定， 决定运行以下子步骤：

         1. 令 device 为由 deviceId 标识的设备（如果可用）。

         2. 如果 device 可用，则用 deviceId 或该 device 的新轮换设备 ID 解决 p，并中止并行步骤。

   6. 使用 descriptor 提示 用户选择一个音频输出设备。

   7. 如果请求结果为 "denied"， 则用新的 DOMException 拒绝 p， 其 name 属性 具有 NotAllowedError 值，并中止这些步骤。

   8. 令 selectedDevice 为用户选择的音频输出设备。

   9. 令 deviceInfo 为 创建 设备信息对象的结果，该对象用 mediaDevices 表示 selectedDevice。

   10. 将 deviceInfo.deviceId 添加到 [[explicitlyGrantedAudioOutputDevices]]。

   11. 用 deviceInfo 解决 p。

7. 返回 p。

一旦设备在调用 selectAudioOutput 后被暴露，它 MUST 被 enumerateDevices() 为当前浏览上下文列出。

如果 selectAudioOutput 返回的 promise 被解决， 则用户代理 MUST 确保文档无需任何额外用户手势， 即刻既被允许播放 HTMLMediaElement 中的媒体， 又即刻被 允许启动 AudioContext。

注

由于当前浏览器中自动播放缺乏标准化， 这并不精确。

此字典描述可用于获取音频输出设备 访问权限的选项。

WebIDLdictionary AudioOutputOptions {
  DOMString deviceId = "";
};