1 /*
2  * Copyright (C) 2021 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.media;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.annotation.SystemApi;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 
25 import java.lang.annotation.Retention;
26 import java.lang.annotation.RetentionPolicy;
27 import java.util.Arrays;
28 import java.util.Objects;
29 
30 /**
31  * The AudioDescriptor contains the information to describe the audio playback/capture
32  * capabilities. The capabilities are described by a byte array, which is defined by a
33  * particular standard. This is used when the format is unrecognized to the platform.
34  */
35 public class AudioDescriptor implements Parcelable {
36     /**
37      * The audio standard is not specified.
38      */
39     public static final int STANDARD_NONE = 0;
40     /**
41      * The Extended Display Identification Data (EDID) standard for a short audio descriptor.
42      */
43     public static final int STANDARD_EDID = 1;
44     /**
45      * The standard for a Speaker Allocation Data Block (SADB).
46      */
47     public static final int STANDARD_SADB = 2;
48     /**
49      * The standard for a Vendor-Specific Audio Data Block (VSADB).
50      */
51     public static final int STANDARD_VSADB = 3;
52 
53     /** @hide */
54     @IntDef({
55             STANDARD_NONE,
56             STANDARD_EDID,
57             STANDARD_SADB,
58             STANDARD_VSADB,
59     })
60     @Retention(RetentionPolicy.SOURCE)
61     public @interface AudioDescriptorStandard {}
62 
63     private final int mStandard;
64     private final byte[] mDescriptor;
65     private final int mEncapsulationType;
66 
67     /**
68      * @hide
69      * Constructor from standard, encapsulation type and descriptor
70      * @param standard the standard of the audio descriptor
71      * @param encapsulationType the encapsulation type of the audio descriptor
72      * @param descriptor the audio descriptor
73      */
74     @SystemApi
AudioDescriptor(int standard, int encapsulationType, @NonNull byte[] descriptor)75     public AudioDescriptor(int standard, int encapsulationType, @NonNull byte[] descriptor) {
76         mStandard = standard;
77         mEncapsulationType = encapsulationType;
78         mDescriptor = descriptor;
79     }
80 
81     /**
82      * @return the standard that defines audio playback/capture capabilities.
83      */
getStandard()84     public @AudioDescriptorStandard int getStandard() {
85         return mStandard;
86     }
87 
88     /**
89      * @return a byte array that describes audio playback/capture capabilities as encoded by the
90      * standard for this AudioDescriptor.
91      */
getDescriptor()92     public @NonNull byte[] getDescriptor() {
93         return mDescriptor;
94     }
95 
96     /**
97      * The encapsulation type indicates what encapsulation type is required when the framework is
98      * using this extra audio descriptor for playing to a device exposing this audio profile.
99      * When encapsulation is required, only playback with {@link android.media.AudioTrack} API is
100      * supported. But playback with {@link android.media.MediaPlayer} is not.
101      * When an encapsulation type is required, the {@link AudioFormat} encoding selected when
102      * creating the {@link AudioTrack} must match the encapsulation type, e.g.
103      * AudioFormat#ENCODING_IEC61937 for AudioProfile.AUDIO_ENCAPSULATION_TYPE_IEC61937.
104      *
105      * @return an integer representing the encapsulation type
106      *
107      * @see AudioProfile#AUDIO_ENCAPSULATION_TYPE_NONE
108      * @see AudioProfile#AUDIO_ENCAPSULATION_TYPE_IEC61937
109      */
getEncapsulationType()110     public @AudioProfile.EncapsulationType int getEncapsulationType() {
111         return mEncapsulationType;
112     }
113 
114     @Override
hashCode()115     public int hashCode() {
116         return Objects.hash(mStandard, mEncapsulationType, Arrays.hashCode(mDescriptor));
117     }
118 
119     @Override
equals(Object o)120     public boolean equals(Object o) {
121         if (this == o) return true;
122         if (o == null || getClass() != o.getClass()) return false;
123 
124         AudioDescriptor that = (AudioDescriptor) o;
125         return ((mStandard == that.mStandard)
126                 && (mEncapsulationType == that.mEncapsulationType)
127                 && (Arrays.equals(mDescriptor, that.mDescriptor)));
128     }
129 
130     @Override
toString()131     public String toString() {
132         StringBuilder sb = new StringBuilder("{");
133         sb.append("standard=" + mStandard);
134         sb.append(", encapsulation type=" + mEncapsulationType);
135         if (mDescriptor != null && mDescriptor.length > 0) {
136             sb.append(", descriptor=").append(Arrays.toString(mDescriptor));
137         }
138         sb.append("}");
139         return sb.toString();
140     }
141 
142     @Override
describeContents()143     public int describeContents() {
144         return 0;
145     }
146 
147     @Override
writeToParcel(@onNull Parcel dest, int flags)148     public void writeToParcel(@NonNull Parcel dest, int flags) {
149         dest.writeInt(mStandard);
150         dest.writeInt(mEncapsulationType);
151         dest.writeByteArray(mDescriptor);
152     }
153 
AudioDescriptor(@onNull Parcel in)154     private AudioDescriptor(@NonNull Parcel in) {
155         mStandard = in.readInt();
156         mEncapsulationType = in.readInt();
157         mDescriptor = in.createByteArray();
158     }
159 
160     public static final @NonNull Parcelable.Creator<AudioDescriptor> CREATOR =
161             new Parcelable.Creator<AudioDescriptor>() {
162                 /**
163                  * Rebuilds an AudioDescriptor previously stored with writeToParcel().
164                  * @param p Parcel object to read the AudioDescriptor from
165                  * @return a new AudioDescriptor created from the data in the parcel
166                  */
167                 public AudioDescriptor createFromParcel(Parcel p) {
168                     return new AudioDescriptor(p);
169                 }
170 
171                 public AudioDescriptor[] newArray(int size) {
172                     return new AudioDescriptor[size];
173                 }
174             };
175 }
176