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

音频输出设备 API

· 52CE 我爱测

音频输出设备 API**(Audio Output Devices API)允许 Web 应用程序提示用户选择用于音频播放的输出设备。

Audio Output Devices API

音频输出设备 API(Audio Output Devices API)允许 Web 应用程序提示用户选择用于音频播放的输出设备。

概念和用法

操作系统通常允许用户指定音频应从扬声器、蓝牙耳机或其他音频输出设备播放。该 API 允许应用程序从 Web 页面内提供与此相同的功能。

即使在权限策略允许的情况下,访问特定音频输出设备仍然需要明确的用户权限,因为用户可能处于不适合通过某些输出设备播放音频的位置。

该 API 提供了 MediaDevices.selectAudioOutput() 方法,允许用户从文档的 Permissions-Policy HTTP 标头的 speaker-selection 指令允许的音频输出设备中选择所需的音频输出。然后选择的设备会获得用户权限,允许使用 MediaDevices.enumerateDevices() 枚举该设备,并使用 HTMLMediaElement.setSinkId() 将其设置为音频输出设备。

音频设备可能会任意连接和断开。希望对此类更改做出反应的应用程序可以侦听 MediaDevices/devicechange_event 事件,并使用 MediaDevices.enumerateDevices 来确定返回的设备中是否存在 sinkId。这可能会触发例如暂停或恢复播放等操作。

接口

对接口的拓展

音频输出设备 API 扩展了以下 API,添加了列出的特性:

MediaDevices

  • MediaDevices.selectAudioOutput()
    • : 此方法提示用户选择特定的音频输出设备,例如扬声器或耳机。选择设备授予用户使用该设备的权限,并返回有关设备的信息,包括其 ID。

HTMLMediaElement

  • HTMLMediaElement.setSinkId()
    • : 此方法设置要用于输出的音频设备的 ID,如果允许,则将使用该设备。
  • HTMLMediaElement.sinkId
    • : 此属性返回正在用于输出的音频设备的唯一 ID,如果正在使用默认的用户代理设备,则返回空字符串。

安全要求

对 API 的访问受以下约束:

  • 所有方法和属性只能在安全上下文中调用。

  • MediaDevices.selectAudioOutput() 授予对所选设备用作音频输出的用户权限:

  • HTMLMediaElement.setSinkId() 将允许的 ID 设置为音频输出:

    • 访问可能受 speaker-selection HTTP 权限策略的限制。
    • 需要用户权限来设置非默认设备 ID。
      • 这可以通过在由 MediaDevices.selectAudioOutput() 启动的提示中选择来获得。
      • 如果已经使用 MediaDevices.getUserMedia() 获得了使用相同组中媒体输入设备的权限,则用户还会隐式授予对应输出设备的权限。

示例

以下是使用 selectAudioOutput() 的示例,该方法位于通过按钮点击触发的函数内,并将所选设备设置为音频输出。

代码首先检查是否支持 selectAudioOutput(),如果支持,则使用它选择输出并返回设备 ID。然后我们使用默认输出播放一些音频,然后调用 setSinkId() 以切换到所选输出设备。

document.querySelector("#myButton").addEventListener("click", async () => {
  if (!navigator.mediaDevices.selectAudioOutput) {
    console.log("不支持 selectAudioOutput(),或不在安全上下文中。");
    return;
  }

  // 显示选择设备的提示
  const audioDevice = await navigator.mediaDevices.selectAudioOutput();

  // 创建音频元素并在默认设备上开始播放音频
  const audio = document.createElement("audio");
  audio.src = "https://example.com/audio.mp3";
  audio.play();

  // 将输出更改为所选的音频输出设备。
  audio.setSinkId(audioDevice.deviceId);
});

请注意,如果记录输出详细信息,它们可能如下所示:

console.log(
  `${audioDevice.kind}: ${audioDevice.label} id = ${audioDevice.deviceId}`,
);
// audiooutput: Realtek Digital Output (Realtek(R) Audio) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=

规范

浏览器兼容性

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

资料来源与适用范围

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

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

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