Rename exported API and improve the documentation

1. Export the MIX_ROLE_* instead of the internal used MIX_TYPE_*
2. Rename API from "type" to "role"
3. Improve the documentation

Bug: 183693610, 194163617
Test: atest com.google.android.gts.audioservice.AudioServiceHostTest
CTS-Coverage-Bug: 191716676
Change-Id: I3f57a832751814469fce4686290212bfda5bd199

core/api/system-current.txt

@@ -5425,8 +5425,6 @@ package android.media.audiopolicy {
     field public static final int MIX_STATE_DISABLED = -1; // 0xffffffff
     field public static final int MIX_STATE_IDLE = 0; // 0x0
     field public static final int MIX_STATE_MIXING = 1; // 0x1
-    field public static final int MIX_TYPE_PLAYERS = 0; // 0x0
-    field public static final int MIX_TYPE_RECORDERS = 1; // 0x1
     field public static final int ROUTE_FLAG_LOOP_BACK = 2; // 0x2
     field public static final int ROUTE_FLAG_RENDER = 1; // 0x1
   }
@@ -5440,7 +5438,9 @@ package android.media.audiopolicy {
   }
 
   public class AudioMixingRule {
-    method public int getTargetMixType();
+    method public int getTargetMixRole();
+    field public static final int MIX_ROLE_INJECTOR = 1; // 0x1
+    field public static final int MIX_ROLE_PLAYERS = 0; // 0x0
     field public static final int RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET = 2; // 0x2
     field public static final int RULE_MATCH_ATTRIBUTE_USAGE = 1; // 0x1
     field public static final int RULE_MATCH_UID = 4; // 0x4
@@ -5455,7 +5455,7 @@ package android.media.audiopolicy {
     method public android.media.audiopolicy.AudioMixingRule build();
     method public android.media.audiopolicy.AudioMixingRule.Builder excludeMixRule(int, Object) throws java.lang.IllegalArgumentException;
     method public android.media.audiopolicy.AudioMixingRule.Builder excludeRule(android.media.AudioAttributes, int) throws java.lang.IllegalArgumentException;
-    method @NonNull public android.media.audiopolicy.AudioMixingRule.Builder setTargetMixType(int);
+    method @NonNull public android.media.audiopolicy.AudioMixingRule.Builder setTargetMixRole(int);
   }
 
   public class AudioPolicy {

media/java/android/media/audiopolicy/AudioMix.java

@@ -113,10 +113,12 @@ public class AudioMix {
      */
     public static final int MIX_TYPE_INVALID = -1;
     /**
+     * @hide
      * Mix type indicating playback streams are mixed.
      */
     public static final int MIX_TYPE_PLAYERS = 0;
     /**
+     * @hide
      * Mix type indicating recording streams are mixed.
      */
     public static final int MIX_TYPE_RECORDERS = 1;

media/java/android/media/audiopolicy/AudioMixingRule.java

@@ -203,17 +203,34 @@ public class AudioMixingRule {
     }
 
     private final int mTargetMixType;
-
-    /** @hide */
-    @IntDef({AudioMix.MIX_TYPE_PLAYERS, AudioMix.MIX_TYPE_RECORDERS})
-    @Retention(SOURCE)
-    public @interface MixType {}
+    int getTargetMixType() {
+        return mTargetMixType;
+    }
 
     /**
-     * Gets target mix type of the mixing rule.
+     * Captures an audio signal from one or more playback streams.
      */
-    public @MixType int getTargetMixType() {
-        return mTargetMixType;
+    public static final int MIX_ROLE_PLAYERS = AudioMix.MIX_TYPE_PLAYERS;
+    /**
+     * Injects an audio signal into the framework to replace a recording source.
+     */
+    public static final int MIX_ROLE_INJECTOR = AudioMix.MIX_TYPE_RECORDERS;
+
+    /** @hide */
+    @IntDef({MIX_ROLE_PLAYERS, MIX_ROLE_INJECTOR})
+    @Retention(SOURCE)
+    public @interface MixRole {}
+
+    /**
+     * Gets target mix role of this mixing rule.
+     *
+     * <p>The mix role indicates playback streams will be captured or recording source will be
+     * injected.
+     *
+     * @return integer value of {@link #MIX_ROLE_PLAYERS} or {@link #MIX_ROLE_INJECTOR}
+     */
+    public @MixRole int getTargetMixRole() {
+        return mTargetMixType == AudioMix.MIX_TYPE_RECORDERS ? MIX_ROLE_INJECTOR : MIX_ROLE_PLAYERS;
     }
 
     @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
@@ -485,26 +502,23 @@ public class AudioMixingRule {
         }
 
         /**
-         * Sets target mix type of the mixing rule.
+         * Sets target mix role of the mixing rule.
          *
-         * <p>Note: If the mix type was not specified, it will be decided automatically by matched
-         * mixing rule. For example, {@link AudioMixingRule#RULE_MATCH_ATTRIBUTE_USAGE} or {@link
-         * AudioMixingRule#RULE_MATCH_USERID} applied {@link AudioMix#MIX_TYPE_PLAYERS}, {@link
-         * AudioMixingRule#RULE_MATCH_ATTRIBUTE_CAPTURE_PRESET} applied {@link
-         * AudioMix#MIX_TYPE_RECORDERS}. For {@link AudioMixingRule#RULE_MATCH_UID}, the mix type
-         * could be {@link AudioMix#MIX_TYPE_PLAYERS} or {@link AudioMix#MIX_TYPE_RECORDERS}, and
-         * {@link AudioMix#MIX_TYPE_PLAYERS} is the default value.
+         * <p>The mix role indicates playback streams will be captured or recording source will be
+         * injected. If not specified, the mix role will be decided automatically when
+         * {@link #addRule(AudioAttributes, int)} or {@link #addMixRule(int, Object)} be called.
          *
-         * @param mixType {@link AudioMix#MIX_TYPE_PLAYERS} or {@link AudioMix#MIX_TYPE_RECORDERS}
+         * @param mixRole integer value of {@link #MIX_ROLE_PLAYERS} or {@link #MIX_ROLE_INJECTOR}
          * @return the same Builder instance.
          */
-        public @NonNull Builder setTargetMixType(@MixType int mixType) {
-            if (mixType != AudioMix.MIX_TYPE_PLAYERS && mixType != AudioMix.MIX_TYPE_RECORDERS) {
-                throw new IllegalArgumentException("Illegal argument for mix type");
+        public @NonNull Builder setTargetMixRole(@MixRole int mixRole) {
+            if (mixRole != MIX_ROLE_PLAYERS && mixRole != MIX_ROLE_INJECTOR) {
+                throw new IllegalArgumentException("Illegal argument for mix role");
             }
 
-            mTargetMixType = mixType;
-            Log.i("AudioMixingRule", "Builder setTargetMixType " + mixType);
+            Log.i("AudioMixingRule", "Builder setTargetMixRole " + mixRole);
+            mTargetMixType = mixRole == MIX_ROLE_INJECTOR
+                    ? AudioMix.MIX_TYPE_RECORDERS : AudioMix.MIX_TYPE_PLAYERS;
             return this;
         }
 

media/java/android/media/audiopolicy/AudioPolicyConfig.java

@@ -101,7 +101,7 @@ public class AudioPolicyConfig implements Parcelable {
             // write voice communication capture allowed flag
             dest.writeBoolean(mix.getRule().voiceCommunicationCaptureAllowed());
             // write specified mix type
-            dest.writeInt(mix.getRule().getTargetMixType());
+            dest.writeInt(mix.getRule().getTargetMixRole());
             // write mix rules
             final ArrayList<AudioMixMatchCriterion> criteria = mix.getRule().getCriteria();
             dest.writeInt(criteria.size());
@@ -137,7 +137,7 @@ public class AudioPolicyConfig implements Parcelable {
             // read voice capture allowed flag
             ruleBuilder.voiceCommunicationCaptureAllowed(in.readBoolean());
             // read specified mix type
-            ruleBuilder.setTargetMixType(in.readInt());
+            ruleBuilder.setTargetMixRole(in.readInt());
             // read mix rules
             int nbRules = in.readInt();
             for (int j = 0 ; j < nbRules ; j++) {
@@ -181,7 +181,7 @@ public class AudioPolicyConfig implements Parcelable {
                     + mix.getRule().voiceCommunicationCaptureAllowed() + "\n";
             // write mix rules
             textDump += "  specified mix type="
-                    + mix.getRule().getTargetMixType() + "\n";
+                    + mix.getRule().getTargetMixRole() + "\n";
             final ArrayList<AudioMixMatchCriterion> criteria = mix.getRule().getCriteria();
             for (AudioMixMatchCriterion criterion : criteria) {
                 switch(criterion.mRule) {