A API AudioPlaybackCapture foi introduzida em Android 10. Com essa API, é possível copiar o áudio que está sendo reproduzido por outros aplicativos. Esse recurso é o análogo da captura de tela, mas para o áudio. O caso de uso principal ocorre em aplicativos de streaming que querem capturar o áudio reproduzido por jogos.
Observe que a API de captura não afeta a latência do aplicativo que reproduz o áudio.
Como criar um aplicativo de captura
Pré-requisitos
Por segurança e privacidade, a captura de reprodução impõe algumas limitações. Para capturar um áudio, o aplicativo precisa atender a estes requisitos:
- O aplicativo precisa ter a permissão
RECORD_AUDIO. - O aplicativo precisa exibir um aviso de
MediaProjectionManager.createScreenCaptureIntent()para que o usuário possa aprová-lo. - Os aplicativos de captura e reprodução precisam estar no mesmo perfil de usuário.
Como capturar áudio
Para capturar o áudio de outro aplicativo, você precisará criar um objeto AudioRecord e adicionar um AudioPlaybackCaptureConfiguration ao seu aplicativo. Faça o seguinte:
- Chame
AudioPlaybackCaptureConfiguration.Builder.build()para criar umAudioPlaybackCaptureConfiguration. - Transmita a configuração para
AudioRecordchamandosetAudioPlaybackCaptureConfig.
Como restringir a captura por conteúdo de áudio
Um aplicativo pode limitar a captura de áudio usando estes métodos:
- Transmita um
AUDIO_USAGEpara AudioPlaybackCaptureConfiguration.addMatchingUsage(), se quiser permitir a captura de um uso específico. Chame o método várias vezes para especificar mais de um uso. - Transmita um
AUDIO_USAGEpara AudioPlaybackCaptureConfiguration.excludeUsage(), se quiser impedir a captura desse uso. Chame o método várias vezes para especificar mais de um uso. - Transmita um UID para AudioPlaybackCaptureConfiguration.addMatchingUid(), se quiser capturar somente aplicativos com um UID específico. Chame o método várias vezes para especificar mais de um UID.
- Transmita um UID para AudioPlaybackCaptureConfiguration.excludeUid(), se quiser impedir a captura desse UID. Chame o método várias vezes para especificar mais de um UID.
Não é possível usar os métodos addMatchingUsage() e excludeUsage() juntos. É preciso escolher uma dessas opções. Da mesma forma, não é possível usar addMatchingUid() e excludeUid() ao mesmo tempo.
Como permitir a captura de reprodução
Você pode configurar um aplicativo para impedir que outros aplicativos capturem o áudio dele. O áudio só poderá ser capturado se o aplicativo atender a estes requisitos:
Uso
O player que reproduz o áudio precisa definir o tipo de uso para USAGE_MEDIA, USAGE_GAME ou USAGE_UNKNOWN.
Política de captura
A política de captura do player precisa ser AudioAttributes.ALLOW_CAPTURE_BY_ALL, que permite a outros aplicativos capturar uma reprodução. Isso pode ser feito de várias maneiras:
- Para ativar a captura em todos os players, inclua
android:allowAudioPlaybackCapture="true"no arquivo demanifest.xmldo aplicativo. - Você também pode permitir a captura em todos os players chamando
AudioManager.setAllowedCapturePolicy(AudioAttributes.ALLOW_CAPTURE_BY_ALL). - Você pode definir a política em um player individual ao criá-la com
AudioAttributes.Builder.setAllowedCapturePolicy(AudioAttributes.ALLOW_CAPTURE_BY_ALL). Se você estiver usandoAAudio, chameAAudioStreamBuilder_setAllowedCapturePolicy(AAUDIO_ALLOW_CAPTURE_BY_ALL).
Se esses pré-requisitos forem atendidos, qualquer áudio produzido pelo player poderá ser capturado.
Como desativar a captura do sistema
As proteções que permitem a captura descrita acima se aplicam somente a aplicativos. Os componentes do sistema Android podem capturar a reprodução por padrão. Muitos desses componentes são personalizados por fornecedores do Android e são compatíveis com recursos como acessibilidade e legenda. Por esse motivo, é recomendável que os aplicativos permitam ao sistema capturar a própria reprodução. Nos casos raros em que você não quer que o sistema capture a reprodução do aplicativo, defina a política de captura como ALLOW_CAPTURE_BY_NONE.
Como configurar o tempo de execução da política
Chame AudioManager.setAllowedCapturePolicy() para alterar a política de captura enquanto um aplicativo está em execução. Se um MediaPlayer ou AudioTrack estiver sendo reproduzido quando você chamar o método, o áudio não será afetado. Feche e reabra o player ou a faixa para que a alteração na política entre em vigor.
Política = manifesto + AudioManager + AudioAttributes
Como a política de captura pode ser especificada em vários locais, é importante entender qual delas entrará em vigor. A política de captura mais restritiva é sempre aplicada. Por exemplo, um aplicativo com um manifesto que inclui setAllowedCapturePolicy="false" nunca permitirá que aplicativos não pertencentes ao sistema capturem o áudio dele, mesmo que AudioManager#setAllowedCapturePolicy esteja definido como ALLOW_CAPTURE_BY_ALL. Da mesma forma, se AudioManager#setAllowedCapturePolicy estiver definido como ALLOW_CAPTURE_BY_ALL e o manifesto for setAllowedCapturePolicy="true", mas os AudioAttributes do player de mídia tiverem sido criados com AudioAttributes.Builder#setAllowedCapturePolicy(ALLOW_CAPTURE_BY_SYSTEM), esse player de mídia não poderá ser capturado por aplicativos que não sejam do sistema.
A tabela abaixo resume o efeito do atributo manifest e a política efetiva:
| allowAudioPlaybackCapture | ALLOW_CAPTURE_BY_ALL | ALLOW_CAPTURE_BY_SYSTEM | ALLOW_CAPTURE_BY_NONE |
|---|---|---|---|
| verdadeiro | qualquer aplicativo | somente do sistema | sem captura |
| falso | somente do sistema | somente do sistema | sem captura |