音訊輸出裝置 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