API de Dispositivos de Saída de Áudio
=====================================

**Secure context:** This feature is available only in secure contexts (en-US) (HTTPS), in some or all supporting browsers.

**Experimental:** **Esta é uma tecnologia experimental (en-US)**  
Verifique a tabela de compatibilidade entre Navegadores cuidadosamente antes de usar essa funcionalidade em produção.

A **API 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étodo `MediaDevices.selectAudioOutput()` (en-US) que permite aos usuários selecionar sua saída de áudio desejada dentre aquelas permitidas pela diretiva `speaker-selection` (en-US) do cabeçalho HTTP `Permissions-Policy` do documento.
 O dispositivo selecionado recebe, então, permissão do usuário, permitindo que ele seja enumerado com `MediaDevices.enumerateDevices()` (en-US) e definido como dispositivo de saída de áudio usando `HTMLMediaElement.setSinkId()` (en-US).

 Dispositivos de áudio podem se conectar e desconectar arbitrariamente. Aplicações que desejam reagir a esse tipo de mudança podem ouvir o evento `devicechange` event (en-US) e usar `enumerateDevices()` (en-US) para determinar se `sinkId` 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()` (en-US)

 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()` (en-US)

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

`HTMLMediaElement.sinkId` (en-US)

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 um contexto seguro (en-US).
* `MediaDevices.selectAudioOutput()` (en-US) 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 HTTP `speaker-selection` (en-US).
    + Ativação de usuário transitória (en-US) é 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()` (en-US) define um ID permitido como saída de áudio:
    + O acesso pode ser controlado pela política de permissões HTTP `speaker-selection` (en-US).
    + É 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 por `MediaDevices.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 com `MediaDevices.getUserMedia()` (en-US).

O status da permissão pode ser consultado usando o método Permissions API (en-US) `navigator.permissions.query()` (en-US), passando um descritor de permissão com a permissão `speaker-selection`.

Exemplos
--------

Aqui está um exemplo de uso de `selectAudioOutput()`, 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 se `selectAudioOutput()` é suportado e, se for o caso, o utiliza para selecionar uma saída e retornar um ID do dispositivo (en-US).
 Em seguida, reproduzimos algum áudio usando a saída padrão e, em seguida, chamamos `setSinkId()` para alternar para o dispositivo de saída selecionado.


```js
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:


```js
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
--------------

| Specification |
| --- |
| Audio Output Devices API  |

Compatibilidade com navegadores
-------------------------------

### api.MediaDevices.selectAudioOutput

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.HTMLMediaElement.setSinkId

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### api.HTMLMediaElement.sinkId

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### http.headers.Permissions-Policy.speaker-selection

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.