MediaDevices: selectAudioOutput() 方法

安全上下文： 此功能仅在 安全上下文（HTTPS）中可用，在部分或所有 支持的浏览器中可用。

实验性： 这是一个 实验性技术
在生产环境中使用之前，请仔细查看 浏览器兼容性表。

selectAudioOutput() 方法是 MediaDevices 接口的方法，用于提示用户选择一个音频输出设备，例如扬声器或耳机。如果用户选择了设备，该方法将授予用户权限，使用所选设备作为音频输出接收器。

选择后，如果设备可用，可以使用 MediaDevices.enumerateDevices() 枚举它，并使用 HTMLMediaElement.setSinkId() 将其设置为音频输出接收器。

成功后，返回的 Promise 将使用 MediaDeviceInfo 对象解析，该对象描述了用户选择的设备。

语法

js
selectAudioOutput()
selectAudioOutput(options)

参数

options 可选

一个对象，用于配置用户提示中可能提供的设备。

deviceId 可选

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

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

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

返回值

一个 Promise，它将使用 MediaDeviceInfo 对象解析，该对象描述了用户选择的音频输出设备。

异常

NotAllowedError DOMException

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

NotFoundError DOMException

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

InvalidStateError DOMException

如果尚未发生 瞬态激活（您必须从某种 UI 事件中触发它），则会返回该错误。

安全要求

对 API 的访问受到以下限制

可以使用 权限 API 方法 navigator.permissions.query() 查询权限状态，将包含 speaker-selection 权限的权限描述符传递给该方法。

示例

以下示例演示了如何在由按钮单击触发的函数内使用 selectAudioOutput()。它输出选择的 设备 ID 和标签（如果可用）或错误消息。

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

选择输出后，这可能会产生

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

规范

规范
音频输出设备 API
# dom-mediadevices-selectaudiooutput

浏览器兼容性

BCD 表仅在启用 JavaScript 的浏览器中加载。

另请参阅