MediaDevices: selectAudioOutput() 方法

语法

selectAudioOutput()
selectAudioOutput(options)

参数

options 可选

一个配置可以在用户提示中提供哪些设备的对象。

deviceId 可选

一个代表先前已暴露/已授权的单个设备的 ID 的字符串。如果未设置，将显示一个包含所有可用音频输出设备的提示。

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

注意： 如果用户代理在之前的会话中已通过 selectAudioOutput() 向用户暴露了指定的非空 ID，用户代理可以选择跳过提示用户。在这种情况下，用户代理可能会直接以该设备 ID 解析，或者如果设备 ID 已更改，则以该设备的新 ID 解析。如果先前已授予指定设备的权限但后来已被撤销，用户代理可能会显示所有允许的设备，并突出显示具有指定 ID 的设备。

返回值

一个 Promise，它会以一个描述用户所选音频输出设备的 MediaDeviceInfo 对象fulfilled。

异常

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() not supported.");
    return;
  }

  // Display prompt and log selected device or error
  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 的介绍页面