Proteção de áudio em segundo plano

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

Todos os apps em execução no Android 17 que têm essas interações de áudio em segundo plano precisam ter uma atividade visível ou executar um serviço em primeiro plano que não seja do tipo SHORT_SERVICE. Isso se aplica se o app é destinado ao nível 37 da API ou não.

Se um app for destinado ao Android 17 (nível 37 da API), haverá uma restrição adicional. Se o app estiver em execução em segundo plano, ele precisará executar um serviço em primeiro plano que tenha recursos de uso durante o uso (WIU, na sigla em inglês). Um serviço em primeiro plano recebe recursos de WIU se for iniciado em resposta a uma operação iniciada pelo usuário ou enquanto o app estiver visível para o usuário. No entanto, o requisito de recursos de WIU é dispensado se o app tiver recebido a permissão de alarme exata e estiver fazendo mudanças em fluxos de áudio que tenham o USAGE_ALARM atributo.

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 de mudança de volume falharão silenciosamente, sem gerar uma exceção ou fornecer uma mensagem de falha. A API de seleção de áudio falha com o código de resultado AUDIOFOCUS_REQUEST_FAILED.

Por que estamos fazendo a mudança

A intenção de introduzir essas restrições é reduzir experiências com bugs de áudio em segundo plano não intencionais. Veja alguns exemplos:

• Os apps que reproduzem áudio sem um serviço em primeiro plano podem ser congelados. Quando o app é descongelado, ele retoma a reprodução de áudio inesperadamente, possivelmente horas depois.
• Os apps que reproduzem áudio sem um serviço em primeiro plano enfrentam restrições de execução variadas que resultam em desempenho de áudio instável.
• A reprodução desvinculada do ciclo de vida da atividade pode resultar em uma sessão de reprodução vazada ou eventos de seleção vazados que continuam sem que o usuário possa interromper a reprodução.

Incentivamos os desenvolvedores a testar os apps e enviar 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 pretende apenas reproduzir á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 oferece funcionalidade VOIP, incluindo apps de videochamadas, ele já precisa atender aos requisitos introduzidos para reprodução (normalmente usando as APIs de telecomunicações recomendadas) para gravar áudio com sucesso e, portanto, é improvável que seja afetado.

Se o app pretende continuar a reprodução de áudio enquanto a tela está desligada ou enquanto a Activity não está visível, o que é mais comum em apps de streaming de música ou podcasts, ele é considerado como fornecedor de 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 o app estava aberto ou em resposta a um acionador 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 o áudio, ele será suprimido.

Práticas recomendadas de áudio em segundo plano para mitigar o impacto

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

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

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

  Por exemplo, se o app for um app de streaming de vídeo que normalmente é apenas em primeiro plano, mas contém uma affordance do usuário para continuar a reprodução enquanto a tela está desligada, quando o acionador 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 SPP mediaPlayback 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 se houver uma interrupção temporária esperada, como AUDIOFOCUS_LOSS_TRANSIENT, a intenção de reproduzir precisará continuar. Assim, o SPP precisará permanecer ativo.

• Interrompa o serviço em primeiro plano no final da reprodução e reinicie a reprodução somente 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á concluído 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 precisará 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.

  Posteriormente, 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 intent de iniciar a reprodução de áudio precisará retornar, resultando em um SPP recém-iniciado.

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

Teste de alterações

É possível testar a conformidade do app em apps que executam o Android 17 ou mais recente (a partir do Beta 3) executando o seguinte comando ADB:

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

Esse comando tem as seguintes opções:

• enable: ativa todas as restrições de reforço de áudio para todos os apps. O requisito de serviços em primeiro plano de WIU é aplicado se um app é destinado ao Android 17 (nível 37 da API) ou não. Além disso, o requisito é aplicado mesmo que o app esteja fazendo mudanças nos fluxos de alarme e tenha a permissão de alarme exata.

• disable: desativa todas as restrições de reforço de áudio.

• throw: ativa todas as restrições de reforço de áudio para todos os apps, como enable. Além disso, essa flag ativa falhas altas, gerando IllegalStateException para interações de volume e seleção. Para reprodução de áudio, o método de gravação retorna um código de erro de forma persistente. Para modos de reprodução sem gravações explícitas, o app falha.

Use adb dumpsys audio ou logcat para identificar se o app encontrou falhas silenciosas devido à aplicação do reforço de áudio. Se isso acontecer, haverá uma entrada com o prefixo AudioHardening e o nome do pacote. Se a mensagem contiver level: full, o app estará executando um serviço em primeiro plano, mas o serviço não terá capacidade de uso durante o uso. Se a mensagem contiver level: partial, o app não estará executando um serviço em primeiro plano.

Entender o SPP com capacidade de uso durante o uso

Geralmente, os serviços em primeiro plano (SPP) 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 o app está 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 atua 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 está ciente da atividade do app. Ele impede que o app acesse dados sensíveis, como localização, câmera ou microfone, e, a partir do Android 17, 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 inicialização de atividade em segundo plano recebem acesso ao WIU.
• SPP iniciado em segundo plano (BFSL, na sigla em inglês): a maioria não concede acesso ao WIU. As principais exceções que concedem WIU são interações que envolvem a intenção explícita do usuário, por exemplo, cliques em notificações, interações de widgets ou eventos de tecla de mídia de um dispositivo externo.
• SPP iniciado pelo sistema: os serviços em primeiro plano recebem acesso ao WIU se forem iniciados pela delegação do servidor do sistema (por exemplo, da biblioteca Telecom do Jetpack ou por vinculações do sistema que representam um estado de primeiro plano elevado para executar funcionalidades dedicadas (como para um VoiceInteractionService).

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

Lista completa de APIs de áudio afetadas