MediaDevices：selectAudioOutput() 方法

语法

selectAudioOutput()
selectAudioOutput(options)

参数

options 可选

对象，用于配置可以在用户提示中提供的设备。

deviceId 可选

表示单个先前公开或允许设备的 ID 的字符串。如果未设置，则会显示包含所有可用音频输出设备的提示。

该选项适用于希望存储设备 ID 以便将来会话中默认使用同一设备的应用程序。注意，方法可能会返回同一设备的新 ID，并且持久化的 ID 必须在 setSinkId() 成功地通过 selectAudioOutput() 传递后才能使用。

备注：如果在先前会话中通过 selectAudioOutput() 向用户显示了指定的非空 ID，则用户代理可能会选择跳过提示用户的步骤。 在这种情况下，用户代理可能会简单地解析为此设备 ID，或者如果设备 ID 已更改，则解析为同一设备的新 ID。 如果先前授予了指定设备的权限，但此后被撤销，用户代理可能会显示所有允许的设备，并突出显示具有指定 ID 的设备。

返回值

Promise，其会兑现一个描述用户选择的音频输出设备的 MediaDeviceInfo 对象。

异常

NotAllowedError DOMException

如果使用 speaker-selection 权限策略来阻止使用音频输出（此外不会显示用于选择音频输出的弹出窗口），或者用户关闭选择提示而没有选择设备时，则会返回此错误。

NotFoundError DOMException

如果没有可用的音频输出设备，则会返回此错误。

InvalidStateError DOMException

如果没有发生瞬态激活（你必须从某种 UI 事件中触发它），则会返回此错误。

安全要求

对此 API 的访问受以下约束：

• 方法必须在安全上下文中调用。
• 需要瞬态用户激活。 用户必须与页面或 UI 元素进行交互，才能使用此特性。
• 访问可能受 speaker-selection HTTP 权限策略的控制。

权限状态可以通过 Permissions API 的 navigator.permissions.query() 方法进行查询（传递一个带有 speaker-selection 权限的权限描述符）。

示例

以下是使用 selectAudioOutput() 的示例，它在按钮点击时触发。它会输出所选的设备 ID 和标签（如果可用），或者错误消息。

document.querySelector("#myButton").addEventListener("click", () => {
  if (!navigator.mediaDevices.selectAudioOutput) {
    console.log("不支持 selectAudioOutput()。");
    return;
  }

  // 显示提示并记录所选设备或错误
  navigator.mediaDevices
    .selectAudioOutput()
    .then((device) => {
      console.log(`${device.kind}: ${device.label} id = ${device.deviceId}`);
    })
    .catch((err) => {
      console.error(`${err.name}: ${err.message}`);
    });
});

选择输出设备后，可能会产生如下输出：

audiooutput: Realtek Digital Output (Realtek(R) Audio) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=

规范

浏览器兼容性

参见

• HTMLMediaElement.setSinkId()
• HTMLMediaElement.sinkId
• WebRTC API 的介绍页面