Cómo administrar el foco de audio

Dos o más apps para Android pueden reproducir audio en el mismo flujo de salida de forma simultánea, y el sistema mezcla todo. Si bien esto es técnicamente impresionante, puede ser muy molesto para el usuario. Para evitar que todas las apps de música se reproduzcan al mismo tiempo, Android presenta la idea 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 tiene el foco, puede reproducir sonido. Sin embargo, después de adquirir el foco de audio, es posible que no puedas mantenerlo hasta que termines de reproducir. Otra app puede solicitar el foco, lo que anula tu retención del foco de audio. Si eso sucede, tu app debería pausar la reproducción o bajar el volumen para que los usuarios puedan escuchar la nueva fuente de audio con mayor facilidad.

Antes de Android 12 (nivel de API 31), el sistema no administraba el foco de audio. Por lo tanto, si bien se recomienda que los desarrolladores de apps cumplan con los lineamientos de foco de audio, si una app sigue reproduciendo sonido a un volumen alto incluso después de perder el foco de audio en un dispositivo que ejecuta Android 11 (nivel de API 30) o una versión anterior, el sistema no puede evitarlo. Sin embargo, este comportamiento de la app genera una mala experiencia del usuario y, a menudo, puede hacer que los usuarios desinstalen la app que no funciona correctamente.

Una app de audio bien diseñada debe administrar el foco de audio de acuerdo con estos lineamientos generales:

• Llama a requestAudioFocus() inmediatamente antes de comenzar a reproducir y verifica que la llamada devuelva AUDIOFOCUS_REQUEST_GRANTED. Realiza la llamada a requestAudioFocus() en la devolución de llamada onPlay() de tu sesión multimedia.

• Cuando otra app obtenga el foco de audio, detén o pausa la reproducción, o bien atenúa (es decir, reduce) el volumen.

• Cuando se detenga la reproducción (por ejemplo, cuando la app no tenga nada más para reproducir), abandona el foco de audio. Tu app no tiene que abandonar el foco de audio si el usuario pausa la reproducción, pero es posible que la reanude más tarde.

• Usa AudioAttributes para describir el tipo de audio que reproduce tu app. Por ejemplo, para las apps que reproducen voz, especifica CONTENT_TYPE_SPEECH.

El foco de audio se controla de manera diferente según la versión de Android que se esté ejecutando:

Android 12 (nivel de API 31) o versiones posteriores

El sistema administra el foco de audio. El sistema fuerza la atenuación de la reproducción de audio de una app cuando otra solicita el foco de audio. El sistema también silencia la reproducción de audio cuando se recibe una llamada entrante.

Android 8.0 (nivel de API 26) a Android 11 (nivel de API 30)

El sistema no administra el foco de audio, pero incluye algunos cambios que se introdujeron a partir de Android 8.0 (nivel de API 26).

Android 7.1 (nivel de API 25) y versiones anteriores

El sistema no administra el foco de audio, y las apps lo administran con requestAudioFocus() y abandonAudioFocus().

Foco de audio en Android 12 y versiones posteriores

Una app multimedia o de videojuego que usa foco de audio no debe reproducir audio después de que pierde el foco. En Android 12 (nivel de API 31) y versiones posteriores, el sistema aplica este comportamiento. Cuando una app solicita el foco de audio mientras otra app lo tiene y está reproduciendo contenido, el sistema fuerza a la app que está reproduciendo contenido a atenuar el sonido. La adición del fundido de salida proporciona una transición más fluida cuando se pasa de una app a otra.

Este comportamiento se produce cuando se cumplen las siguientes condiciones:

1. La primera app que se está reproduciendo cumple con todos estos criterios:

   • La app tiene el atributo de uso AudioAttributes.USAGE_MEDIA o AudioAttributes.USAGE_GAME.
   • La app solicitó correctamente el foco de audio con AudioManager.AUDIOFOCUS_GAIN.
   • La app no está reproduciendo audio con el tipo de contenido AudioAttributes.CONTENT_TYPE_SPEECH.

2. Una segunda app solicita el foco de audio con AudioManager.AUDIOFOCUS_GAIN.

Cuando se cumplen estas condiciones, el sistema de audio atenúa la primera app. Al final de la atenuación, el sistema notifica a la primera app sobre la pérdida de foco. Los reproductores de la app permanecen silenciados hasta que la app vuelve a solicitar el foco de audio.

Comportamientos existentes del foco de audio

También debes tener en cuenta estos otros casos que implican un cambio en el foco de audio.

Disminución automática del volumen

La atenuación automática (reducción temporal del nivel de audio de una app para que otra se pueda escuchar con claridad) se introdujo en Android 8.0 (nivel de API 26).

Si el sistema implementa la atenuación, no es necesario que la implementes en tu app.

La disminución automática del volumen también se produce cuando una notificación de audio toma el foco de una app en reproducción. El inicio de la reproducción de notificaciones se sincroniza con el final de la rampa de disminución del volumen.

La disminución automática del volumen se produce cuando se cumplen las siguientes condiciones:

1. La primera app, que se está reproduciendo actualmente, cumple con todos estos criterios:

   • La app solicitó correctamente el foco de audio con cualquier tipo de obtención de foco.
   • La app no está reproduciendo audio con el tipo de contenido AudioAttributes.CONTENT_TYPE_SPEECH.
   • La app no estableció AudioFocusRequest.Builder.setWillPauseWhenDucked(true).

2. Una segunda app solicita el foco de audio con AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK.

Cuando se cumplen estas condiciones, el sistema de audio atenúa todos los reproductores activos de la primera app mientras la segunda app tiene el foco. Cuando la segunda app abandona el foco, se restablece el volumen. La primera app no recibe una notificación cuando pierde el foco, por lo que no tiene que hacer nada.

Ten en cuenta que la atenuación automática no se realiza cuando el usuario escucha contenido de voz, ya que podría perderse parte del programa. Por ejemplo, las indicaciones por voz para las rutas en auto no se atenúan.

Silenciar la reproducción de audio actual para las llamadas telefónicas entrantes

Algunas apps no se comportan correctamente y siguen reproduciendo audio durante las llamadas telefónicas. Esta situación obliga al usuario a buscar y silenciar o cerrar la app ofensiva para escuchar la llamada. Para evitarlo, el sistema puede silenciar el audio de otras apps mientras hay una llamada entrante. El sistema invoca esta función cuando se recibe una llamada telefónica entrante y una app cumple con estas condiciones:

• La app tiene el atributo de uso AudioAttributes.USAGE_MEDIA o AudioAttributes.USAGE_GAME.
• La app solicitó correctamente el foco de audio (cualquier obtención de foco) y está reproduciendo audio.

Si una app continúa reproduciéndose durante la llamada, se silencia la reproducción hasta que la llamada finaliza. Sin embargo, si una app comienza a reproducir contenido durante la llamada, ese reproductor no se silencia, ya que se supone que el usuario inició la reproducción de forma intencional.

Foco de audio en Android 8.0 a Android 11

A partir de Android 8.0 (nivel de API 26), cuando llamas a requestAudioFocus(), debes proporcionar un parámetro AudioFocusRequest. El AudioFocusRequest contiene información sobre el contexto de audio y las capacidades de tu app. El sistema usa esta información para administrar la obtención y la pérdida del foco de audio automáticamente. Para liberar el foco de audio, llama al método abandonAudioFocusRequest(), que también toma un AudioFocusRequest como argumento. Usa la misma instancia de AudioFocusRequest cuando solicites y abandones el foco.

Para crear un AudioFocusRequest, usa un AudioFocusRequest.Builder. Como una solicitud de foco siempre debe especificar el tipo de solicitud, este se incluye en el constructor del 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.

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

// initializing variables for audio focus and playback management
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()
}
val focusLock = Any()

var playbackDelayed = false
var playbackNowAuthorized = false

// requesting audio focus and processing the response
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
    }
}

// implementing OnAudioFocusChangeListener to react to focus changes
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) {
                // only resume if playback is being interrupted
                resumeOnFocusGain = isPlaying()
                playbackDelayed = false
            }
            pausePlayback()
        }
        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
            // ... pausing or ducking depends on your app
        }
    }
}

// initializing variables for audio focus and playback management
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();
final Object focusLock = new Object();

boolean playbackDelayed = false;
boolean playbackNowAuthorized = false;

// requesting audio focus and processing the response
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;
    }
}

// implementing OnAudioFocusChangeListener to react to focus changes
@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) {
                // only resume if playback is being interrupted
                resumeOnFocusGain = isPlaying();
                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 (nivel de API 26), cuando otra app solicita el foco con AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK, el sistema puede atenuar y restablecer el volumen sin invocar la devolución de llamada onAudioFocusChange() de la app.

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

Si quieres que tu app se detenga cuando se le solicite que atenúe el sonido en lugar de disminuir el volumen, crea un OnAudioFocusChangeListener con un método de devolución de llamada onAudioFocusChange() que implemente el comportamiento de pausa o reanudación deseado. Llama a setOnAudioFocusChangeListener() para registrar el objeto de escucha y a setWillPauseWhenDucked(true) para indicarle al sistema que use tu devolución de llamada en lugar de realizar la atenuación automática.

Obtención demorada del foco

A veces, el sistema no puede otorgar una solicitud de foco de audio porque otra app lo "bloqueó", como durante una llamada telefónica. En este caso, requestAudioFocus() devuelve 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), que permite que tu app controle una solicitud de enfoque de forma asíncrona Con esta marca establecida, una solicitud realizada cuando el enfoque está bloqueado devuelve AUDIOFOCUS_REQUEST_DELAYED. Cuando ya no exista la condición que bloqueó el foco de audio, como cuando finaliza una llamada telefónica, el sistema otorgará la solicitud de foco pendiente y llamará a onAudioFocusChange() para notificar a tu app.

Para controlar la obtención retrasada del foco, debes crear un OnAudioFocusChangeListener con un método de devolución de llamada onAudioFocusChange() que implemente el comportamiento deseado y registrar el objeto de escucha llamando a setOnAudioFocusChangeListener().

Foco de audio en Android 7.1 y versiones anteriores

Cuando llamas a requestAudioFocus(), debes especificar una sugerencia de duración, que puede respetar otra app que actualmente tiene el foco y se está reproduciendo:

• Solicita el foco de audio permanente (AUDIOFOCUS_GAIN) cuando planees reproducir audio en el futuro inmediato (por ejemplo, cuando reproduzcas música) y esperes que el titular anterior del foco de audio detenga la reproducción.
• Solicita el foco transitorio (AUDIOFOCUS_GAIN_TRANSIENT) cuando esperes reproducir audio solo por un período breve y que el titular anterior pause la reproducción.
• Solicita un foco transitorio con atenuación (AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK) para indicar que esperas reproducir audio solo durante un período breve y que está bien que el propietario del foco anterior siga reproduciendo si "atenúa" (baja) su salida de audio. Ambas salidas de audio se mezclan en la transmisión de audio. La atenuación es especialmente adecuada para las apps que usan la transmisión de audio de forma intermitente, como las instrucciones sobre cómo llegar en auto.

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

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

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
}

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().

audioManager.abandonAudioFocus(afChangeListener)

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

Esto notifica al sistema que ya no necesitas el foco y cancela el registro del OnAudioFocusChangeListener asociado. Si solicitaste un foco transitorio, esto notificará a una app que se pausó o atenuó que puede continuar con la reproducción o restablecer su 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. Cuando esto sucede, tu app recibe una llamada al método onAudioFocusChange() en el AudioFocusChangeListener que especificaste cuando la app llamó a requestAudioFocus().

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

Pérdida transitoria del foco

Si el cambio de foco es transitorio (AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK o AUDIOFOCUS_LOSS_TRANSIENT), tu app debería atenuar el volumen (si no usas la atenuación automática) o pausar la reproducción, pero mantener el mismo estado.

Durante una pérdida transitoria del foco de audio, debes seguir supervisando los cambios en el foco de audio y prepararte para reanudar la reproducción normal cuando recuperes el foco. Cuando la app que bloquea abandona el foco, recibes una devolución de llamada (AUDIOFOCUS_GAIN). En este punto, puedes restablecer 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 app debería pausar la reproducción de inmediato, ya que nunca 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 muestra cómo implementar OnAudioFocusChangeListener y su devolución de llamada onAudioFocusChange(). Observa el uso de un Handler para retrasar la devolución de llamada de detención en una pérdida permanente del foco de audio.

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
        }
    }
}

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:

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

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

Para asegurarte de que la detención retrasada 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 usa tu servicio.