MediaDevices: selectAudioOutput() 方法

語法

selectAudioOutput()
selectAudioOutput(options)

引數

options 可選

一個配置可以在使用者提示中提供哪些裝置的物件。

deviceId 可選

一個代表先前已暴露/已授權的單個裝置的 ID 的字串。如果未設定，將顯示一個包含所有可用音訊輸出裝置的提示。

此選項旨在供應用程式儲存裝置 ID，以便在將來的會話中預設使用相同的裝置。請注意，該方法可能會為同一裝置返回新的 ID，並且持久化的 ID 必須透過 selectAudioOutput() 成功傳遞後才能與 setSinkId() 一起使用。

注意： 如果使用者代理在之前的會話中已透過 selectAudioOutput() 向用戶暴露了指定的非空 ID，使用者代理可以選擇跳過提示使用者。在這種情況下，使用者代理可能會直接以該裝置 ID 解析，或者如果裝置 ID 已更改，則以該裝置的新 ID 解析。如果先前已授予指定裝置的許可權但後來已被撤銷，使用者代理可能會顯示所有允許的裝置，並突出顯示具有指定 ID 的裝置。

返回值

一個 Promise，它會以一個描述使用者所選音訊輸出裝置的 MediaDeviceInfo 物件fulfilled。

異常

NotAllowedError DOMException

如果使用了 speaker-selection 許可權策略來阻止使用音訊輸出（此外，用於選擇音訊輸出的彈出視窗也不會顯示），或者使用者在未選擇裝置的情況下關閉了選擇提示，則返回此值。

NotFoundError DOMException

如果沒有可用的音訊輸出裝置，則返回此值。

InvalidStateError DOMException

如果沒有 瞬時啟用（必須從某種 UI 事件觸發），則返回此值。

安全要求

API 的訪問受以下約束：

• 必須在 安全上下文 中呼叫該方法。
• 需要 瞬時使用者啟用。使用者必須與頁面或 UI 元素進行互動，此功能才能正常工作。
• 訪問可能受 speaker-selection HTTP 許可權策略的限制。

可以使用 Permissions API 方法 navigator.permissions.query() 查詢許可權狀態，傳遞一個包含 speaker-selection 許可權的許可權描述符。

示例

以下是一個使用 selectAudioOutput() 的示例，該函式在按鈕點選時觸發。它會輸出所選裝置的 裝置 ID 和標籤（如果可用），或者錯誤訊息。

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

選擇輸出後，可能會產生以下結果：

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

規範

瀏覽器相容性

另見

• HTMLMediaElement.setSinkId()
• HTMLMediaElement.sinkId
• WebRTC - 該 API 的介紹頁面