Como gerenciar alterações na saída de áudio

Os usuários esperam poder controlar o volume de um app de áudio. O comportamento padrão inclui a capacidade de usar os controles de volume, como botões do dispositivo ou controles deslizantes na interface, e evitar a reprodução em voz alta se um periférico, como fones de ouvido, for desconectado durante o uso.

Como usar os controles de volume

Quando um usuário pressiona uma tecla de volume em um app de jogo ou música, o volume precisa mudar, mesmo que o player esteja pausado entre as músicas ou não haja música no local atual do jogo.

O Android usa streams de áudio separados para tocar músicas, alarmes, notificações, campainha de chamada recebida, sons do sistema, volume de chamadas e tons DTMF. Isso permite que os usuários controlem o volume de cada stream de forma independente.

Por padrão, pressionar o controle de volume modifica o volume do stream de áudio ativo. Se o app não estiver reproduzindo nada, pressionar as teclas de volume ajustará o volume da música (ou o volume da campainha em versões anteriores ao Android 9).

A menos que seu app seja um despertador, você deve tocar áudio com o uso AudioAttributes.USAGE_MEDIA.

Para garantir que os controles de volume ajustem o stream correto, chame setVolumeControlStream() transmitindo o tipo de stream correspondente aos atributos que você pode recuperar em AudioAttributes.getVolumeControlStream.

Kotlin

setVolumeControlStream(AudioManager.STREAM_MUSIC)

Java

setVolumeControlStream(AudioManager.STREAM_MUSIC);

Faça essa chamada no ciclo de vida do app, normalmente pelo método onResume() da atividade ou do fragmento que controla a mídia. Isso conectará os controles de volume ao STREAM_MUSIC sempre que a atividade ou o fragmento de destino estiver visível.

Como controlar o volume de stream de maneira programática

Em casos raros, você pode definir o volume de um stream de áudio programaticamente. Por exemplo, quando o app substitui uma interface existente. Isso não é recomendado porque o AudioManager do Android mistura todos os streams de áudio do mesmo tipo. Esses métodos mudam o volume de cada app que usa o stream. Evite usá-los:

Como trabalhar com dispositivos de volume fixo

Alguns dispositivos, como os Chromebooks, têm controles de volume, mas não permitem que os apps usem os métodos AudioManager descritos acima para mudar o nível de um stream de áudio. Eles são chamados de dispositivos com volume fixo. Você pode descobrir se o app está sendo executado em um dispositivo de volume fixo chamando isVolumeFixed().

Um app de áudio precisa oferecer a capacidade de equilibrar o volume de saída com outros apps que podem estar sendo reproduzidos no mesmo stream. Em dispositivos com volume fixo, o app precisa conectar os próprios controles de volume ao método setVolume() apropriado na tabela abaixo:

Jogador Método
Faixa de áudio AudioTrack.setVolume()
MediaPlayer MediaPlayer.setVolume()
ExoPlayer Use SimpleExoPlayer.setVolume(), que define o volume da faixa de áudio subjacente.

Não seja barulhento

Os usuários têm várias alternativas quando se trata de aproveitar o áudio dos dispositivos Android. A maioria dos dispositivos tem um alto-falante integrado, entradas para fones de ouvido com fio e muitos também têm conectividade Bluetooth e suporte para áudio A2DP.

Quando um fone de ouvido é desconectado ou um dispositivo Bluetooth é desconectado, o stream de áudio é redirecionado automaticamente para o alto-falante integrado. Se você ouve música em volume alto, isso pode ser uma surpresa barulhenta.

Os usuários geralmente esperam que os apps que incluem um player de música com controles de reprodução na tela pausem a reprodução nesse caso. Outros apps, como jogos que não incluem controles, continuarão sendo jogados. O usuário pode ajustar o volume com os controles de hardware do dispositivo.

Quando a saída de áudio volta para o alto-falante integrado, o sistema transmite uma intent ACTION_AUDIO_BECOMING_NOISY. Crie um BroadcastReceiver que escute essa intent sempre que estiver reproduzindo áudio. Seu receptor terá esta aparência:

Kotlin

private class BecomingNoisyReceiver : BroadcastReceiver() {

    override fun onReceive(context: Context, intent: Intent) {
        if (intent.action == AudioManager.ACTION_AUDIO_BECOMING_NOISY) {
            // Pause the playback
        }
    }
}

Java

private class BecomingNoisyReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
      if (AudioManager.ACTION_AUDIO_BECOMING_NOISY.equals(intent.getAction())) {
          // Pause the playback
      }
    }
}

Registre o receptor quando começar a reprodução e cancele o registro quando parar. Se você criar seu app conforme descrito neste guia, essas chamadas vão aparecer nos callbacks de sessão de mídia onPlay() e onStop().

Kotlin

private val intentFilter = IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY)
private val myNoisyAudioStreamReceiver = BecomingNoisyReceiver()

private val callback = object : MediaSessionCompat.Callback() {

    override fun onPlay() {
        registerReceiver(myNoisyAudioStreamReceiver, intentFilter)
    }

    override fun onStop() {
        unregisterReceiver(myNoisyAudioStreamReceiver)
    }
}

Java

private IntentFilter intentFilter = new IntentFilter(AudioManager.ACTION_AUDIO_BECOMING_NOISY);
private BecomingNoisyReceiver myNoisyAudioStreamReceiver = new BecomingNoisyReceiver();

MediaSessionCompat.Callback callback = new
MediaSessionCompat.Callback() {
  @Override
  public void onPlay() {
    registerReceiver(myNoisyAudioStreamReceiver, intentFilter);
  }

  @Override
  public void onStop() {
    unregisterReceiver(myNoisyAudioStreamReceiver);
  }
}