AudioTrack: Update Tuner API
Move Tuner specific methods to SystemApi
to match Tuner Api visibility.
Update return value annotation on getters.
Test: AudioTrackTest#testTunerConfiguration
Bug: 151178170
Change-Id: I5461d62db38cd912b5896b9c27fd1fef29306bae
diff --git a/api/current.txt b/api/current.txt
index 8152cd6..47a43eb 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -24658,7 +24658,6 @@
field public static final int ENCAPSULATION_METADATA_TYPE_DVB_AD_DESCRIPTOR = 2; // 0x2
field public static final int ENCAPSULATION_METADATA_TYPE_FRAMEWORK_TUNER = 1; // 0x1
field public static final int ENCAPSULATION_MODE_ELEMENTARY_STREAM = 1; // 0x1
- field public static final int ENCAPSULATION_MODE_HANDLE = 2; // 0x2
field public static final int ENCAPSULATION_MODE_NONE = 0; // 0x0
field public static final int ERROR = -1; // 0xffffffff
field public static final int ERROR_BAD_VALUE = -2; // 0xfffffffe
@@ -24691,7 +24690,6 @@
method @NonNull public android.media.AudioTrack.Builder setPerformanceMode(int);
method @NonNull public android.media.AudioTrack.Builder setSessionId(@IntRange(from=1) int) throws java.lang.IllegalArgumentException;
method @NonNull public android.media.AudioTrack.Builder setTransferMode(int) throws java.lang.IllegalArgumentException;
- method @NonNull public android.media.AudioTrack.Builder setTunerConfiguration(@NonNull android.media.AudioTrack.TunerConfiguration);
}
public static final class AudioTrack.MetricsConstants {
@@ -24723,18 +24721,6 @@
method public void onTearDown(@NonNull android.media.AudioTrack);
}
- public static class AudioTrack.TunerConfiguration {
- method public int getContentId();
- method public int getSyncId();
- }
-
- public static class AudioTrack.TunerConfiguration.Builder {
- ctor public AudioTrack.TunerConfiguration.Builder();
- method @NonNull public android.media.AudioTrack.TunerConfiguration build();
- method @NonNull public android.media.AudioTrack.TunerConfiguration.Builder setContentId(@IntRange(from=1) int);
- method @NonNull public android.media.AudioTrack.TunerConfiguration.Builder setSyncId(@IntRange(from=1) int);
- }
-
public class CamcorderProfile {
method public static android.media.CamcorderProfile get(int);
method public static android.media.CamcorderProfile get(int, int);
diff --git a/api/system-current.txt b/api/system-current.txt
index 2d2ebcd..3f65890 100755
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -4354,6 +4354,26 @@
method @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public int getClientUid();
}
+ public class AudioTrack implements android.media.AudioRouting android.media.VolumeAutomation {
+ field @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public static final int ENCAPSULATION_MODE_HANDLE = 2; // 0x2
+ }
+
+ public static class AudioTrack.Builder {
+ method @NonNull @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public android.media.AudioTrack.Builder setTunerConfiguration(@NonNull android.media.AudioTrack.TunerConfiguration);
+ }
+
+ public static class AudioTrack.TunerConfiguration {
+ method @IntRange(from=1) @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public int getContentId();
+ method @IntRange(from=1) @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public int getSyncId();
+ }
+
+ public static class AudioTrack.TunerConfiguration.Builder {
+ ctor public AudioTrack.TunerConfiguration.Builder();
+ method @NonNull @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public android.media.AudioTrack.TunerConfiguration build();
+ method @NonNull @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public android.media.AudioTrack.TunerConfiguration.Builder setContentId(@IntRange(from=1) int);
+ method @NonNull @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) public android.media.AudioTrack.TunerConfiguration.Builder setSyncId(@IntRange(from=1) int);
+ }
+
public class HwAudioSource {
method public boolean isPlaying();
method public void start();
diff --git a/media/java/android/media/AudioDeviceInfo.java b/media/java/android/media/AudioDeviceInfo.java
index 6e63d17..9950f05 100644
--- a/media/java/android/media/AudioDeviceInfo.java
+++ b/media/java/android/media/AudioDeviceInfo.java
@@ -425,9 +425,9 @@
/**
* Returns an array of supported encapsulation modes for the device.
*
- * The array can include any of
- * {@link AudioTrack#ENCAPSULATION_MODE_ELEMENTARY_STREAM},
- * {@link AudioTrack#ENCAPSULATION_MODE_HANDLE}.
+ * The array can include any of the {@code AudioTrack} encapsulation modes,
+ * e.g. {@link AudioTrack#ENCAPSULATION_MODE_NONE},
+ * or {@link AudioTrack#ENCAPSULATION_MODE_ELEMENTARY_STREAM}.
*
* @return An array of supported encapsulation modes for the device. This
* may be an empty array if no encapsulation modes are supported.
diff --git a/media/java/android/media/AudioTrack.java b/media/java/android/media/AudioTrack.java
index 94d4fcc..d17e429 100644
--- a/media/java/android/media/AudioTrack.java
+++ b/media/java/android/media/AudioTrack.java
@@ -22,6 +22,8 @@
import android.annotation.IntRange;
import android.annotation.NonNull;
import android.annotation.Nullable;
+import android.annotation.RequiresPermission;
+import android.annotation.SystemApi;
import android.annotation.TestApi;
import android.compat.annotation.UnsupportedAppUsage;
import android.os.Binder;
@@ -229,7 +231,7 @@
@IntDef({
ENCAPSULATION_MODE_NONE,
ENCAPSULATION_MODE_ELEMENTARY_STREAM,
- ENCAPSULATION_MODE_HANDLE,
+ // ENCAPSULATION_MODE_HANDLE, @SystemApi
})
@Retention(RetentionPolicy.SOURCE)
public @interface EncapsulationMode {}
@@ -244,16 +246,17 @@
/**
* This mode indicates metadata encapsulation with an elementary stream payload.
* Both compressed and PCM format is allowed.
- *
- * TODO(b/147778408) Link: See the Android developers guide for more information.
*/
public static final int ENCAPSULATION_MODE_ELEMENTARY_STREAM = 1;
/**
- * This mode indicates metadata encapsulation with a handle payload.
- * The handle is a 64 bit long, provided by the Tuner API.
- *
- * TODO(b/147778408) Link: Fill in Tuner API to obtain the handle.
+ * This mode indicates metadata encapsulation with a handle payload
+ * and is set through {@link Builder#setEncapsulationMode(int)}.
+ * The handle is a 64 bit long, provided by the Tuner API
+ * in {@link android.os.Build.VERSION_CODES#R}.
+ * @hide
*/
+ @SystemApi
+ @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING)
public static final int ENCAPSULATION_MODE_HANDLE = 2;
/* Enumeration of metadata types permitted for use by
@@ -908,7 +911,9 @@
*
* Use the Builder to construct the TunerConfiguration object,
* which is then used by the {@link AudioTrack.Builder} to create an AudioTrack.
+ * @hide
*/
+ @SystemApi
public static class TunerConfiguration {
private final int mContentId;
private final int mSyncId;
@@ -921,15 +926,17 @@
/**
* Returns the contentId.
*/
- public int getContentId() {
- return mContentId;
+ @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING)
+ public @IntRange(from = 1) int getContentId() {
+ return mContentId; // The Builder ensures this is > 0.
}
/**
* Returns the syncId.
*/
- public int getSyncId() {
- return mSyncId;
+ @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING)
+ public @IntRange(from = 1) int getSyncId() {
+ return mSyncId; // The Builder ensures this is > 0.
}
/**
@@ -943,11 +950,13 @@
* Sets the contentId from the Tuner filter.
*
* @param contentId selects the audio stream to use.
- * See android.media.tv.tuner.filter.Filter#getId().
+ * The contentId may be obtained from
+ * {@link android.media.tv.tuner.filter.Filter#getId()}.
* This is always a positive number.
- * TODO(b/147778408) Link to tuner filter doc when unhidden.
+ *
* @return the same Builder instance.
*/
+ @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING)
public @NonNull Builder setContentId(@IntRange(from = 1) int contentId) {
if (contentId < 1) {
throw new IllegalArgumentException(
@@ -962,11 +971,13 @@
*
* @param syncId selects the clock to use for synchronization
* of audio with other streams such as video.
- * See android.media.tv.tuner.Tuner#getAvSyncHwId().
+ * The syncId may be obtained from
+ * {@link android.media.tv.tuner.Tuner#getAvSyncHwId()}.
* This is always a positive number.
- * TODO(b/147778408) Link to tuner filter doc when unhidden.
+ *
* @return the same Builder instance.
*/
+ @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING)
public @NonNull Builder setSyncId(@IntRange(from = 1) int syncId) {
if (syncId < 1) {
throw new IllegalArgumentException("syncId " + syncId + " must be positive");
@@ -983,11 +994,12 @@
* @throws UnsupportedOperationException if the parameters set on the
* {@code Builder} are incompatible.
*/
+ @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING)
public @NonNull TunerConfiguration build() {
if (mContentId < 1 || mSyncId < 1) {
throw new UnsupportedOperationException(
- "contentId " + mContentId
- + " syncId " + mSyncId
+ "mContentId " + mContentId
+ + " mSyncId " + mSyncId
+ " must be set");
}
return new TunerConfiguration(mContentId, mSyncId);
@@ -1113,15 +1125,14 @@
*
* Encapsulation mode allows metadata to be sent together with
* the audio data payload in a {@code ByteBuffer}.
- * The data format is specified in the Android developers site.
- *
- * TODO(b/147778408) Link to doc page.
+ * This requires a compatible hardware audio codec.
*
* @param encapsulationMode one of {@link AudioTrack#ENCAPSULATION_MODE_NONE},
- * {@link AudioTrack#ENCAPSULATION_MODE_ELEMENTARY_STREAM},
- * {@link AudioTrack#ENCAPSULATION_MODE_HANDLE}.
+ * or {@link AudioTrack#ENCAPSULATION_MODE_ELEMENTARY_STREAM}.
* @return the same Builder instance.
*/
+ // Note: with the correct permission {@code AudioTrack#ENCAPSULATION_MODE_HANDLE}
+ // may be used as well.
public @NonNull Builder setEncapsulationMode(@EncapsulationMode int encapsulationMode) {
switch (encapsulationMode) {
case ENCAPSULATION_MODE_NONE:
@@ -1225,7 +1236,10 @@
*
* @param tunerConfiguration obtained by {@link AudioTrack.TunerConfiguration.Builder}.
* @return the same Builder instance.
+ * @hide
*/
+ @SystemApi
+ @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING)
public @NonNull Builder setTunerConfiguration(
@NonNull TunerConfiguration tunerConfiguration) {
if (tunerConfiguration == null) {
@@ -1475,7 +1489,7 @@
*
* For AudioTracks incorporating a secondary Audio Description stream
* (where such contents may be sent through an Encapsulation Mode
- * {@link #ENCAPSULATION_MODE_ELEMENTARY_STREAM} or {@link #ENCAPSULATION_MODE_HANDLE}
+ * other than {@link #ENCAPSULATION_MODE_NONE}).
* or internally by a HW channel),
* the level of mixing of the Audio Description to the Main Audio stream
* is controlled by this method.