This post was originally published at Capturing Audio in Android Q

image

Posted by Don Turner, Developer Advocate for Android Media

image

In Android Q there’s a new API which allows applications to capture the audio of other applications. It’s called the AudioPlaybackCapture API and it enables some important use cases for easier content sharing and accessibility.

Some examples include:

  • Live captioning – allowing the audio content of the currently playing app to be captioned or translated in real time. In fact, the Live Caption feature shown at I/O this year is a client of this API. Live captioning allows your users to engage with audible content even when it’s impossible or inconvenient to do so, such as listening in a public place without headphones.
  • Game recording and streaming – In-game sounds can be recorded and streamed to live audiences, helping to increase the social reach of game content.

There may be some situations where a developer wishes to disallow the capture of their app’s audio. This article explains how audio capture works for users and how developers can disallow their app’s audio from being captured if they need to.

What does the user see?

In order to capture the audio of other apps the user must grant the record audio permission to the app doing the capturing.

AUDIO_RECORD permissions dialog

AUDIO_RECORD permissions dialog

Additionally, before a capture session can be started the capturing app must call MediaProjectionManager.createScreenCaptureIntent(). This will display the following dialog to the user:

screen capture intent dialog

Screen capture intent dialog

The user must tap “Start now” in order for a capturing session to be started. This will allow both video and audio to be captured.

cast icon showing red in status bar

Cast icon showing red in status bar

During a capture session the cast icon is shown in red in the status bar.

Can my app’s audio be captured?

Whether your app’s audio can be captured by default depends on your target API. Here’s a table which summarizes the default behaviour:

Target API Third party apps can capture your app’s audio by default? System apps and components can capture your app’s audio by default?
28 and below No, the app needs to explicitly opt-in Yes for audio with usage type MEDIA, GAME and UNKNOWN
29 Yes for audio with usage type MEDIA, GAME and UNKNOWN Yes for audio with usage type MEDIA, GAME and UNKNOWN

Disallowing capture by third party apps

There may be situations where an app wishes to disallow its audio from being captured by other apps. This could be because the audio contains:

  • sensitive information – such as private voice recordings.
  • copyrighted material – such as copyrighted music or audio from movies and TV shows.

An app’s audio capturing policy can be set either for all audio or for each individual audio player.

Disallowing capture of all audio by third party apps

To disallow capture of all audio by third party apps you can do either of the following:

Add the following to your AndroidManifest.xml <application

...

android:allowAudioPlaybackCapture="false"/>

Programmatically disable capture by running the following code prior to playing audio AudioManager.setAllowedCapturePolicy(ALLOW_CAPTURE_BY_SYSTEM)

Disallowing capture on a per player basis by third party apps

To disallow capture for an individual player you can set the capture policy for the audio player when it is built by calling:

AudioAttributes.Builder.setAllowedCapturePolicy(ALLOW_CAPTURE_BY_SYSTEM)

This approach may be useful if your app plays content with differing licenses. For example, both copyrighted and royalty-free content.

Disallowing capture by system apps and components

By default system apps and components are allowed to capture an app’s audio if its usage is MEDIA, GAME and UNKNOWN, as this enables important accessibility use cases, such as live captioning.

In rare cases where a developer wishes to disallow audio capture for system apps as well they can do so in a similar way to the approach for third party apps. Note that this will also disallow capture by third party apps.

Disallowing capture of all audio

This can only be done programmatically by running the following code before any audio is played:

AudioManager.setAllowedCapturePolicy(ALLOW_CAPTURE_BY_NONE)

Disallowing capture on a per player basis

To disallow capture for an individual player you can set the capture policy for the audio player when it is built:

AudioAttributes.Builder.setAllowedCapturePolicy(ALLOW_CAPTURE_BY_NONE)

What next?

If your app is targeting API 28 or below and you would like to enable audio capture add android:allowAudioPlaybackCapture="true" to your app’s manifest.xml.

If you would like to disallow some or all of your audio from being captured then update your app according to the instructions above.

For more information check out the Audio Playback Capture API documentation.

image image

Link:

This post was originally published at Capturing Audio in Android Q