大网数据广告活动
Web 标准与前端开发

MediaDevices:selectAudioOutput() 方法

· 52CE 我爱测

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

Audio Output Devices API

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

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

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

语法

selectAudioOutput()
selectAudioOutput(options)

参数

  • options
    • : 对象,用于配置可以在用户提示中提供的设备。
      • deviceId
        • : 表示单个先前公开或允许设备的 ID 的字符串。如果未设置,则会显示包含所有可用音频输出设备的提示。

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

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

返回值

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

异常

  • NotAllowedError DOMException
    • : 如果使用 speaker-selection 权限策略来阻止使用音频输出(此外不会显示用于选择音频输出的弹出窗口),或者用户关闭选择提示而没有选择设备时,则会返回此错误。
  • NotFoundError DOMException
    • : 如果没有可用的音频输出设备,则会返回此错误。
  • InvalidStateError DOMException
    • : 如果没有发生transient activation(你必须从某种 UI 事件中触发它),则会返回此错误。

安全要求

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

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

示例

以下是使用 selectAudioOutput() 的示例,它在按钮点击时触发。它会输出所选的MediaDeviceInfo.deviceId 和标签(如果可用),或者错误消息。

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 的介绍页面

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。