AudioFocusRequestClass Clase

Definición

[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

Herencia

Object

JavaObject

Object

AudioFocusRequestClass

Atributos

RegisterAttribute

Comentarios

Clase para encapsular información sobre una solicitud de foco de audio. Una AudioFocusRequest instancia se compila mediante Buildery se usa para solicitar y abandonar el foco de audio, respectivamente con AudioManager#requestAudioFocus(AudioFocusRequest) y AudioManager#abandonAudioFocusRequest(AudioFocusRequest).

<h3>¿Qué es el foco de audio?</h3>

El foco de audio es un concepto introducido en la API 8. Se usa para transmitir el hecho de que un usuario solo puede centrarse en una sola secuencia de audio a la vez, por ejemplo, escuchar música o podcast, pero no ambos al mismo tiempo. En algunos casos, varias secuencias de audio pueden reproducirse al mismo tiempo, pero solo hay una que el usuario realmente escucharía (centrarse en), mientras que la otra se reproduce en segundo plano. Un ejemplo de esto es conducir indicaciones que se hablan mientras la música se reproduce en un volumen reducido (a.k.a. pato).

Cuando una aplicación solicita el foco de audio, expresa su intención de "poseer" el foco de audio para reproducir audio. Vamos a revisar los distintos tipos de solicitudes de enfoque, el valor devuelto después de una solicitud y las respuestas a una pérdida.

Nota: las aplicaciones no deben reproducir nada hasta que se conceda el foco.

<h3>Los diferentes tipos de solicitudes< de enfoque/h3>

Hay cuatro tipos de solicitudes de enfoque. Una solicitud de enfoque correcta con cada una producirá comportamientos diferentes por el sistema y la otra aplicación que anteriormente tenía el foco de audio. <ul><li>AudioManager#AUDIOFOCUS_GAIN expresa el hecho de que la aplicación es ahora la única fuente de audio a la que escucha el usuario. La duración de la reproducción de audio es desconocida y, posiblemente, es muy larga: después de que el usuario termine de interactuar con la aplicación, (s) no espera que se reanude otra secuencia de audio. Algunos ejemplos de usos de esta ganancia de foco son para la reproducción de música, para un juego o un reproductor de vídeo.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT es para una situación cuando sabe que la aplicación está capturando temporalmente el foco del propietario actual, pero el usuario espera que la reproducción vuelva a donde estaba una vez que la aplicación ya no requiere el foco de audio. Un ejemplo es para reproducir una alarma o durante una llamada voIP. Se sabe que la reproducción es finita: la alarma agotará el tiempo de espera o se descartará, la llamada voIP tiene un principio y un final. Cuando finaliza cualquiera de esos eventos y si el usuario estaba escuchando música cuando se inició, el usuario espera que la música se reanude, pero no quería escuchar ambos al mismo tiempo.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK: este tipo de solicitud de enfoque es similar al AUDIOFOCUS_GAIN_TRANSIENT aspecto temporal de la solicitud de enfoque, pero también expresa el hecho durante el tiempo que posee el foco, permite que otra aplicación siga jugando en un volumen reducido, "pato". Algunos ejemplos son cuando se reproducen indicaciones o notificaciones, es correcto que la música siga reproduciendo, pero no lo suficientemente fuerte como para evitar que las indicaciones sean difíciles de entender. Una atenuación típica de la aplicación "ducked" es un factor de 0,2f (o -14dB), que se puede aplicar por ejemplo con MediaPlayer.setVolume(0.2f) cuando se usa esta clase para la reproducción.</li>

<li>AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE también es para una solicitud temporal, pero también expresa que la aplicación espera que el dispositivo no juegue nada más. Esto se usa normalmente si está realizando la grabación de audio o el reconocimiento de voz, y no quiere que el sistema reproduzca las notificaciones de ejemplos durante ese tiempo.</li></ul>

Una AudioFocusRequest instancia siempre contiene uno de los cuatro tipos de solicitudes explicados anteriormente. Se pasa al compilar una AudioFocusRequest instancia con su generador en el Builder constructor AudioFocusRequest.Builder#Builder(int)o con AudioFocusRequest.Builder#setFocusGain(int) después de copiar una instancia existente con AudioFocusRequest.Builder#Builder(AudioFocusRequest).

"note"><b>Note:</b> Si una aplicación tiene como destino Android 15 (nivel de API 35) o superior, no puede solicitar el foco de audio a menos que sea la aplicación superior o ejecute un servicio en primer plano. Este requisito es similar a los requisitos para la reproducción de audio. Si una aplicación solicita el foco de audio cuando no cumple estos requisitos, el método devuelve <c>AudioManager#AUDIOFOCUS_REQUEST_FAILED</c>. </aside>

<h3>Calificar la solicitud< de enfoque/h3><h4>Caso de uso que requiere una solicitud< de enfoque/h4>

Cualquier solicitud de enfoque está calificada por ( AudioAttributes vea Builder#setAudioAttributes(AudioAttributes)) que describe el caso de uso de audio que seguirá la solicitud (una vez que se haya concedido o realizado correctamente). Se recomienda usar lo mismo AudioAttributes para la solicitud que los atributos que usa para la reproducción de audio o multimedia. <br>Si no se establecen atributos, se usan atributos predeterminados de AudioAttributes#USAGE_MEDIA .

<h4>Enfoque< retrasado/h4>

El foco de audio puede ser "bloqueado" por el sistema por varias razones: durante una llamada telefónica, cuando el coche al que está conectado el dispositivo reproduce un mensaje de emergencia... Para admitir estas situaciones, la aplicación puede solicitar que se notifique cuando se cumpla su solicitud, marcando su solicitud como aceptando el enfoque retrasado, con Builder#setAcceptsDelayedFocusGain(boolean). <br>Si se solicita el foco mientras el sistema está bloqueado, AudioManager#requestAudioFocus(AudioFocusRequest) devolverá AudioManager#AUDIOFOCUS_REQUEST_DELAYED. Cuando el foco ya no está bloqueado, se llamará al agente de escucha de foco con Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener) o con Builder#setOnAudioFocusChangeListener(OnAudioFocusChangeListener, Handler) para notificar a la aplicación que ahora posee el foco de audio.

<h4>Pausa frente al< pato/h4>

Cuando una aplicación solicitó el foco de audio con AudioManager#AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, el sistema pato al propietario actual del foco.

Nota: este comportamiento es <b>nuevo para android O</b>, mientras que las aplicaciones destinadas al nivel del SDK hasta la API 25 tenían que implementar el pato a sí mismos cuando recibieron una pérdida de foco de AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK.

Pero el pato no siempre es el comportamiento esperado por el usuario. Un ejemplo típico es cuando el dispositivo reproduce indicaciones de conducción mientras el usuario escucha un audio book o podcast, y espera que la reproducción de audio se detenga, en lugar de pato, ya que es difícil entender un mensaje de navegación y contenido hablado al mismo tiempo. Por lo tanto, el sistema no se pato automáticamente cuando detecte que sería el contenido hablado: este contenido se detecta cuando AudioAttributes el del jugador está calificado por AudioAttributes#CONTENT_TYPE_SPEECH. Consulte por ejemplo a AudioAttributes.Builder#setContentType(int) y MediaPlayer#setAudioAttributes(AudioAttributes) si está escribiendo una aplicación de reproducción multimedia para audio book, podcasts... Dado que el sistema no pato automáticamente las aplicaciones que reproducen voz, llama a su agente de escucha de foco en su lugar para notificarlas de AudioManager#AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK, por lo que pueden pausarse en su lugar. Tenga en cuenta que este comportamiento es independiente del uso de AudioFocusRequest, pero vinculado al uso de AudioAttributes.

Si la aplicación requiere pausar en lugar de pato por cualquier otro motivo que la reproducción de voz, también puede declararlo con Builder#setWillPauseWhenDucked(boolean), lo que hará que el sistema llame a su agente de escucha de foco en lugar de pato automáticamente.

<h4>Ejemplo</h4>

En el ejemplo siguiente se describen los pasos siguientes que se encuentran en cualquier aplicación que reproduciría audio y usar el foco de audio. Aquí reproducimos un libro de audio y nuestra aplicación está pensada para pausar en lugar de pato cuando pierde el foco. Estos pasos constan de: <ul><li>Creating AudioAttributes que se usará para la reproducción y la solicitud de enfoque.</li li><>Configuring and creating the AudioFocusRequest instance that define the intended focus behaviors.</li li><>Solicita el foco de audio y comprueba el código de retorno para ver si la reproducción puede ocurrir inmediatamente o se retrasa.</li li><>Implementación de un agente de escucha de cambio de foco para responder a ganancias y pérdidas 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 documentación para android.media.AudioFocusRequest.

Las partes de esta página son modificaciones basadas en el trabajo creado y compartido por el Android y se usan según los términos descritos en creative Creative Commons 2.5 Attribution License.