API устройств вывода звука

API устройств вывода звука позволяет веб-приложениям запросить у пользователя, какое устройство вывода звука следует использовать для воспроизведения аудио.

Операционные системы обычно позволяют пользователям указывать, что звук должен воспроизводиться с динамиков, Bluetooth-гарнитуры или другого устройства вывода звука. Этот API позволяет приложениям предоставить ту же функциональность с веб-страницы.

Даже если политика разрешений это допускает, доступ к конкретному устройству вывода звука по-прежнему требует явного разрешения пользователя, так как пользователь может находиться в месте, где воспроизведение звука через некоторые устройства вывода нежелательно.

API предоставляет метод MediaDevices.selectAudioOutput(), который позволяет пользователям выбрать желаемое устройство вывода звука из тех, которые разрешены директивой speaker-selection заголовка HTTP Permissions-Policy для документа. Выбранное устройство затем имеет разрешение пользователя, позволяя перечислить его с помощью MediaDevices.enumerateDevices() и установить в качестве устройства вывода звука с помощью HTMLMediaElement.setSinkId().

Устройства аудио могут произвольно подключаться и отключаться. Приложения, которые хотят реагировать на такие изменения, могут слушать событие devicechange и использовать enumerateDevices(), чтобы определить, есть ли sinkId в возвращенных устройствах. Это может, например, вызвать приостановку или возобновление воспроизведения.

API устройств вывода звука расширяет следующие API, добавляя указанные функции:

MediaDevices

MediaDevices.selectAudioOutput()

Этот метод запрашивает у пользователя выбор конкретного устройства вывода звука, например, динамиков или гарнитуры. Выбор устройства предоставляет разрешение пользователя на использование этого устройства и возвращает информацию об устройстве, включая его идентификатор.

HTMLMediaElement

HTMLMediaElement.setSinkId()

Этот метод задаёт идентификатор устройства аудио для вывода, который будет использоваться, если разрешено.

HTMLMediaElement.sinkId

Это свойство возвращает уникальный идентификатор устройства аудио, используемого для вывода, или пустую строку, если используется устройство по умолчанию пользователя.

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

• Все методы и свойства могут быть вызваны только в безопасном контексте.

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

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

• HTMLMediaElement.setSinkId() устанавливает разрешённый идентификатор в качестве устройства вывода звука:

  • Доступ может быть ограничен заголовком HTTP speaker-selection Политики разрешений.
  • Требуется разрешение пользователя для установки нестандартного идентификатора устройства.
    • Это может произойти при выборе в запросе, запущенном MediaDevices.selectAudioOutput()
    • Разрешение пользователя на установку устройства вывода также подразумевается, если пользователь уже предоставил разрешение на использование устройства ввода медиа в той же группе с помощью MediaDevices.getUserMedia().

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

Код сначала проверяет, поддерживается ли selectAudioOutput(), и если поддерживается, использует его для выбора вывода и возвращает идентификатор устройства device 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=