AAPI de Dispositivos de Saída de Áudio permite que aplicações web solicitem aos usuários qual dispositivo de saída deve ser usado para a reprodução de áudio.

Conceitos e uso

Sistemas operacionais comumente permitem que os usuários especifiquem se o áudio deve ser reproduzido nos alto-falantes, em um fone de ouvido Bluetooth ou em algum outro dispositivo de saída de áudio.Esta API permite que as aplicações ofereçam essa mesma funcionalidade a partir de uma página web.

Mesmo se permitido por uma política de permissões, o acesso a um dispositivo de saída de áudio específico ainda requer permissão explícita do usuário, pois o usuário pode estar em um local onde a reprodução de áudio através de alguns dispositivos de saída não seja apropriada.

A API fornece o métodoMediaDevices.selectAudioOutput() que permite aos usuários selecionar sua saída de áudio desejada dentre aquelas permitidas pela diretivaspeaker-selection do cabeçalho HTTPPermissions-Policy do documento.O dispositivo selecionado recebe, então, permissão do usuário, permitindo que ele seja enumerado comMediaDevices.enumerateDevices() e definido como dispositivo de saída de áudio usandoHTMLMediaElement.setSinkId().

Dispositivos de áudio podem se conectar e desconectar arbitrariamente. Aplicações que desejam reagir a esse tipo de mudança podem ouvir o eventodevicechange event e usarenumerateDevices() para determinar sesinkId está presente nos dispositivos retornados.Isso pode iniciar, por exemplo, a pausa ou retomada da reprodução.

Interfaces

Extensões para interfaces

A API de Dispositivos de Saída de Áudio estende as seguintes APIs, adicionando as funcionalidades listadas:

MediaDevices

MediaDevices.selectAudioOutput()

Este método solicita ao usuário a seleção de um dispositivo de saída de áudio específico, como um alto-falante ou fone de ouvido.Selecionar um dispositivo concede permissão do usuário para usá-lo e retorna informações sobre o dispositivo, incluindo seu ID.

HTMLMediaElement

HTMLMediaElement.setSinkId()

Este método define o ID do dispositivo de áudio a ser usado para saída, que será usado se permitido.

HTMLMediaElement.sinkId

Esta propriedade retorna o ID único do dispositivo de áudio em uso, ou uma string vazia se o dispositivo padrão do agente do usuário estiver sendo usado.

Requisitos de segurança

O acesso à API está sujeito às seguintes restrições:

• Todos os métodos e propriedades só podem ser chamados em umcontexto seguro.

• MediaDevices.selectAudioOutput() concede permissão do usuário para um dispositivo selecionado ser usado como o dispositivo de saída de áudio:

  • O acesso pode ser controlado pela política de permissões HTTPspeaker-selection.
  • Ativação de usuário transitória é necessária.O usuário deve interagir com a página ou um elemento de interface do usuário para que o método seja chamado.

• HTMLMediaElement.setSinkId() define um ID permitido como saída de áudio:

  • O acesso pode ser controlado pela política de permissões HTTPspeaker-selection.
  • É necessária a permissão do usuário para definir um ID de dispositivo não padrão.
    • Isso pode vir da seleção na janela de diálogo lançada porMediaDevices.selectAudioOutput()
    • A permissão do usuário para definir o dispositivo de saída é concedida implicitamente se o usuário já concedeu permissão para usar um dispositivo de entrada de mídia no mesmo grupo comMediaDevices.getUserMedia().

O status da permissão pode ser consultado usando o métodoPermissions APInavigator.permissions.query(), passando um descritor de permissão com a permissãospeaker-selection.

Exemplos

Aqui está um exemplo de uso deselectAudioOutput(), dentro de uma função que é acionada por um clique em um botão, e em seguida definindo o dispositivo selecionado como saída de áudio.

O código primeiro verifica seselectAudioOutput() é suportado e, se for o caso, o utiliza para selecionar uma saída e retornar umID do dispositivo.Em seguida, reproduzimos algum áudio usando a saída padrão e, em seguida, chamamossetSinkId() para alternar para o dispositivo de saída selecionado.

document.querySelector("#meuBotao").addEventListener("click", async () => {  if (!navigator.mediaDevices.selectAudioOutput) {    console.log(      "selectAudioOutput() não suportado ou não está em contexto seguro.",    );    return;  }  // Exibe janela de seleção do dispositivo  const dispositivoDeAudio = await navigator.mediaDevices.selectAudioOutput();  // Cria um elemento de áudio e inicia a reprodução de áudio no dispositivo padrão  const audio = document.createElement("audio");  audio.src = "https://example.com/audio.mp3";  audio.play();  // Altera a saída para o dispositivo de áudio selecionado.  audio.setSinkId(dispositivoDeAudio.deviceId);});

Observe que se você registrar os detalhes de saída, eles podem se parecer com isso:

console.log(  `${dispositivoDeAudio.kind}: ${dispositivoDeAudio.label} id = ${dispositivoDeAudio.deviceId}`,);// saída de áudio: Saída Digital Realtek (Áudio Realtek(R)) id = 0wE6fURSZ20H0N2NbxqgowQJLWbwo+5ablCVVJwRM3k=

Especificações

Compatibilidade com navegadores

api.MediaDevices.selectAudioOutput

api.HTMLMediaElement.setSinkId

api.HTMLMediaElement.sinkId

http.headers.Permissions-Policy.speaker-selection