AudioFocusRequestClass Classe

Definição

[Android.Runtime.Register("android/media/AudioFocusRequest", ApiSince=26, DoNotGenerateAcw=true)]
public sealed class AudioFocusRequestClass : Java.Lang.Object

[<Android.Runtime.Register("android/media/AudioFocusRequest", ApiSince=26, DoNotGenerateAcw=true)>]
type AudioFocusRequestClass = class
    inherit Object

Herança

Object

Object

AudioFocusRequestClass

Atributos

RegisterAttribute

Comentários

Uma classe para encapsular informações sobre uma solicitação de foco de áudio. Uma AudioFocusRequest instância é criada por Builder, e é usada para solicitar e abandonar o foco de áudio, respectivamente com AudioManager#requestAudioFocus(AudioFocusRequest) e AudioManager#abandonAudioFocusRequest(AudioFocusRequest).

<h3>O que é foco de áudio?</h3>

O foco de áudio é um conceito introduzido na API 8. Ele é usado para transmitir o fato de que um usuário só pode se concentrar em um único fluxo de áudio de cada vez, por exemplo, ouvir música ou um podcast, mas não ambos ao mesmo tempo. Em alguns casos, vários fluxos de áudio podem ser reproduzidos ao mesmo tempo, mas há apenas um que o usuário realmente ouviria (concentre-se), enquanto o outro é reproduzido em segundo plano. Um exemplo disso é dirigir direções sendo faladas enquanto a música toca em um volume reduzido (também conhecido como esquiva).

Quando um aplicativo solicita foco de áudio, ele expressa sua intenção de "possuir" o foco de áudio para reproduzir áudio. Vamos examinar os diferentes tipos de solicitações de foco, o valor retornado após uma solicitação e as respostas a uma perda.

Observação: os aplicativos não devem reproduzir nada até que o foco seja concedido.

<h3>Os diferentes tipos de solicitações< de foco/h3>

Há quatro tipos de solicitação de foco. Uma solicitação de foco bem-sucedida com cada uma produzirá comportamentos diferentes pelo sistema e pelo outro aplicativo que anteriormente mantinha o foco de áudio. <ul><li>AudioManager#AUDIOFOCUS_GAIN expressa o fato de que seu aplicativo agora é a única fonte de áudio que o usuário está ouvindo. A duração da reprodução de áudio é desconhecida e é possivelmente muito longa: depois que o usuário termina de interagir com seu aplicativo, ele não espera que outro fluxo de áudio seja retomado. Exemplos de usos desse ganho de foco são para reprodução de música, para um jogo ou um player de vídeo.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT é para uma situação em que você sabe que seu aplicativo está temporariamente capturando o foco do proprietário atual, mas o usuário espera que a reprodução volte para onde estava quando seu aplicativo não exigir mais foco de áudio. Um exemplo é para reproduzir um alarme ou durante uma chamada VoIP. A reprodução é conhecida por ser finita: o alarme vai acabar ou ser descartado, a chamada voIP tem um começo e um fim. Quando qualquer um desses eventos termina, e se o usuário estava ouvindo música quando começou, o usuário espera que a música seja retomada, mas não quis ouvir ambas ao mesmo tempo.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK: esse tipo de solicitação de foco é semelhante ao AUDIOFOCUS_GAIN_TRANSIENT aspecto temporário da solicitação de foco, mas também expressa o fato durante o tempo em que você tem foco, você permite que outro aplicativo continue jogando em um volume reduzido, "abaixado". Exemplos são que ao tocar direções ou notificações de condução, não há problema para a música continuar tocando, mas não alto o suficiente para impedir que as direções sejam difíceis de entender. Uma atenuação típica do aplicativo "ducked" é um fator de 0,2f (ou -14dB), que pode, por exemplo, ser aplicado MediaPlayer.setVolume(0.2f) ao usar essa classe para reprodução.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE também é para uma solicitação temporária, mas também expressa que seu aplicativo espera que o dispositivo não reproduza mais nada. Isso normalmente é usado se você estiver fazendo gravação de áudio ou reconhecimento de fala e não quiser que as notificações de exemplos sejam reproduzidas pelo sistema durante esse tempo.</li></ul>

Uma AudioFocusRequest instância sempre contém um dos quatro tipos de solicitações explicados acima. Ela é passada ao compilar uma AudioFocusRequest instância com seu construtor no Builder construtor AudioFocusRequest.Builder#Builder(int)ou AudioFocusRequest.Builder#setFocusGain(int) depois de copiar uma instância existente com AudioFocusRequest.Builder#Builder(AudioFocusRequest).

<h3>Qualificando sua solicitação< de foco/h3><h4>Caso de uso que exige uma solicitação< de foco/h4>

Qualquer solicitação de foco é qualificada pelo AudioAttributes (veja Builder#setAudioAttributes(AudioAttributes)) que descreve o caso de uso de áudio que seguirá a solicitação (depois que ela for bem-sucedida ou concedida). É recomendável usar o mesmo AudioAttributes para a solicitação que os atributos que você está usando para reprodução de áudio/mídia. <br>Se nenhum atributo for definido, os atributos padrão serão AudioAttributes#USAGE_MEDIA usados.

<h4>Foco< atrasado/h4>

O foco de áudio pode ser "bloqueado" pelo sistema por vários motivos: durante uma chamada telefônica, quando o carro ao qual o dispositivo está conectado reproduz uma mensagem de emergência... Para dar suporte a essas situações, o aplicativo pode solicitar que seja notificado quando sua solicitação for atendida, sinalizando sua solicitação como aceitando o foco atrasado, com Builder#setAcceptsDelayedFocusGain(boolean). <br>Se o foco for solicitado enquanto estiver bloqueado pelo sistema, AudioManager#requestAudioFocus(AudioFocusRequest) retornará AudioManager#AUDIOFOCUS_REQUEST_DELAYED. Quando o foco não estiver mais bloqueado, o ouvinte de foco definido com Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener) ou com Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener, Handler) será chamado para notificar o aplicativo que ele agora possui foco de áudio.

<h4>Pausar vs pato</h4>

Quando um aplicativo solicitado foco de áudio com AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, o sistema se esquivará do proprietário do foco atual.

Observação: esse comportamento é <b>novo para Android O</b>, enquanto os aplicativos direcionados ao nível do SDK até a API 25 tiveram que implementar o próprio pato quando receberam uma perda de foco.AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK

Mas o pato nem sempre é o comportamento esperado pelo usuário. Um exemplo típico é quando o dispositivo executa direções de condução enquanto o usuário está ouvindo um livro de áudio ou podcast e espera que a reprodução de áudio pause, em vez de pato, pois é difícil entender um prompt de navegação e conteúdo falado ao mesmo tempo. Portanto, o sistema não será automaticamente evitado quando detectar que ele estaria evitando conteúdo falado: esse conteúdo é detectado quando o AudioAttributes jogador é qualificado por AudioAttributes#CONTENT_TYPE_SPEECH. Consulte, por exemplo AudioAttributes.Builder#setContentType(int) , e MediaPlayer#setAudioAttributes(AudioAttributes) se você estiver escrevendo um aplicativo de reprodução de mídia para livro de áudio, podcasts... Como o sistema não se esquivará automaticamente dos aplicativos que reproduzem fala, ele chama o ouvinte de AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCKfoco para notificá-los, para que eles possam pausar. Observe que esse comportamento é independente do uso de AudioFocusRequest, mas vinculado ao uso de AudioAttributes.

Se seu aplicativo exigir pausa em vez de se esquivar por qualquer outro motivo que não seja reproduzir fala, você também poderá declarar isso com , o que fará com Builder#setWillPauseWhenDucked(boolean)que o sistema chame seu ouvinte de foco em vez de se esquivar automaticamente.

<h4>Exemplo</h4>

O exemplo a seguir aborda as etapas a seguir a serem encontradas em qualquer aplicativo que reproduziria áudio e usaria o foco de áudio. Aqui, reproduzimos um livro de áudio e nosso aplicativo se destina a pausar em vez de se abaixar quando perder o foco. Estas etapas consistem em: <ul><li>Criando AudioAttributes para ser usado para a reprodução e a solicitação de foco.</li li>><Configurar e criar a AudioFocusRequest instância que define os comportamentos de foco pretendidos.</li li><>Solicitando foco de áudio e verificando o código de retorno para ver se a reprodução pode acontecer imediatamente ou está atrasada.</li li><>Implementando um ouvinte de mudança de foco para responder a ganhos e perdas de foco.</li></ul>

// initialization of the audio attributes and focus request
            mAudioManager = (AudioManager) Context.getSystemService(Context.AUDIO_SERVICE);
            mPlaybackAttributes = new AudioAttributes.Builder()
                    .setUsage(AudioAttributes.USAGE_MEDIA)
                    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
                    .build();
            mFocusRequest = new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
                    .setAudioAttributes(mPlaybackAttributes)
                    .setAcceptsDelayedFocusGain(true)
                    .setWillPauseWhenDucked(true)
                    .setOnAudioFocusChangeListener(this, mMyHandler)
                    .build();
            mMediaPlayer = new MediaPlayer();
            mMediaPlayer.setAudioAttributes(mPlaybackAttributes);
            final Object mFocusLock = new Object();

            boolean mPlaybackDelayed = false;

            // requesting audio focus
            int res = mAudioManager.requestAudioFocus(mFocusRequest);
            synchronized (mFocusLock) {
                if (res == AudioManager.AUDIOFOCUS_REQUEST_FAILED) {
                    mPlaybackDelayed = false;
                } else if (res == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
                    mPlaybackDelayed = false;
                    playbackNow();
                } else if (res == AudioManager.AUDIOFOCUS_REQUEST_DELAYED) {
                   mPlaybackDelayed = true;
                }
            }

            // implementation of the OnAudioFocusChangeListener
            @Override
            public void onAudioFocusChange(int focusChange) {
                switch (focusChange) {
                    case AudioManager.AUDIOFOCUS_GAIN:
                        if (mPlaybackDelayed || mResumeOnFocusGain) {
                            synchronized (mFocusLock) {
                                mPlaybackDelayed = false;
                                mResumeOnFocusGain = false;
                            }
                            playbackNow();
                        }
                        break;
                    case AudioManager.AUDIOFOCUS_LOSS:
                        synchronized (mFocusLock) {
                            // this is not a transient loss, we shouldn't automatically resume for now
                            mResumeOnFocusGain = false;
                            mPlaybackDelayed = false;
                        }
                        pausePlayback();
                        break;
                    case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT:
                    case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK:
                        // we handle all transient losses the same way because we never duck audio books
                        synchronized (mFocusLock) {
                            // we should only resume if playback was interrupted
                            mResumeOnFocusGain = mMediaPlayer.isPlaying();
                            mPlaybackDelayed = false;
                        }
                        pausePlayback();
                        break;
                }
            }

            // Important:
            // Also set "mResumeOnFocusGain" to false when the user pauses or stops playback: this way your
            // application doesn't automatically restart when it gains focus, even though the user had
            // stopped it.

Java documentação para android.media.AudioFocusRequest.

Partes desta página são modificações baseadas no trabalho criado e compartilhado pelo Project Open Source do Open Source e usadas de acordo com os termos descritos na Creative Commons 2.5.