Playback capture

The AudioPlaybackCapture API was introduced in Android 10. This API gives apps the ability to copy the audio being played by other apps. This feature is the analog of screen capture, but for audio. The primary use case is for streaming apps that want to capture the audio being played by games.

Note that the capture API does not affect the latency of the app whose audio is being captured.

Building a capture app

Prerequisites

For security and privacy, playback capture imposes some limitations. To be able to capture audio, an app must meet these requirements:

Capturing audio

To capture audio from another app, your app must build an AudioRecord object and add an AudioPlaybackCaptureConfiguration to it. Follow these steps:

  1. Call AudioPlaybackCaptureConfiguration.Builder.build() to build an AudioPlaybackCaptureConfiguration.
  2. Pass the configuration to the AudioRecord by calling setAudioPlaybackCaptureConfig.

Constraining capture by audio content

An app can limit which audio it can capture by using these methods:

Note that you cannot use the addMatchingUsage() and excludeUsage() methods together. You must choose one or the other. Likewise, you cannot use addMatchingUid() and excludeUid() at the same time.

Allowing playback capture

You can configure an app to prevent other apps from capturing its audio. The audio coming from an app can be captured only if the app meets these requirements:

Usage

The player producing the audio must set its usage to USAGE_MEDIA, USAGE_GAME, or USAGE_UNKNOWN.

Capture policy

The player's capture policy must be AudioAttributes.ALLOW_CAPTURE_BY_ALL, which allows other apps to capture playback. This can be done in a number of ways:

If these prerequisites are met, any audio produced by the player can be captured.

Disabling system capture

The protections permitting capture described above apply only to apps. Android system components can capture playback by default. Many of these components are customized by Android vendors and support features like accessibility and captioning. For this reason it is recommended that apps allow the system to capture their playback. In the rare case when you do not want the system to capture your app's playback, set the capture policy to ALLOW_CAPTURE_BY_NONE.

Setting policy at runtime

You can call AudioManager.setAllowedCapturePolicy() to change the capture policy while an app is running. If a MediaPlayer or AudioTrack is playing when you call the method, the audio is not affected. You must close and reopen the player or track for the policy change to take effect.

Policy = manifest + AudioManager + AudioAttributes

Since the capture policy can be specified in several places, it's important to understand how the effective policy is determined. The most restrictive capture policy is always applied. For example, an app whose manifest includes setAllowedCapturePolicy="false" will never permit non-system apps to capture its audio, even if AudioManager#setAllowedCapturePolicy is set to ALLOW_CAPTURE_BY_ALL. Similarly, if the AudioManager#setAllowedCapturePolicy is set to ALLOW_CAPTURE_BY_ALL and the manifest sets setAllowedCapturePolicy="true", but the media player's AudioAttributes were built with AudioAttributes.Builder#setAllowedCapturePolicy(ALLOW_CAPTURE_BY_SYSTEM), then this media player will not be capturable by non-system apps.

The table below summarizes the effect of the manifest attribute and the effective policy:

allowAudioPlaybackCapture ALLOW_CAPTURE_BY_ALL ALLOW_CAPTURE_BY_SYSTEM ALLOW_CAPTURE_BY_NONE
true any app system only no capture
false system only system only no capture