MediaDevices：selectAudioOutput() 方法

安全上下文: 此项功能仅在一些支持的浏览器的安全上下文（HTTPS）中可用。

实验性: 这是一项实验性技术
在将其用于生产之前，请仔细检查浏览器兼容性表格。

MediaDevices 接口的 selectAudioOutput() 方法会提示用户选择一个音频输出设备，例如扬声器或耳机。如果用户选择了设备，该方法会授予用户权限，使选定的设备成为音频输出的目标。

选择设备后，如果该设备可用，可以使用 MediaDevices.enumerateDevices() 列出它，并使用 HTMLMediaElement.setSinkId() 将其设置为音频输出目标。

成功时，返回的 Promise 会兑现一个描述所选设备的 MediaDeviceInfo 对象。

语法

js
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 的访问受以下约束：

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

示例

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

js
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}`);
    });
});

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

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

规范

Specification
Audio Output Devices API
# dom-mediadevices-selectaudiooutput

浏览器兼容性

BCD tables only load in the browser

参见