Merge "Add documentation for the APC feature" into qt-dev

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

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},

media/java/android/media/AudioManager.java

@@ -1483,12 +1483,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},

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:
  *