Google se compromete a impulsar la igualdad racial para las comunidades afrodescendientes. Obtén información al respecto.

Cómo administrar el foco de audio

Dos o más apps para Android pueden reproducir audio en la misma transmisión de salida de forma simultánea y el sistema se ocupa de mezclar todo. Si bien esta función es técnicamente impresionante, puede resultar muy molesta para el usuario. Para evitar que todas las apps de música reproduzcan contenido al mismo tiempo, Android presenta el concepto de foco de audio. Solo una app por vez puede mantener el foco de audio.

Cuando tu app necesita transmitir audio, debe solicitar el foco de audio. Cuando lo recibe, puede reproducir sonido. Sin embargo, después de adquirir el foco de audio, es posible que no pueda mantenerlo hasta que termine la reproducción. Si otra app solicita el foco de audio, tu app dejará de tenerlo. Si eso ocurre, debería pausar la reproducción o bajar el volumen para que los usuarios escuchen la nueva fuente de audio con más facilidad.

El foco de audio es cooperativo. Si bien te alentamos a que programes tu app de modo que cumpla con los lineamientos del foco de audio, el sistema no impone las reglas. Si una aplicación quiere seguir reproduciendo contenido a un volumen alto, incluso luego de haber perdido el foco de audio, no hay nada que se lo impida. Esa es una mala experiencia y es muy probable que los usuarios desinstalen una app que se comporte de ese modo incorrecto.

Una app de audio que tiene un buen comportamiento debe administrar el foco de audio de acuerdo con estos lineamientos generales:

  • Debe llamar a requestAudioFocus() justo antes de comenzar a reproducir contenido y verificar que la llamada muestre AUDIOFOCUS_REQUEST_GRANTED. Si diseñas tu app como se describe en esta guía, la llamada a requestAudioFocus() se debe realizar en la devolución de llamada onPlay() de tu sesión multimedia.
  • Cuando otra app obtiene el foco de audio, la tuya debe detener o pausar la reproducción, o bajar el volumen.
  • Cuando la reproducción se detiene, debe abandonar el foco de audio.

El foco de audio se maneja de manera diferente según la versión de Android que se ejecute:

  • A partir de Android 2.2 (API nivel 8), las apps llaman a requestAudioFocus() y a abandonAudioFocus() para administrar el foco de audio. También deben registrar un AudioManager.OnAudioFocusChangeListener con ambas llamadas para recibir devoluciones de llamada y administrar su propio nivel de audio.
  • En el caso de las apps orientadas a Android 5.0 (API nivel 21) y versiones posteriores, las apps de audio deben usar AudioAttributes para describir el tipo de audio que reproduce tu app. Por ejemplo, las aplicaciones que reproducen contenido de voz deben especificar CONTENT_TYPE_SPEECH.
  • Las apps que ejecutan Android 8.0 (API nivel 26) o versiones posteriores deben usar el método requestAudioFocus(), que toma un parámetro AudioFocusRequest. AudioFocusRequest contiene información sobre el contexto de audio y las funciones de tu app. El sistema usa esta información para administrar automáticamente la obtención y la pérdida del foco de audio.

Foco de audio en Android 8.0 y versiones posteriores

A partir de Android 8.0 (API nivel 26), cuando llamas a requestAudioFocus(), debes proporcionar un parámetro AudioFocusRequest. Para liberar el foco de audio, llama al método abandonAudioFocusRequest(), que también toma un AudioFocusRequest como argumento. Se debe usar la misma instancia de AudioFocusRequest al solicitar y abandonar el foco.

Para crear un AudioFocusRequest, usa un AudioFocusRequest.Builder. Dado que una solicitud de foco siempre debe especificar de qué tipo es, este se incluye en el constructor para el compilador. Usa los métodos del compilador para establecer los otros campos de la solicitud.

El campo FocusGain es obligatorio; todos los demás son opcionales.

MétodoNotas
setFocusGain() Este campo es obligatorio en todas las solicitudes. Toma los mismos valores que el objeto durationHint utilizado en la llamada de versiones previas a Android 8.0 a requestAudioFocus(): AUDIOFOCUS_GAIN, AUDIOFOCUS_GAIN_TRANSIENT, AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK o AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE.
setAudioAttributes() AudioAttributes describe el caso práctico de tu app. El sistema observa esos atributos cuando una aplicación obtiene y pierde el foco de audio. Los atributos reemplazan la noción de tipo de transmisión. En Android 8.0 (API nivel 26) y versiones posteriores, dejaron de estar disponibles los tipos de transmisión para cualquier operación que no sea la de los controles de volumen. Usa los mismos atributos en la solicitud del foco que usas en tu reproductor de audio (como se muestra en el ejemplo que sigue a esta tabla).

Primero usa un AudioAttributes.Builder para especificar los atributos y luego usa este método para asignar los atributos a la solicitud.

Si no se especifica, el valor predeterminado de AudioAttributes es AudioAttributes.USAGE_MEDIA.

setWillPauseWhenDucked() Cuando otra aplicación solicita el foco con AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, la app que lo tiene en ese momento no suele recibir una devolución de llamada onAudioFocusChange() porque el sistema puede disminuir el volumen por sí mismo. Cuando necesites pausar la reproducción en lugar de bajar el volumen, llama a setWillPauseWhenDucked(true) y crea y configura un OnAudioFocusChangeListener, como se describe en Disminución automática del volumen.
setAcceptsDelayedFocusGain() Una solicitud de foco de audio puede fallar cuando otra aplicación bloquea el foco. Este método permite una obtención demorada del foco: la capacidad de adquirir el foco de manera asíncrona cuando esté disponible.

Ten en cuenta que la obtención demorada del foco solo funciona si también especificas AudioManager.OnAudioFocusChangeListener en la solicitud de audio, ya que tu app necesita recibir la devolución de llamada para saber si se otorgó el foco.

setOnAudioFocusChangeListener() Un OnAudioFocusChangeListener solo es necesario si también especificas willPauseWhenDucked(true) o setAcceptsDelayedFocusGain(true) en la solicitud.

Hay dos métodos para configurar el objeto de escucha: uno con un argumento de controlador y otro sin él. El controlador es el subproceso en el que se ejecuta el objeto de escucha. Si no especificas un controlador, se usa el que está asociado con el Looper principal.

En el siguiente ejemplo, se muestra cómo usar un AudioFocusRequest.Builder para crear una AudioFocusRequest y solicitar y abandonar el foco de audio:

Kotlin

    audioManager = getSystemService(Context.AUDIO_SERVICE) as AudioManager
    focusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN).run {
        setAudioAttributes(AudioAttributes.Builder().run {
            setUsage(AudioAttributes.USAGE_GAME)
            setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
            build()
        })
        setAcceptsDelayedFocusGain(true)
        setOnAudioFocusChangeListener(afChangeListener, handler)
        build()
    }
    mediaPlayer = MediaPlayer()
    val focusLock = Any()

    var playbackDelayed = false
    var playbackNowAuthorized = false

    // ...
    val res = audioManager.requestAudioFocus(focusRequest)
    synchronized(focusLock) {
        playbackNowAuthorized = when (res) {
            AudioManager.AUDIOFOCUS_REQUEST_FAILED -> false
            AudioManager.AUDIOFOCUS_REQUEST_GRANTED -> {
                playbackNow()
                true
            }
            AudioManager.AUDIOFOCUS_REQUEST_DELAYED -> {
                playbackDelayed = true
                false
            }
            else -> false
        }
    }

    // ...
    override fun onAudioFocusChange(focusChange: Int) {
        when (focusChange) {
            AudioManager.AUDIOFOCUS_GAIN ->
                if (playbackDelayed || resumeOnFocusGain) {
                    synchronized(focusLock) {
                        playbackDelayed = false
                        resumeOnFocusGain = false
                    }
                    playbackNow()
                }
            AudioManager.AUDIOFOCUS_LOSS -> {
                synchronized(focusLock) {
                    resumeOnFocusGain = false
                    playbackDelayed = false
                }
                pausePlayback()
            }
            AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
                synchronized(focusLock) {
                    resumeOnFocusGain = true
                    playbackDelayed = false
                }
                pausePlayback()
            }
            AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
                // ... pausing or ducking depends on your app
            }
        }
    }
    

Java

    audioManager = (AudioManager) Context.getSystemService(Context.AUDIO_SERVICE);
    playbackAttributes = new AudioAttributes.Builder()
            .setUsage(AudioAttributes.USAGE_GAME)
            .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
            .build();
    focusRequest = new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
            .setAudioAttributes(playbackAttributes)
            .setAcceptsDelayedFocusGain(true)
            .setOnAudioFocusChangeListener(afChangeListener, handler)
            .build();
    mediaPlayer = new MediaPlayer();
    final Object focusLock = new Object();

    boolean playbackDelayed = false;
    boolean playbackNowAuthorized = false;

    // ...
    int res = audioManager.requestAudioFocus(focusRequest);
    synchronized(focusLock) {
        if (res == AudioManager.AUDIOFOCUS_REQUEST_FAILED) {
            playbackNowAuthorized = false;
        } else if (res == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
            playbackNowAuthorized = true;
            playbackNow();
        } else if (res == AudioManager.AUDIOFOCUS_REQUEST_DELAYED) {
           playbackDelayed = true;
           playbackNowAuthorized = false;
        }
    }

    // ...
    @Override
    public void onAudioFocusChange(int focusChange) {
        switch (focusChange) {
            case AudioManager.AUDIOFOCUS_GAIN:
                if (playbackDelayed || resumeOnFocusGain) {
                    synchronized(focusLock) {
                        playbackDelayed = false;
                        resumeOnFocusGain = false;
                    }
                    playbackNow();
                }
                break;
            case AudioManager.AUDIOFOCUS_LOSS:
                synchronized(focusLock) {
                    resumeOnFocusGain = false;
                    playbackDelayed = false;
                }
                pausePlayback();
                break;
            case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT:
                synchronized(focusLock) {
                    resumeOnFocusGain = true;
                    playbackDelayed = false;
                }
                pausePlayback();
                break;
            case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK:
                // ... pausing or ducking depends on your app
                break;
            }
        }
    }
    

Disminución automática del volumen

En Android 8.0 (API nivel 26), cuando otra app solicita el foco con AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, el sistema puede disminuir y restaurar el volumen sin invocar la devolución de llamada onAudioFocusChange() de la aplicación.

Si bien la disminución automática del volumen es un comportamiento aceptable para las apps de reproducción de música y video, no es útil cuando se reproduce contenido de voz, como en una app de audiolibros. En este caso, la aplicación debería pausar la reproducción.

Si deseas que tu app pause la reproducción cuando se le pida que disminuya volumen, crea un OnAudioFocusChangeListener con un método de devolución de llamada onAudioFocusChange() que implemente el comportamiento de pausa/reanudación deseado. Llama a setOnAudioFocusChangeListener() para registrar el objeto de escucha y llama a setWillPauseWhenDucked(true) para indicarle al sistema que use tu devolución de llamada en lugar de aplicar la disminución automática del volumen.

Obtención demorada del foco

En ocasiones, el sistema no puede aceptar una solicitud de foco de audio porque otra app lo está "bloqueando"; por ejemplo, cuando hay una llamada telefónica en curso. En este caso, requestAudioFocus() muestra AUDIOFOCUS_REQUEST_FAILED. Cuando esto sucede, tu app no debe continuar con la reproducción de audio porque no obtuvo el foco.

El método setAcceptsDelayedFocusGain(true) le permite a tu app manejar una solicitud de foco de manera asíncrona. Con esta marca establecida, una solicitud que se realiza cuando el foco está bloqueado muestra AUDIOFOCUS_REQUEST_DELAYED. Cuando la condición que bloqueó el foco de audio deja de existir, como cuando termina una llamada telefónica, el sistema acepta la solicitud de foco pendiente y llama a onAudioFocusChange() para informárselo a tu app.

A fin de manejar la obtención demorada del foco, debes crear un OnAudioFocusChangeListener con un método de devolución de llamada onAudioFocusChange() que implemente el comportamiento deseado y llamar a setOnAudioFocusChangeListener() para registrar el objeto de escucha.

Foco de audio en versiones previas a Android 8.0

Cuando llamas a requestAudioFocus(), debes especificar una sugerencia de duración, que puede respetar otra app que tenga el foco en ese momento y esté reproduciendo contenido:

  • Solicita el foco de audio permanente (AUDIOFOCUS_GAIN) cuando planees reproducir audio en el futuro próximo (por ejemplo, para reproducir música) y esperes que el elemento que tiene el foco de audio en ese momento deje de reproducir su contenido.
  • Solicita el foco transitorio (AUDIOFOCUS_GAIN_TRANSIENT) cuando planees reproducir audio durante un período breve y esperes que el elemento anterior que tenía el foco pause la reproducción.
  • Solicita el foco transitorio con disminución de volumen (AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK) para indicar que esperas reproducir audio solo durante un período breve y que está bien que el elemento anterior que tenía el foco siga reproduciendo si disminuye el volumen de su salida de audio. Ambas salidas se mezclan en la transmisión de audio. La disminución del volumen es adecuada en especial para las apps que usan la transmisión de audio de forma intermitente, como las que brindan rutas en auto audibles.

El método requestAudioFocus() también requiere un AudioManager.OnAudioFocusChangeListener. Este objeto de escucha debe crearse en la misma actividad o servicio que posee tu sesión multimedia. Implementa la devolución de llamada onAudioFocusChange() que recibe tu aplicación cuando alguna otra app adquiere o abandona el foco de audio.

El siguiente fragmento solicita el foco de audio permanente en la transmisión STREAM_MUSIC y registra un OnAudioFocusChangeListener para manejar los cambios posteriores en el foco. (El objeto de escucha de cambios se analiza en Cómo responder a un cambio de foco de audio).

Kotlin

    audioManager = getSystemService(Context.AUDIO_SERVICE) as AudioManager
    lateinit var afChangeListener AudioManager.OnAudioFocusChangeListener

    ...
    // Request audio focus for playback
    val result: Int = audioManager.requestAudioFocus(
            afChangeListener,
            // Use the music stream.
            AudioManager.STREAM_MUSIC,
            // Request permanent focus.
            AudioManager.AUDIOFOCUS_GAIN
    )

    if (result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
        // Start playback
    }
    

Java

    AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
    AudioManager.OnAudioFocusChangeListener afChangeListener;

    ...
    // Request audio focus for playback
    int result = audioManager.requestAudioFocus(afChangeListener,
                                 // Use the music stream.
                                 AudioManager.STREAM_MUSIC,
                                 // Request permanent focus.
                                 AudioManager.AUDIOFOCUS_GAIN);

    if (result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
        // Start playback
    }
    

Cuando termines la reproducción, llama a abandonAudioFocus().

Kotlin

    audioManager.abandonAudioFocus(afChangeListener)
    

Java

    // Abandon audio focus when playback complete
    audioManager.abandonAudioFocus(afChangeListener);
    

De este modo, se informa al sistema que ya no necesitas el foco y se cancela el registro del OnAudioFocusChangeListener asociado. Si solicitaste un foco transitorio, se informará a la app que haya pausado la reproducción o disminuido su volumen que puede reanudarla o restaurar el volumen.

Cómo responder a un cambio de foco de audio

Cuando una app adquiere el foco de audio, debe poder liberarlo cuando otra app lo solicite para sí misma. En ese momento, tu app recibe una llamada al método onAudioFocusChange() en el AudioFocusChangeListener que especificaste cuando la app llamó a requestAudioFocus().

El parámetro focusChange pasado a onAudioFocusChange() indica el tipo de cambio que se produce. Corresponde a la sugerencia de duración que usa la app que está adquiriendo el foco. Tu app debería responder de manera adecuada.

Pérdida transitoria del foco
Si el cambio de foco es transitorio (AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK o AUDIOFOCUS_LOSS_TRANSIENT), tu app debe disminuir el volumen (si no usa la disminución automática de volumen) o pausar la reproducción, y no alterar su estado más allá de eso.

Durante una pérdida transitoria del foco de audio, debes seguir supervisando los cambios del foco y estar preparado para reanudar la reproducción normal al recuperar el foco. Cuando la app que bloqueaba el foco lo abandona, recibes una devolución de llamada (AUDIOFOCUS_GAIN). En este punto, puedes restaurar el volumen al nivel normal o reiniciar la reproducción.

Pérdida permanente del foco
Si la pérdida del foco de audio es permanente (AUDIOFOCUS_LOSS), otra app está reproduciendo audio. Tu aplicación debe pausar la reproducción de inmediato, ya que no recibirá una devolución de llamada AUDIOFOCUS_GAIN. Para reiniciar la reproducción, el usuario debe realizar una acción explícita, como presionar el control de transporte de reproducción en una notificación o en la IU de la app.

En el siguiente fragmento de código, se demuestra cómo implementar el OnAudioFocusChangeListener y su devolución de llamada onAudioFocusChange(). Observa el uso de un Handler para demorar la devolución de llamada de detención en una pérdida permanente del foco de audio.

Kotlin

    private val handler = Handler()
    private val afChangeListener = AudioManager.OnAudioFocusChangeListener { focusChange ->
        when (focusChange) {
            AudioManager.AUDIOFOCUS_LOSS -> {
                // Permanent loss of audio focus
                // Pause playback immediately
                mediaController.transportControls.pause()
                // Wait 30 seconds before stopping playback
                handler.postDelayed(delayedStopRunnable, TimeUnit.SECONDS.toMillis(30))
            }
            AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
                // Pause playback
            }
            AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
                // Lower the volume, keep playing
            }
            AudioManager.AUDIOFOCUS_GAIN -> {
                // Your app has been granted audio focus again
                // Raise volume to normal, restart playback if necessary
            }
        }
    }
    

Java

    private Handler handler = new Handler();
    AudioManager.OnAudioFocusChangeListener afChangeListener =
      new AudioManager.OnAudioFocusChangeListener() {
        public void onAudioFocusChange(int focusChange) {
          if (focusChange == AudioManager.AUDIOFOCUS_LOSS) {
            // Permanent loss of audio focus
            // Pause playback immediately
            mediaController.getTransportControls().pause();
            // Wait 30 seconds before stopping playback
            handler.postDelayed(delayedStopRunnable,
              TimeUnit.SECONDS.toMillis(30));
          }
          else if (focusChange == AudioManager.AUDIOFOCUS_LOSS_TRANSIENT) {
            // Pause playback
          } else if (focusChange == AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK) {
            // Lower the volume, keep playing
          } else if (focusChange == AudioManager.AUDIOFOCUS_GAIN) {
            // Your app has been granted audio focus again
            // Raise volume to normal, restart playback if necessary
          }
        }
      };
    

El controlador usa un Runnable que tiene el siguiente aspecto:

Kotlin

    private var delayedStopRunnable = Runnable {
        mediaController.transportControls.stop()
    }
    

Java

    private Runnable delayedStopRunnable = new Runnable() {
        @Override
        public void run() {
            getMediaController().getTransportControls().stop();
        }
    };
    

Para garantizar que la detención demorada no se active si el usuario reinicia la reproducción, llama a mHandler.removeCallbacks(mDelayedStopRunnable) en respuesta a cualquier cambio de estado. Por ejemplo, llama a removeCallbacks() en onPlay(), onSkipToNext(), etc., de tu devolución de llamada. También debes llamar a este método en la devolución de llamada onDestroy() de tu servicio cuando limpies los recursos que utiliza.