Proteção de áudio em segundo plano

A partir do Android 17, o framework de áudio aplica restrições a 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.

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

Se um app for direcionado ao Android 17 (nível 37 da API), haverá uma restrição adicional. Se o app estiver em segundo plano, ele precisará estar executando um serviço em primeiro plano com recursos enquanto em 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 exato e estiver fazendo mudanças em streams de áudio que tenham o atributo USAGE_ALARM.

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 vão falhar 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.

Por que estamos fazendo essa mudança?

A intenção de introduzir essas restrições é reduzir as experiências de áudio em segundo plano com bugs 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 inesperadamente a reprodução de áudio, possivelmente horas depois.
• Os apps que reproduzem áudio sem um serviço em primeiro plano enfrentavam várias restrições de execução, o que resultava 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 vazada ou em 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 Issue Tracker 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 oferecer uma funcionalidade de interação de áudio em segundo plano, mesmo em circunstâncias condicionais.

Se o app só pretende 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 de VOIP, incluindo apps de videochamada, ele já precisa atender aos requisitos que estão sendo introduzidos para reprodução (normalmente usando as APIs de telecomunicações recomendadas) para gravar áudio corretamente. Portanto, é improvável que ele seja afetado.

Se o app pretende continuar a reprodução de áudio enquanto a tela está desligada ou enquanto a atividade não está visível, o que é mais comum em apps de streaming de música ou de podcast, ele é considerado como um app que oferece 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 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 reduzir 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, é provável que seu app não seja afetado pelo aumento da segurança 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, vai precisar iniciar manualmente um FGS mediaPlayback. Sempre inicie um serviço em primeiro plano enquanto o app estiver em primeiro plano se houver a possibilidade de áudio em segundo plano.

  Por exemplo, se o app for de streaming de vídeo, que normalmente é apenas em primeiro plano, mas contém uma funcionalidade 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 FGS mediaPlayback ativo durante falhas temporárias de menos de 10 minutos.

  Se o app tiver uma falha temporária, como um problema de armazenamento em buffer devido à atividade da rede, ou se houver uma interrupção temporária esperada, como AUDIOFOCUS_LOSS_TRANSIENT, a intent de reprodução precisa continuar. Portanto, o FGS precisa permanecer ativo.

• Interrompa o serviço em primeiro plano ao final da reprodução e só a reinicie se o usuário fizer isso explicitamente.

  No caso de um sinal permanente para encerrar a reprodução (por exemplo, o conteúdo foi 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 precisa interromper a interação de áudio, 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 de fazer isso, 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 para iniciar a reprodução de áudio será retornada, resultando em um FGS recém-iniciado.

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

Teste de alterações

Para testar a conformidade do app em dispositivos com o Android 17 ou versões mais recentes (começando com a versão Beta 3), execute o seguinte comando do 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 aumento de segurança de áudio para todos os apps. O requisito para 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 streams de alarme e tenha a permissão de alarme exato.

• disable: desativa todas as restrições de aumento de segurança de áudio.

• throw: ativa todas as restrições de proteção de áudio para todos os apps, como enable. Além disso, essa flag ativa falhas ruidosas, gerando IllegalStateException para interações de volume e foco. Para reprodução de áudio, o método de gravação retorna um código do 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 da proteção de áudio. Se isso acontecer, haverá uma entrada com o prefixo AudioHardening com o nome do pacote. Se a mensagem tiver level: full, o app está executando um serviço em primeiro plano, mas o serviço não tem o recurso "enquanto em uso". Se a mensagem contiver level: partial, seu app não está executando um serviço em primeiro plano.

Noções básicas sobre FGS com recurso "enquanto em 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 enquanto em uso (WIU, na sigla em inglês).

O WIU atua como um portão de segurança, impedindo que os SPPs iniciados em segundo plano se envolvam em determinados comportamentos sensíveis quando o usuário pode não estar 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:

• FGS padrão: os serviços iniciados enquanto o app está visível ou recebe permissão para iniciar atividades em segundo plano recebem acesso WIU.
• FGS iniciado em segundo plano (BFSL): a maioria não concede acesso ao WIU. As exceções principais 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 com widgets ou eventos de teclas de mídia de um dispositivo externo.
• FGS iniciado pelo sistema: os serviços em primeiro plano recebem acesso de WIU se forem iniciados pela delegação do servidor do sistema (por exemplo, da biblioteca Jetpack Telecom) ou por vinculações do sistema que representam um estado em primeiro plano elevado para executar uma funcionalidade dedicada (como para um VoiceInteractionService).

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

Lista completa de APIs de áudio afetadas