MediaDevices: метод selectAudioOutput()

Метод selectAudioOutput() интерфейса MediaDevices предлагает пользователю выбрать устройство вывода звука, такое как динамики или наушники. Если пользователь выбирает устройство, метод предоставляет разрешение на использование выбранного устройства в качестве источника вывода звука.

После выбора, если устройство доступно, его можно перечислить с помощью MediaDevices.enumerateDevices() и установить в качестве источника вывода звука с помощью HTMLMediaElement.setSinkId().

В случае успеха возвращаемое Promise разрешается с помощью MediaDeviceInfo, описывающего выбранное устройство.

options Необязательно

Объект, который настраивает, какие устройства могут быть предложены в запросе к пользователю.

deviceId Необязательно

Строка, представляющая идентификатор одного ранее экспонированного/разрешённого устройства. Если не задано, отобразится запрос со всеми доступными устройствами вывода звука.

Этот параметр предназначен для приложений, которые хотят сохранить идентификатор устройства, чтобы это же устройство можно было использовать по умолчанию в будущих сессиях. Обратите внимание, что метод может вернуть новый идентификатор для того же устройства, и что сохранённые идентификаторы должны быть переданы через selectAudioOutput() успешно, прежде чем они будут работать с setSinkId().

Примечание: Пользовательский агент может выбрать пропустить запрос к пользователю, если указанный ненулевой идентификатор был ранее показан пользователю посредством selectAudioOutput() в предыдущей сессии. В этом случае пользовательский агент может просто разрешить с этим идентификатором устройства или новым идентификатором для того же устройства, если оно изменилось. Если разрешение на указанное устройство ранее было предоставлено, но затем было отозвано, пользовательский агент может отобразить все разрешенные устройства, выделив устройство с указанным идентификатором.

A Promise, который выполняется с объектом MediaDeviceInfo, описывающим устройство вывода звука, выбранное пользователем.

NotAllowedError DOMException

Возвращается, если используется speaker-selection Политика разрешений для блокировки использования устройств вывода звука (кроме того, всплывающее окно для выбора устройства вывода звука не будет отображаться), или пользователь закрыл запрос выбора, не выбрав устройство.

NotFoundError DOMException

Возвращается, если нет доступных устройств вывода звука.

InvalidStateError DOMException

Возвращается, если не произошло временного активации (необходимо вызвать её из какого-либо события пользовательского интерфейса).

Доступ к API ограничен следующими условиями:

• Метод должен вызываться в безопасном контексте.
• Требуется временная активация пользователя. Пользователь должен взаимодействовать со страницей или элементом пользовательского интерфейса, чтобы эта функция работала.
• Доступ может быть ограничен speaker-selection HTTP политикой разрешений.

Статус разрешения можно запросить с помощью метода API разрешений navigator.permissions.query(), передав описатель разрешения с разрешением speaker-selection.

Вот пример использования selectAudioOutput(), внутри функции, которая запускается при нажатии кнопки. Он выводит выбранные идентификаторы устройств и метки (если доступны) или сообщение об ошибке.

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