From 654b3cb1c739c275702fd9043c5b546f8fd5d680 Mon Sep 17 00:00:00 2001
From: Kevin Rocard <krocard@google.com>
Date: Wed, 3 Apr 2019 16:51:11 -0700
Subject: [PATCH] Add documentation for the APC feature

Test: m offline-sdk-docs
Bug: 111453086
Bug: 128454790
Change-Id: Ibeef672b1e3090bb83304cce4b58f0ffab7a9cdc
Signed-off-by: Kevin Rocard <krocard@google.com>
---
 core/res/res/values/attrs_manifest.xml        | 15 ++++++++++---
 media/java/android/media/AudioAttributes.java | 13 ++++++++---
 media/java/android/media/AudioManager.java    | 15 ++++++++++---
 .../AudioPlaybackCaptureConfiguration.java    | 22 ++++++++++++-------
 4 files changed, 48 insertions(+), 17 deletions(-)

diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index 47c243ca1e041..aec9e60c7424f 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -1684,18 +1684,27 @@
              This flag is turned on by default. <em>This attribute is usable only by system apps.
              </em> -->
         <attr name="allowClearUserDataOnFailedRestore"/>
-        <!-- If {@code true} the app's non sensitive audio can be capture by other apps with
-             {@code AudioPlaybackCaptureConfiguration} and a {@code MediaProjection}.
+        <!-- If {@code true} the app's non sensitive audio can be captured by other apps with
+             {@link android.media.AudioPlaybackCaptureConfiguration} and a
+             {@link android.media.projection.MediaProjection}.
+
+             If {@code false} the audio played by the application will never be captured by non
+             system apps. It is equivalent to limiting
+             {@link android.media.AudioManager#setAllowedCapturePolicy(int)} to
+             {@link android.media.AudioAttributes#ALLOW_CAPTURE_BY_SYSTEM}.
 
              <p>
              Non sensitive audio is defined as audio whose {@code AttributeUsage} is
              {@code USAGE_UNKNOWN}), {@code USAGE_MEDIA}) or {@code USAGE_GAME}).
-             All other usages (eg. {@code USAGE_VOICE_COMMUNICATION}) will not be captured.
+             All other usages like {@code USAGE_VOICE_COMMUNICATION} will not be captured.
 
              <p>
              The default value is:
                  - {@code true} for apps with targetSdkVersion >= 29 (Q).
                  - {@code false} for apps with targetSdkVersion < 29.
+
+             <p>
+             See {@link android.media.AudioPlaybackCaptureConfiguration} for more detail.
              -->
         <attr name="allowAudioPlaybackCapture" format="boolean" />
         <!-- If {@code true} this app allows shared/external storage media to be
diff --git a/media/java/android/media/AudioAttributes.java b/media/java/android/media/AudioAttributes.java
index 9d4bce7b43010..89b09dc65872d 100644
--- a/media/java/android/media/AudioAttributes.java
+++ b/media/java/android/media/AudioAttributes.java
@@ -696,12 +696,19 @@ public final class AudioAttributes implements Parcelable {
         }
 
         /**
-         * Specifying if audio may or may not be captured by other apps or the system.
+         * Specifies weather the audio may or may not be captured by other apps or the system.
          *
          * The default is {@link AudioAttributes#ALLOW_CAPTURE_BY_ALL}.
          *
-         * Note that an application can also set its global policy, in which case the most
-         * restrictive policy is always applied.
+         * There are multiple ways to set this policy:
+         *  - for each tracks independently, with this method
+         *  - application wide at runtime, with {@link AudioManager#setAllowedCapturePolicy(int)}
+         *  - application wide at build time, see {@code allowAudioPlaybackCapture} in the
+         *    application manifest.
+         * The most restrictive policy is always applied.
+         *
+         * See {@link AudioPlaybackCaptureConfiguration} for more details on the restrictions
+         * which audio signals can be captured.
          *
          * @param capturePolicy one of
          *     {@link #ALLOW_CAPTURE_BY_ALL},
diff --git a/media/java/android/media/AudioManager.java b/media/java/android/media/AudioManager.java
index dc5c6639375b7..8a2a606699697 100644
--- a/media/java/android/media/AudioManager.java
+++ b/media/java/android/media/AudioManager.java
@@ -1479,12 +1479,21 @@ public class AudioManager {
      }
 
     /**
-     * Specifying if this audio may or may not be captured by other apps or the system.
+     * Specifies wheather the audio played by this app may or may not be captured by other apps or
+     * the system.
      *
      * The default is {@link AudioAttributes#ALLOW_CAPTURE_BY_ALL}.
      *
-     * Note that each audio track can also set its policy, in which case the most
-     * restrictive policy is always applied.
+     * There are multiple ways to set this policy:
+     *  - for each tracks independently, see
+     *    {@link AudioAttributes.Builder#setAllowedCapturePolicy(int)}
+     *  - application wide at runtime, with this method
+     *  - application wide at build time, see {@code allowAudioPlaybackCapture} in the application
+     *  manifest.
+     * The most restrictive policy is always applied.
+     *
+     * See {@link AudioPlaybackCaptureConfiguration} for more details on the restrictions
+     * which audio signals can be captured.
      *
      * @param capturePolicy one of
      *     {@link AudioAttributes#ALLOW_CAPTURE_BY_ALL},
diff --git a/media/java/android/media/AudioPlaybackCaptureConfiguration.java b/media/java/android/media/AudioPlaybackCaptureConfiguration.java
index bcaef032093de..d61f14c25c7e6 100644
--- a/media/java/android/media/AudioPlaybackCaptureConfiguration.java
+++ b/media/java/android/media/AudioPlaybackCaptureConfiguration.java
@@ -28,18 +28,24 @@ import com.android.internal.util.Preconditions;
 /**
  * Configuration for capturing audio played by other apps.
  *
- * Only the following audio can be captured:
- *  - usage MUST be {@link AudioAttributes#USAGE_UNKNOWN} or {@link AudioAttributes#USAGE_GAME}
+ *  When capturing audio signals played by other apps (and yours),
+ *  you will only capture a mix of the audio signals played by players
+ *  (such as AudioTrack or MediaPlayer) which present the following characteristics:
+ *  - the usage value MUST be {@link AudioAttributes#USAGE_UNKNOWN} or
+ *    {@link AudioAttributes#USAGE_GAME}
  *    or {@link AudioAttributes#USAGE_MEDIA}. All other usages CAN NOT be captured.
- *  - audio attributes MUST have its ${@link AudioAttributes.Builder#setAllowedCapturePolicy}
- *    to {@link AudioAttributes#ALLOW_CAPTURE_BY_ALL}.
- *  - played by apps that MUST be in the same user profile as the capturing app
- *    (eg work profile can not capture user profile apps and vice-versa).
- *  - played by apps for which the attribute allowAudioPlaybackCapture in their manifest
+ *  - AND the capture policy set by their app (with ${@link AudioManager#setAllowedCapturePolicy})
+ *    or on each player (with ${@link AudioAttributes.Builder#setAllowedCapturePolicy}) is
+ *    {@link AudioAttributes#ALLOW_CAPTURE_BY_ALL}, whichever is the most strict.
+ *  - AND their app attribute allowAudioPlaybackCapture in their manifest
  *    MUST either be:
  *      * set to "true"
- *      * not set, and their targetSdkVersion MUST be equal or higher to
+ *      * not set, and their {@code targetSdkVersion} MUST be equal or higher to
  *        {@link android.os.Build.VERSION_CODES#Q}.
+ *        Ie. Apps that do not target at least Android Q must explicitly opt-in to be captured by a
+ *            MediaProjection.
+ *  - AND their apps MUST be in the same user profile as your app
+ *    (eg work profile can not capture user profile apps and vice-versa).
  *
  * <p>An example for creating a capture configuration for capturing all media playback:
  *