Proteção de áudio em segundo plano

A partir do Android 17, o framework de áudio impõe restrições às interações de áudio em segundo plano, incluindo reprodução de áudio, solicitações de foco de áudio e APIs de mudança de volume para garantir que essas mudanças sejam iniciadas intencionalmente pelo usuário.

Se um desenvolvedor de apps quiser controlar o áudio sem uma atividade visível, ele precisa garantir que o app tenha um serviço em primeiro plano (que não seja do tipo SHORT_SERVICE) iniciado com recursos em uso (WIU, na sigla em inglês). Um serviço em primeiro plano recebe recursos de WIU se for iniciado em resposta a um MediaSessionEvent ou enquanto o app estiver visível para o usuário.

Se o app tentar chamar APIs de áudio enquanto não estiver em um ciclo de vida válido, as APIs de reprodução de áudio e mudança de volume falharão silenciosamente sem gerar uma exceção ou fornecer uma mensagem de falha. A API de foco de áudio falha com o código de resultado AUDIOFOCUS_REQUEST_FAILED.

O objetivo dessas restrições é reduzir experiências com bugs de áudio em segundo plano não intencionais. Veja alguns exemplos:

• Os apps que tocam áudio sem um serviço em primeiro plano podem ser congelados. Quando o app é descongelado, ele retoma a reprodução de áudio de forma inesperada, possivelmente horas depois.
• Os apps que reproduzem áudio sem um serviço em primeiro plano enfrentam várias restrições de execução, o que resulta em um desempenho de áudio instável.
• A reprodução foi separada do ciclo de vida da atividade, o que pode resultar em uma sessão de reprodução ou eventos de foco vazados que continuam sem que o usuário possa interromper a reprodução.

Recomendamos que os desenvolvedores testem os apps e enviem feedback sobre a mudança de comportamento se houver casos de uso de áudio intencionais afetados negativamente. Informe qualquer problema usando este rastreador de problemas de compatibilidade de apps do Android 17.

Identificar casos de uso de áudio em segundo plano afetados

Audite a implementação da reprodução de áudio e identifique se o app pretende fornecer funcionalidade de interação de áudio em segundo plano mesmo em circunstâncias condicionais.

Se o app só pretende tocar áudio ou usar APIs de áudio enquanto mostra uma atividade visível para o usuário, incluindo o uso do modo picture-in-picture (PiP), ele não será afetado por nenhuma dessas mudanças.

Se o app oferecer funcionalidade de VOIP, incluindo apps de videochamada, ele já precisa atender aos requisitos de reprodução (normalmente usando as APIs de telecomunicações recomendadas) para gravar áudio. Portanto, é improvável que ele seja afetado.

Se o app pretende continuar a reprodução de áudio com a tela desligada ou enquanto o usuário dispensou totalmente a atividade, o que é mais comum em apps de streaming de música ou de podcasts, ele é considerado como oferecendo funcionalidade de áudio em segundo plano e precisa atender aos novos requisitos.

Cenários de áudio em segundo plano que provavelmente serão afetados

Se o app não seguir o modelo de continuar uma interação de áudio iniciada enquanto ele estava aberto ou em resposta a um gatilho explícito do usuário, é provável que a funcionalidade do app seja suprimida silenciosamente.

Por exemplo, se o app iniciar um serviço em primeiro plano em resposta a BOOT_COMPLETE e tentar interagir com áudio, ele será suprimido.

Práticas recomendadas para reduzir o impacto do áudio em segundo plano

• Use o componente MediaSessionService da biblioteca jetpack media3 para gerenciar a reprodução de áudio em segundo plano.

  Se você fizer isso, é provável que o app não seja afetado pelo reforço em segundo plano, já que a biblioteca ajuda a gerenciar o ciclo de vida da reprodução.

• Se você não estiver usando a biblioteca media3, será necessário iniciar manualmente um FGS mediaPlayback. Sempre inicie um serviço em primeiro plano enquanto o app estiver em primeiro plano se áudio em segundo plano puder ocorrer.

  Por exemplo, se o app for de streaming de vídeo, que normalmente é apenas em primeiro plano, mas tiver um recurso para o usuário continuar a reprodução com a tela desligada, quando o gatilho de reprodução iniciado pelo usuário ocorrer, o app ainda precisará iniciar um serviço em primeiro plano.

  Isso garante que o serviço em primeiro plano seja iniciado com recursos de WIU.

• Mantenha o mediaPlayback FGS ativo durante falhas temporárias de menos de 10 minutos.

  Se o app tiver uma falha temporária, como um problema com o buffer devido à atividade de rede, ou houver uma interrupção temporária esperada, como AUDIOFOCUS_LOSS_TRANSIENT, a intenção de reproduzir deve continuar. Portanto, seu FGS precisa permanecer ativo.

• Pare o serviço em primeiro plano no final da reprodução e reinicie apenas se o usuário retomar explicitamente a reprodução.

  No caso de um sinal permanente para encerrar a reprodução (por exemplo, o conteúdo está completo sem reprodução automática, um AUDIOFOCUS_LOSS, um evento de pausa do UMO ou um evento de tecla de mídia) ou uma falha irrecuperável, o app deve interromper a interação de áudio, parar o serviço em primeiro plano e encerrar a sessão de mídia. Fazer tudo isso corresponde à concepção do usuário de "concluir" a interação de áudio em segundo plano desejada. Depois disso, o app não terá mais recursos de interação de áudio em segundo plano.

  Depois, se o usuário retomar explicitamente a reprodução, por exemplo, pela interface do app ou pelo botão de reprodução do objeto de mídia universal, a intenção de iniciar a reprodução de áudio vai retornar, resultando em um novo FGS.

• Teste o comportamento de reprodução de áudio com comandos adb shell.

Testar mudanças no Android 16 e no Android 17

O recurso já está implementado no nível "aviso" do Android 16 em diante. Isso significa que os apps podem usar a adb shell cmd audio set-enable-hardening para testar manualmente a aplicação do reforço de áudio em segundo plano.

Para ativar a aplicação em dispositivos com Android 16, execute o seguinte comando:

adb shell cmd audio set-enable-hardening 1

Para desativar a aplicação em dispositivos com Android 17, execute o seguinte comando:

adb shell cmd audio set-enable-hardening 0

Também recomendamos usar logcat ou o comando adb adb dumpsys audio para identificar se o app encontrou falhas silenciosas devido à aplicação do reforço de áudio. Se isso acontecer, o registro terá uma entrada com o prefixo AudioHardening e o nome do seu pacote.

Entender o FGS com capacidade de uso durante o uso

Em geral, os serviços em primeiro plano (FGS, na sigla em inglês) precisam ser iniciados enquanto um app está em primeiro plano para estender as operações iniciadas pelo usuário. Em alguns casos específicos, os apps podem iniciar um serviço em primeiro plano enquanto estão em segundo plano. No entanto, esses serviços em primeiro plano geralmente não recebem recursos de uso durante o uso (WIU, na sigla em inglês).

O WIU funciona como um portão de segurança. Ele impede que o SPP iniciado em segundo plano se envolva em determinados comportamentos sensíveis quando o usuário não tem conhecimento da atividade do app. Ele impede que o app acesse dados sensíveis, como localização, câmera ou microfone. Além disso, a partir do Android 17, ele também bloqueia APIs de áudio que normalmente exigem um contexto de interface visível.

Confira uma referência útil:

• SPP padrão: os serviços iniciados enquanto o app está visível ou com capacidade de iniciar atividades em segundo plano recebem acesso ao WIU.
• FGS iniciado em segundo plano (BFSL): a maioria não concede acesso ao WIU. As exceções principais que concedem o WIU são interações que envolvem a intenção explícita do usuário, por exemplo, cliques em notificações, interações com widgets ou eventos de teclas de mídia de um dispositivo externo.
• O sistema iniciou o FGS: o FGS começou a usar a delegação do system-server (por exemplo, usando a biblioteca Telecom jetpack) e recebeu acesso ao WIU.

Leia mais em Restrições para iniciar um serviço em primeiro plano do segundo plano.

Lista completa das APIs de áudio afetadas