音频输出设备 API

概念与用法

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

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

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

音频设备可能会任意连接和断开。希望对这种类型更改做出响应的应用程序可以监听 devicechange 事件，并使用 enumerateDevices() 来确定返回的设备中是否存在 sinkId。这可能会触发，例如，暂停或恢复播放。

接口

其他接口的扩展

音频输出设备 API 扩展了以下 API，并添加了列出的功能

MediaDevices

MediaDevices.selectAudioOutput()

此方法提示用户选择一个特定的音频输出设备，例如扬声器或耳机。选择设备将授予用户使用该设备的许可，并返回有关设备的信息，包括其 ID。

HTMLMediaElement

HTMLMediaElement.setSinkId()

此方法设置要用于输出的音频设备的 ID，如果允许，将使用该 ID。

HTMLMediaElement.sinkId

此属性返回正在用于输出的音频设备的唯一 ID，如果正在使用默认用户代理设备，则返回空字符串。

安全要求

API 的访问受以下约束：

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

• MediaDevices.selectAudioOutput() 授予用户许可使用选定的设备作为音频输出接收器

  • 访问可能受 speaker-selection HTTP 权限策略的限制。
  • 需要 瞬时用户激活。必须由用户与页面或 UI 元素进行交互才能调用该方法。

• 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() not supported or not in secure context.");
    return;
  }

  // Display prompt to select device
  const audioDevice = await navigator.mediaDevices.selectAudioOutput();

  // Create an audio element and start playing audio on the default device
  const audio = document.createElement("audio");
  audio.src = "https://example.com/audio.mp3";
  audio.play();

  // Change the sink to the selected audio output device.
  audio.setSinkId(audioDevice.deviceId);
});

请注意，如果您记录输出详细信息，它们可能看起来像这样

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

规范

浏览器兼容性

api.MediaDevices.selectAudioOutput

api.HTMLMediaElement.setSinkId

api.HTMLMediaElement.sinkId

http.headers.Permissions-Policy.speaker-selection