Protección de audio en segundo plano

A partir de Android 17, el framework de audio aplica restricciones en las interacciones de audio en segundo plano, incluidas la reproducción de audio, las solicitudes de foco de audio y las APIs de cambio de volumen para garantizar que el usuario inicie estos cambios de forma intencional.

Todas las apps que se ejecutan en Android 17 y que tienen estas interacciones de audio en segundo plano deben tener una actividad visible o ejecutar un servicio en primer plano que no sea de tipo SHORT_SERVICE. Esto se aplica independientemente de si la app se orienta al nivel de API 37.

Si una app se orienta a Android 17 (nivel de API 37), hay una restricción adicional. Si la app se ejecuta en segundo plano, debe ejecutar un servicio en primer plano que tenga capacidades de uso mientras está en uso (WIU). (Se otorgan capacidades de WIU a un servicio en primer plano si se inicia en respuesta a una operación iniciada por el usuario o mientras la app está visible para el usuario). Sin embargo, se exime el requisito de capacidades de WIU si se le otorgó a la app el permiso exacto de alarma y se realizan cambios en las transmisiones de audio que tienen el USAGE_ALARM atributo.

Si la app intenta llamar a las APIs de audio mientras no está en un ciclo de vida válido, las APIs de reproducción de audio y de cambio de volumen fallan de forma silenciosa sin generar una excepción ni proporcionar un mensaje de falla. La API de foco de audio falla con el código de resultado AUDIOFOCUS_REQUEST_FAILED.

Por qué realizamos el cambio

El objetivo de introducir estas restricciones es reducir las experiencias de audio en segundo plano no intencionales y con errores. Aquí encontrarás algunos ejemplos:

• Las apps que reproducen audio sin un servicio en primer plano se pueden congelar. Cuando la app se descongele, se reanudará la reproducción de audio de forma inesperada, posiblemente horas después.
• Las apps que reproducen audio sin un servicio en primer plano enfrentan varias restricciones de ejecución que generan un rendimiento de audio entrecortado.
• La reproducción se separó del ciclo de vida de la actividad, lo que podría generar una sesión de reproducción filtrada o eventos de foco filtrados que continúan sin que el usuario pueda detener la reproducción.

Recomendamos a los desarrolladores que prueben sus apps y proporcionen comentarios sobre el cambio de comportamiento si hay casos de uso de audio intencionales que se vean afectados de forma negativa. Informa cualquier problema con esta herramienta de seguimiento de errores de compatibilidad de apps de Android 17.

Identifica los casos de uso de audio en segundo plano afectados

Audita la implementación de la reproducción de audio y determina si tu app pretende proporcionar funcionalidad de interacción de audio en segundo plano incluso en circunstancias condicionales.

Si tu app solo pretende reproducir audio o utilizar APIs de audio mientras muestra una actividad visible para el usuario, incluido el uso del modo de pantalla en pantalla (PIP), no se verá afectada por ninguno de estos cambios.

Si tu app proporciona funcionalidad de VOIP, incluidas las apps de videollamadas, ya debe cumplir con los requisitos que se introducen para la reproducción (por lo general, mediante el uso de las APIs de telecomunicaciones recomendadas) para grabar audio correctamente, por lo que es poco probable que se vea afectada.

Si tu app pretende continuar con la reproducción de audio mientras la pantalla está apagada o mientras tu actividad no está visible, lo que se ve con mayor frecuencia en las apps de transmisión de música o de podcasts, se considera que tu app proporciona funcionalidad de audio en segundo plano y debe cumplir con los nuevos requisitos.

Situaciones de audio en segundo plano que probablemente se vean afectadas

Si tu app no sigue el modelo de continuar una interacción de audio iniciada mientras estaba abierta o en respuesta a un activador explícito del usuario, es probable que la funcionalidad de tu app se suprima de forma silenciosa.

Por ejemplo, si tu app inicia un servicio en primer plano en respuesta a BOOT_COMPLETE y trata de interactuar con el audio, se suprimirá.

Prácticas recomendadas de audio en segundo plano para mitigar el impacto

• Usa el componente MediaSessionService de la biblioteca de Jetpack media3 para administrar la reproducción de audio en segundo plano.

  Si lo haces, es probable que la app no se vea afectada por el refuerzo en segundo plano debido a que la biblioteca ayuda a administrar el ciclo de vida de la reproducción.

• Si no aprovechas la biblioteca media3, deberás iniciar manualmente un FGS mediaPlayback. Siempre inicia un servicio en primer plano mientras la app esté en primer plano si puede ocurrir audio en segundo plano.

  Por ejemplo, si tu app es una app de transmisión de video que suele ser solo en primer plano, pero contiene una indicación visual para el usuario para continuar reproduciendo mientras la pantalla está apagada, cuando se produzca el activador de reproducción iniciado por el usuario, tu app aún debe iniciar un servicio en primer plano.

  Esto garantiza que el servicio en primer plano se inicie con capacidades de WIU.

• Mantén activo el FGS mediaPlayback durante las fallas transitorias de menos de 10 minutos.

  Si tu app tiene una falla transitoria, como un problema con el almacenamiento en búfer debido a la actividad de la red, o hay una interrupción transitoria esperada, como AUDIOFOCUS_LOSS_TRANSIENT, la intención de reproducir debe continuar. Por lo tanto, tu FGS debe permanecer activo.

• Detén el servicio en primer plano al final de la reproducción y reiníciala solo si el usuario la reanuda de forma explícita.

  En el caso de una señal permanente para finalizar la reproducción (por ejemplo, el contenido se completa sin reproducción automática, un AUDIOFOCUS_LOSS, un evento de pausa del UMO o un evento de clave multimedia) o una falla irrecuperable, tu app debe detener la interacción de audio, detener el servicio en primer plano y finalizar la sesión multimedia. Todo esto corresponde a la concepción del usuario de "finalizar" la interacción de audio en segundo plano deseada. Después de hacerlo, tu app ya no tiene capacidades de interacción de audio en segundo plano.

  Posteriormente, si el usuario reanuda la reproducción de forma explícita, por ejemplo, a través de la IU de tu app o del botón de reproducción del objeto multimedia universal, debe volver la intención de iniciar la reproducción de audio, lo que genera un FGS recién iniciado.

• Prueba el comportamiento de reproducción de audio con comandos de adb shell.

Prueba los cambios

Para probar el cumplimiento de tu app en apps que ejecutan Android 17 o versiones posteriores (a partir de la versión Beta 3), ejecuta el siguiente comando de ADB:

adb shell cmd audio set-enable-hardening <enable|disable|throw>

Este comando tiene las siguientes opciones:

• enable: Habilita todas las restricciones de refuerzo de audio para todas las apps. El requisito de los servicios en primer plano de WIU se aplica independientemente de si una app se orienta a Android 17 (nivel de API 37). Además, el requisito se aplica incluso si la app realiza cambios en las transmisiones de alarma y tiene el permiso de alarma exacta.

• disable: Desactiva todas las restricciones de endurecimiento de audio.

• throw: Habilita todas las restricciones de refuerzo de audio para todas las apps, como enable. Además, esta marca habilita las fallas ruidosas y genera IllegalStateException para las interacciones de volumen y foco. Para la reproducción de audio, el método de escritura muestra de forma persistente un código de error. Para los modos de reproducción sin escrituras explícitas, la app falla.

Usa adb dumpsys audio o logcat para identificar si la app encontró fallas silenciosas debido a la aplicación del refuerzo de audio. Si lo hizo, habrá una entrada con el prefijo AudioHardening con el nombre del paquete. Si el mensaje contiene level: full, tu app ejecuta un servicio en primer plano, pero el servicio no tiene capacidad de uso mientras está en uso. Si el mensaje contiene level: partial, tu app no ejecuta ningún servicio en primer plano.

Información sobre el FGS con capacidad de uso mientras está en uso

Por lo general, los servicios en primer plano (FGS) se deben iniciar mientras una app está en primer plano para extender las operaciones iniciadas por el usuario. En algunos casos específicos, se permite que las apps inicien un servicio en primer plano mientras están en segundo plano. Sin embargo, por lo general, estos servicios en primer plano no tienen capacidades de uso mientras está en uso (WIU).

WIU actúa como una puerta de seguridad: evita que el FGS iniciado desde el segundo plano participe en ciertos comportamientos sensibles cuando el usuario podría no estar al tanto de la actividad de la app. Evita que la app acceda a datos sensibles, como la ubicación, la cámara o el micrófono, y, a partir de Android 17, también bloquea las APIs de audio que suelen requerir un contexto de IU visible.

Aquí tienes una referencia útil:

• FGS estándar: Los servicios que se inician mientras la app está visible o que tienen capacidad de inicio de actividad en segundo plano tienen acceso a WIU.
• FGS iniciado en segundo plano (BFSL): La mayoría no otorga acceso a WIU. Las excepciones principales que otorgan WIU son las interacciones que implican una intención explícita del usuario, por ejemplo, clics en notificaciones, interacciones con widgets o eventos de clave multimedia desde un dispositivo externo.
• FGS iniciado por el sistema: Los servicios en primer plano tienen acceso a WIU si se inician mediante la delegación del servidor del sistema (por ejemplo, desde la biblioteca de Jetpack Telecom) o mediante vinculaciones del sistema que representan un estado elevado en primer plano para realizar funciones dedicadas (como para un VoiceInteractionService.

Obtén más información en Restricciones para iniciar un servicio en primer plano desde el segundo plano.

Lista completa de las APIs de audio afectadas

Función de audio	Resultado	APIs afectadas
Reproducción de audio	Se silencia la reproducción. Ninguna excepción, ningún mensaje de falla proporcionado por ninguna API	AudioTrack.write() (NDK) AAudioStream_write OpenSL ES para Android También podrían verse afectadas las bibliotecas multimedia del cliente que administran la reproducción, como media3, Exoplayer y Oboe.
Solicitud de foco de audio	Muestra AUDIOFOCUS_REQUEST_FAILED. No afecta la reproducción de audio de otras apps, no se adquiere el foco.	AudioManager.requestAudioFocus()
APIs de modo de timbre y volumen	No afecta el modo de timbre ni el volumen (la llamada al método se ignora de forma silenciosa). Ninguna excepción, ningún mensaje de falla proporcionado por ninguna API	AudioManager.setStreamVolume() AudioManager.setStreamMute() AudioManager.adjustStreamVolume() AudioManager.adjustVolume() AudioManager.adjustSuggestedStreamVolume() AudioManager.setRingerMode()