1 /*
2  * Copyright (C) 2014 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.Bundle;
23 import android.os.Parcel;
24 import android.os.Parcelable;
25 import android.text.TextUtils;
26 import android.util.Log;
27 import android.util.SparseIntArray;
28 
29 import java.lang.annotation.Retention;
30 import java.lang.annotation.RetentionPolicy;
31 import java.util.Collections;
32 import java.util.HashSet;
33 import java.util.Objects;
34 import java.util.Set;
35 
36 /**
37  * A class to encapsulate a collection of attributes describing information about an audio
38  * stream.
39  * <p><code>AudioAttributes</code> supersede the notion of stream types (see for instance
40  * {@link AudioManager#STREAM_MUSIC} or {@link AudioManager#STREAM_ALARM}) for defining the
41  * behavior of audio playback. Attributes allow an application to specify more information than is
42  * conveyed in a stream type by allowing the application to define:
43  * <ul>
44  * <li>usage: "why" you are playing a sound, what is this sound used for. This is achieved with
45  *     the "usage" information. Examples of usage are {@link #USAGE_MEDIA} and {@link #USAGE_ALARM}.
46  *     These two examples are the closest to stream types, but more detailed use cases are
47  *     available. Usage information is more expressive than a stream type, and allows certain
48  *     platforms or routing policies to use this information for more refined volume or routing
49  *     decisions. Usage is the most important information to supply in <code>AudioAttributes</code>
50  *     and it is recommended to build any instance with this information supplied, see
51  *     {@link AudioAttributes.Builder} for exceptions.</li>
52  * <li>content type: "what" you are playing. The content type expresses the general category of
53  *     the content. This information is optional. But in case it is known (for instance
54  *     {@link #CONTENT_TYPE_MOVIE} for a movie streaming service or {@link #CONTENT_TYPE_MUSIC} for
55  *     a music playback application) this information might be used by the audio framework to
56  *     selectively configure some audio post-processing blocks.</li>
57  * <li>flags: "how" is playback to be affected, see the flag definitions for the specific playback
58  *     behaviors they control. </li>
59  * </ul>
60  * <p><code>AudioAttributes</code> are used for example in one of the {@link AudioTrack}
61  * constructors (see {@link AudioTrack#AudioTrack(AudioAttributes, AudioFormat, int, int, int)}),
62  * to configure a {@link MediaPlayer}
63  * (see {@link MediaPlayer#setAudioAttributes(AudioAttributes)} or a
64  * {@link android.app.Notification} (see {@link android.app.Notification#audioAttributes}). An
65  * <code>AudioAttributes</code> instance is built through its builder,
66  * {@link AudioAttributes.Builder}.
67  */
68 public final class AudioAttributes implements Parcelable {
69     private final static String TAG = "AudioAttributes";
70 
71     /**
72      * Content type value to use when the content type is unknown, or other than the ones defined.
73      */
74     public final static int CONTENT_TYPE_UNKNOWN = 0;
75     /**
76      * Content type value to use when the content type is speech.
77      */
78     public final static int CONTENT_TYPE_SPEECH = 1;
79     /**
80      * Content type value to use when the content type is music.
81      */
82     public final static int CONTENT_TYPE_MUSIC = 2;
83     /**
84      * Content type value to use when the content type is a soundtrack, typically accompanying
85      * a movie or TV program.
86      */
87     public final static int CONTENT_TYPE_MOVIE = 3;
88     /**
89      * Content type value to use when the content type is a sound used to accompany a user
90      * action, such as a beep or sound effect expressing a key click, or event, such as the
91      * type of a sound for a bonus being received in a game. These sounds are mostly synthesized
92      * or short Foley sounds.
93      */
94     public final static int CONTENT_TYPE_SONIFICATION = 4;
95 
96     /**
97      * Usage value to use when the usage is unknown.
98      */
99     public final static int USAGE_UNKNOWN = 0;
100     /**
101      * Usage value to use when the usage is media, such as music, or movie
102      * soundtracks.
103      */
104     public final static int USAGE_MEDIA = 1;
105     /**
106      * Usage value to use when the usage is voice communications, such as telephony
107      * or VoIP.
108      */
109     public final static int USAGE_VOICE_COMMUNICATION = 2;
110     /**
111      * Usage value to use when the usage is in-call signalling, such as with
112      * a "busy" beep, or DTMF tones.
113      */
114     public final static int USAGE_VOICE_COMMUNICATION_SIGNALLING = 3;
115     /**
116      * Usage value to use when the usage is an alarm (e.g. wake-up alarm).
117      */
118     public final static int USAGE_ALARM = 4;
119     /**
120      * Usage value to use when the usage is notification. See other
121      * notification usages for more specialized uses.
122      */
123     public final static int USAGE_NOTIFICATION = 5;
124     /**
125      * Usage value to use when the usage is telephony ringtone.
126      */
127     public final static int USAGE_NOTIFICATION_RINGTONE = 6;
128     /**
129      * Usage value to use when the usage is a request to enter/end a
130      * communication, such as a VoIP communication or video-conference.
131      */
132     public final static int USAGE_NOTIFICATION_COMMUNICATION_REQUEST = 7;
133     /**
134      * Usage value to use when the usage is notification for an "instant"
135      * communication such as a chat, or SMS.
136      */
137     public final static int USAGE_NOTIFICATION_COMMUNICATION_INSTANT = 8;
138     /**
139      * Usage value to use when the usage is notification for a
140      * non-immediate type of communication such as e-mail.
141      */
142     public final static int USAGE_NOTIFICATION_COMMUNICATION_DELAYED = 9;
143     /**
144      * Usage value to use when the usage is to attract the user's attention,
145      * such as a reminder or low battery warning.
146      */
147     public final static int USAGE_NOTIFICATION_EVENT = 10;
148     /**
149      * Usage value to use when the usage is for accessibility, such as with
150      * a screen reader.
151      */
152     public final static int USAGE_ASSISTANCE_ACCESSIBILITY = 11;
153     /**
154      * Usage value to use when the usage is driving or navigation directions.
155      */
156     public final static int USAGE_ASSISTANCE_NAVIGATION_GUIDANCE = 12;
157     /**
158      * Usage value to use when the usage is sonification, such as  with user
159      * interface sounds.
160      */
161     public final static int USAGE_ASSISTANCE_SONIFICATION = 13;
162     /**
163      * Usage value to use when the usage is for game audio.
164      */
165     public final static int USAGE_GAME = 14;
166     /**
167      * @hide
168      * Usage value to use when feeding audio to the platform and replacing "traditional" audio
169      * source, such as audio capture devices.
170      */
171     public final static int USAGE_VIRTUAL_SOURCE = 15;
172     /**
173      * Usage value to use for audio responses to user queries, audio instructions or help
174      * utterances.
175      */
176     public final static int USAGE_ASSISTANT = 16;
177 
178     /**
179      * IMPORTANT: when adding new usage types, add them to SDK_USAGES and update SUPPRESSIBLE_USAGES
180      *            if applicable.
181      */
182 
183     /**
184      * @hide
185      * Denotes a usage for notifications that do not expect immediate intervention from the user,
186      * will be muted when the Zen mode disables notifications
187      * @see #SUPPRESSIBLE_USAGES
188      */
189     public final static int SUPPRESSIBLE_NOTIFICATION = 1;
190     /**
191      * @hide
192      * Denotes a usage for notifications that do expect immediate intervention from the user,
193      * will be muted when the Zen mode disables calls
194      * @see #SUPPRESSIBLE_USAGES
195      */
196     public final static int SUPPRESSIBLE_CALL = 2;
197     /**
198      * @hide
199      * Denotes a usage that is never going to be muted, even in Total Silence.
200      * @see #SUPPRESSIBLE_USAGES
201      */
202     public final static int SUPPRESSIBLE_NEVER = 3;
203 
204     /**
205      * @hide
206      * Array of all usage types for calls and notifications to assign the suppression behavior,
207      * used by the Zen mode restrictions.
208      * @see com.android.server.notification.ZenModeHelper
209      */
210     public static final SparseIntArray SUPPRESSIBLE_USAGES;
211 
212     static {
213         SUPPRESSIBLE_USAGES = new SparseIntArray();
SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION, SUPPRESSIBLE_NOTIFICATION)214         SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION,                      SUPPRESSIBLE_NOTIFICATION);
SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_RINGTONE, SUPPRESSIBLE_CALL)215         SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_RINGTONE,             SUPPRESSIBLE_CALL);
SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_REQUEST,SUPPRESSIBLE_CALL)216         SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_REQUEST,SUPPRESSIBLE_CALL);
SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_INSTANT,SUPPRESSIBLE_NOTIFICATION)217         SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_INSTANT,SUPPRESSIBLE_NOTIFICATION);
SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_DELAYED,SUPPRESSIBLE_NOTIFICATION)218         SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_DELAYED,SUPPRESSIBLE_NOTIFICATION);
SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_EVENT, SUPPRESSIBLE_NOTIFICATION)219         SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_EVENT,                SUPPRESSIBLE_NOTIFICATION);
SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANCE_ACCESSIBILITY, SUPPRESSIBLE_NEVER)220         SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANCE_ACCESSIBILITY,          SUPPRESSIBLE_NEVER);
221     }
222 
223     /**
224      * @hide
225      * Array of all usage types exposed in the SDK that applications can use.
226      */
227     public final static int[] SDK_USAGES = {
228             USAGE_UNKNOWN,
229             USAGE_MEDIA,
230             USAGE_VOICE_COMMUNICATION,
231             USAGE_VOICE_COMMUNICATION_SIGNALLING,
232             USAGE_ALARM,
233             USAGE_NOTIFICATION,
234             USAGE_NOTIFICATION_RINGTONE,
235             USAGE_NOTIFICATION_COMMUNICATION_REQUEST,
236             USAGE_NOTIFICATION_COMMUNICATION_INSTANT,
237             USAGE_NOTIFICATION_COMMUNICATION_DELAYED,
238             USAGE_NOTIFICATION_EVENT,
239             USAGE_ASSISTANCE_ACCESSIBILITY,
240             USAGE_ASSISTANCE_NAVIGATION_GUIDANCE,
241             USAGE_ASSISTANCE_SONIFICATION,
242             USAGE_GAME,
243             USAGE_ASSISTANT,
244     };
245 
246     /**
247      * Flag defining a behavior where the audibility of the sound will be ensured by the system.
248      */
249     public final static int FLAG_AUDIBILITY_ENFORCED = 0x1 << 0;
250     /**
251      * @hide
252      * Flag defining a behavior where the playback of the sound is ensured without
253      * degradation only when going to a secure sink.
254      */
255     // FIXME not guaranteed yet
256     // TODO  add in FLAG_ALL_PUBLIC when supported and in public API
257     public final static int FLAG_SECURE = 0x1 << 1;
258     /**
259      * @hide
260      * Flag to enable when the stream is associated with SCO usage.
261      * Internal use only for dealing with legacy STREAM_BLUETOOTH_SCO
262      */
263     public final static int FLAG_SCO = 0x1 << 2;
264     /**
265      * @hide
266      * Flag defining a behavior where the system ensures that the playback of the sound will
267      * be compatible with its use as a broadcast for surrounding people and/or devices.
268      * Ensures audibility with no or minimal post-processing applied.
269      */
270     @SystemApi
271     public final static int FLAG_BEACON = 0x1 << 3;
272 
273     /**
274      * Flag requesting the use of an output stream supporting hardware A/V synchronization.
275      */
276     public final static int FLAG_HW_AV_SYNC = 0x1 << 4;
277 
278     /**
279      * @hide
280      * Flag requesting capture from the source used for hardware hotword detection.
281      * To be used with capture preset MediaRecorder.AudioSource.HOTWORD or
282      * MediaRecorder.AudioSource.VOICE_RECOGNITION.
283      */
284     @SystemApi
285     public final static int FLAG_HW_HOTWORD = 0x1 << 5;
286 
287     /**
288      * @hide
289      * Flag requesting audible playback even under limited interruptions.
290      */
291     @SystemApi
292     public final static int FLAG_BYPASS_INTERRUPTION_POLICY = 0x1 << 6;
293 
294     /**
295      * @hide
296      * Flag requesting audible playback even when the underlying stream is muted.
297      */
298     @SystemApi
299     public final static int FLAG_BYPASS_MUTE = 0x1 << 7;
300 
301     /**
302      * Flag requesting a low latency path when creating an AudioTrack.
303      * When using this flag, the sample rate must match the native sample rate
304      * of the device. Effects processing is also unavailable.
305      *
306      * Note that if this flag is used without specifying a bufferSizeInBytes then the
307      * AudioTrack's actual buffer size may be too small. It is recommended that a fairly
308      * large buffer should be specified when the AudioTrack is created.
309      * Then the actual size can be reduced by calling
310      * {@link AudioTrack#setBufferSizeInFrames(int)}. The buffer size can be optimized
311      * by lowering it after each write() call until the audio glitches, which is detected by calling
312      * {@link AudioTrack#getUnderrunCount()}. Then the buffer size can be increased
313      * until there are no glitches.
314      * This tuning step should be done while playing silence.
315      * This technique provides a compromise between latency and glitch rate.
316      *
317      * @deprecated Use {@link AudioTrack.Builder#setPerformanceMode(int)} with
318      * {@link AudioTrack#PERFORMANCE_MODE_LOW_LATENCY} to control performance.
319      */
320     public final static int FLAG_LOW_LATENCY = 0x1 << 8;
321 
322     /**
323      * @hide
324      * Flag requesting a deep buffer path when creating an {@code AudioTrack}.
325      *
326      * A deep buffer path, if available, may consume less power and is
327      * suitable for media playback where latency is not a concern.
328      * Use {@link AudioTrack.Builder#setPerformanceMode(int)} with
329      * {@link AudioTrack#PERFORMANCE_MODE_POWER_SAVING} to enable.
330      */
331     public final static int FLAG_DEEP_BUFFER = 0x1 << 9;
332 
333     private final static int FLAG_ALL = FLAG_AUDIBILITY_ENFORCED | FLAG_SECURE | FLAG_SCO |
334             FLAG_BEACON | FLAG_HW_AV_SYNC | FLAG_HW_HOTWORD | FLAG_BYPASS_INTERRUPTION_POLICY |
335             FLAG_BYPASS_MUTE | FLAG_LOW_LATENCY | FLAG_DEEP_BUFFER;
336     private final static int FLAG_ALL_PUBLIC = FLAG_AUDIBILITY_ENFORCED |
337             FLAG_HW_AV_SYNC | FLAG_LOW_LATENCY;
338 
339     private int mUsage = USAGE_UNKNOWN;
340     private int mContentType = CONTENT_TYPE_UNKNOWN;
341     private int mSource = MediaRecorder.AudioSource.AUDIO_SOURCE_INVALID;
342     private int mFlags = 0x0;
343     private HashSet<String> mTags;
344     private String mFormattedTags;
345     private Bundle mBundle; // lazy-initialized, may be null
346 
AudioAttributes()347     private AudioAttributes() {
348     }
349 
350     /**
351      * Return the content type.
352      * @return one of the values that can be set in {@link Builder#setContentType(int)}
353      */
getContentType()354     public int getContentType() {
355         return mContentType;
356     }
357 
358     /**
359      * Return the usage.
360      * @return one of the values that can be set in {@link Builder#setUsage(int)}
361      */
getUsage()362     public int getUsage() {
363         return mUsage;
364     }
365 
366     /**
367      * @hide
368      * Return the capture preset.
369      * @return one of the values that can be set in {@link Builder#setCapturePreset(int)} or a
370      *    negative value if none has been set.
371      */
372     @SystemApi
getCapturePreset()373     public int getCapturePreset() {
374         return mSource;
375     }
376 
377     /**
378      * Return the flags.
379      * @return a combined mask of all flags
380      */
getFlags()381     public int getFlags() {
382         // only return the flags that are public
383         return (mFlags & (FLAG_ALL_PUBLIC));
384     }
385 
386     /**
387      * @hide
388      * Return all the flags, even the non-public ones.
389      * Internal use only
390      * @return a combined mask of all flags
391      */
392     @SystemApi
getAllFlags()393     public int getAllFlags() {
394         return (mFlags & FLAG_ALL);
395     }
396 
397     /**
398      * @hide
399      * Return the Bundle of data.
400      * @return a copy of the Bundle for this instance, may be null.
401      */
402     @SystemApi
getBundle()403     public Bundle getBundle() {
404         if (mBundle == null) {
405             return mBundle;
406         } else {
407             return new Bundle(mBundle);
408         }
409     }
410 
411     /**
412      * @hide
413      * Return the set of tags.
414      * @return a read-only set of all tags stored as strings.
415      */
getTags()416     public Set<String> getTags() {
417         return Collections.unmodifiableSet(mTags);
418     }
419 
420     /**
421      * Builder class for {@link AudioAttributes} objects.
422      * <p> Here is an example where <code>Builder</code> is used to define the
423      * {@link AudioAttributes} to be used by a new <code>AudioTrack</code> instance:
424      *
425      * <pre class="prettyprint">
426      * AudioTrack myTrack = new AudioTrack(
427      *         new AudioAttributes.Builder()
428      *             .setUsage(AudioAttributes.USAGE_MEDIA)
429      *             .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
430      *             .build(),
431      *         myFormat, myBuffSize, AudioTrack.MODE_STREAM, mySession);
432      * </pre>
433      *
434      * <p>By default all types of information (usage, content type, flags) conveyed by an
435      * <code>AudioAttributes</code> instance are set to "unknown". Unknown information will be
436      * interpreted as a default value that is dependent on the context of use, for instance a
437      * {@link MediaPlayer} will use a default usage of {@link AudioAttributes#USAGE_MEDIA}.
438      */
439     public static class Builder {
440         private int mUsage = USAGE_UNKNOWN;
441         private int mContentType = CONTENT_TYPE_UNKNOWN;
442         private int mSource = MediaRecorder.AudioSource.AUDIO_SOURCE_INVALID;
443         private int mFlags = 0x0;
444         private HashSet<String> mTags = new HashSet<String>();
445         private Bundle mBundle;
446 
447         /**
448          * Constructs a new Builder with the defaults.
449          * By default, usage and content type are respectively {@link AudioAttributes#USAGE_UNKNOWN}
450          * and {@link AudioAttributes#CONTENT_TYPE_UNKNOWN}, and flags are 0. It is recommended to
451          * configure the usage (with {@link #setUsage(int)}) or deriving attributes from a legacy
452          * stream type (with {@link #setLegacyStreamType(int)}) before calling {@link #build()}
453          * to override any default playback behavior in terms of routing and volume management.
454          */
Builder()455         public Builder() {
456         }
457 
458         /**
459          * Constructs a new Builder from a given AudioAttributes
460          * @param aa the AudioAttributes object whose data will be reused in the new Builder.
461          */
462         @SuppressWarnings("unchecked") // for cloning of mTags
Builder(AudioAttributes aa)463         public Builder(AudioAttributes aa) {
464             mUsage = aa.mUsage;
465             mContentType = aa.mContentType;
466             mFlags = aa.mFlags;
467             mTags = (HashSet<String>) aa.mTags.clone();
468         }
469 
470         /**
471          * Combines all of the attributes that have been set and return a new
472          * {@link AudioAttributes} object.
473          * @return a new {@link AudioAttributes} object
474          */
475         @SuppressWarnings("unchecked") // for cloning of mTags
build()476         public AudioAttributes build() {
477             AudioAttributes aa = new AudioAttributes();
478             aa.mContentType = mContentType;
479             aa.mUsage = mUsage;
480             aa.mSource = mSource;
481             aa.mFlags = mFlags;
482             aa.mTags = (HashSet<String>) mTags.clone();
483             aa.mFormattedTags = TextUtils.join(";", mTags);
484             if (mBundle != null) {
485                 aa.mBundle = new Bundle(mBundle);
486             }
487             return aa;
488         }
489 
490         /**
491          * Sets the attribute describing what is the intended use of the the audio signal,
492          * such as alarm or ringtone.
493          * @param usage one of {@link AudioAttributes#USAGE_UNKNOWN},
494          *     {@link AudioAttributes#USAGE_MEDIA},
495          *     {@link AudioAttributes#USAGE_VOICE_COMMUNICATION},
496          *     {@link AudioAttributes#USAGE_VOICE_COMMUNICATION_SIGNALLING},
497          *     {@link AudioAttributes#USAGE_ALARM}, {@link AudioAttributes#USAGE_NOTIFICATION},
498          *     {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE},
499          *     {@link AudioAttributes#USAGE_NOTIFICATION_COMMUNICATION_REQUEST},
500          *     {@link AudioAttributes#USAGE_NOTIFICATION_COMMUNICATION_INSTANT},
501          *     {@link AudioAttributes#USAGE_NOTIFICATION_COMMUNICATION_DELAYED},
502          *     {@link AudioAttributes#USAGE_NOTIFICATION_EVENT},
503          *     {@link AudioAttributes#USAGE_ASSISTANT},
504          *     {@link AudioAttributes#USAGE_ASSISTANCE_ACCESSIBILITY},
505          *     {@link AudioAttributes#USAGE_ASSISTANCE_NAVIGATION_GUIDANCE},
506          *     {@link AudioAttributes#USAGE_ASSISTANCE_SONIFICATION},
507          *     {@link AudioAttributes#USAGE_GAME}.
508          * @return the same Builder instance.
509          */
setUsage(@ttributeUsage int usage)510         public Builder setUsage(@AttributeUsage int usage) {
511             switch (usage) {
512                 case USAGE_UNKNOWN:
513                 case USAGE_MEDIA:
514                 case USAGE_VOICE_COMMUNICATION:
515                 case USAGE_VOICE_COMMUNICATION_SIGNALLING:
516                 case USAGE_ALARM:
517                 case USAGE_NOTIFICATION:
518                 case USAGE_NOTIFICATION_RINGTONE:
519                 case USAGE_NOTIFICATION_COMMUNICATION_REQUEST:
520                 case USAGE_NOTIFICATION_COMMUNICATION_INSTANT:
521                 case USAGE_NOTIFICATION_COMMUNICATION_DELAYED:
522                 case USAGE_NOTIFICATION_EVENT:
523                 case USAGE_ASSISTANCE_ACCESSIBILITY:
524                 case USAGE_ASSISTANCE_NAVIGATION_GUIDANCE:
525                 case USAGE_ASSISTANCE_SONIFICATION:
526                 case USAGE_GAME:
527                 case USAGE_VIRTUAL_SOURCE:
528                 case USAGE_ASSISTANT:
529                      mUsage = usage;
530                      break;
531                 default:
532                      mUsage = USAGE_UNKNOWN;
533             }
534             return this;
535         }
536 
537         /**
538          * Sets the attribute describing the content type of the audio signal, such as speech,
539          * or music.
540          * @param contentType the content type values, one of
541          *     {@link AudioAttributes#CONTENT_TYPE_MOVIE},
542          *     {@link AudioAttributes#CONTENT_TYPE_MUSIC},
543          *     {@link AudioAttributes#CONTENT_TYPE_SONIFICATION},
544          *     {@link AudioAttributes#CONTENT_TYPE_SPEECH},
545          *     {@link AudioAttributes#CONTENT_TYPE_UNKNOWN}.
546          * @return the same Builder instance.
547          */
setContentType(@ttributeContentType int contentType)548         public Builder setContentType(@AttributeContentType int contentType) {
549             switch (contentType) {
550                 case CONTENT_TYPE_UNKNOWN:
551                 case CONTENT_TYPE_MOVIE:
552                 case CONTENT_TYPE_MUSIC:
553                 case CONTENT_TYPE_SONIFICATION:
554                 case CONTENT_TYPE_SPEECH:
555                      mContentType = contentType;
556                      break;
557                 default:
558                      mUsage = CONTENT_TYPE_UNKNOWN;
559             }
560             return this;
561         }
562 
563         /**
564          * Sets the combination of flags.
565          *
566          * This is a bitwise OR with the existing flags.
567          * @param flags a combination of {@link AudioAttributes#FLAG_AUDIBILITY_ENFORCED},
568          *    {@link AudioAttributes#FLAG_HW_AV_SYNC}.
569          * @return the same Builder instance.
570          */
setFlags(int flags)571         public Builder setFlags(int flags) {
572             flags &= AudioAttributes.FLAG_ALL;
573             mFlags |= flags;
574             return this;
575         }
576 
577         /**
578          * @hide
579          * Replaces flags.
580          * @param flags any combination of {@link AudioAttributes#FLAG_ALL}.
581          * @return the same Builder instance.
582          */
replaceFlags(int flags)583         public Builder replaceFlags(int flags) {
584             mFlags = flags & AudioAttributes.FLAG_ALL;
585             return this;
586         }
587 
588         /**
589          * @hide
590          * Adds a Bundle of data
591          * @param bundle a non-null Bundle
592          * @return the same builder instance
593          */
594         @SystemApi
addBundle(@onNull Bundle bundle)595         public Builder addBundle(@NonNull Bundle bundle) {
596             if (bundle == null) {
597                 throw new IllegalArgumentException("Illegal null bundle");
598             }
599             if (mBundle == null) {
600                 mBundle = new Bundle(bundle);
601             } else {
602                 mBundle.putAll(bundle);
603             }
604             return this;
605         }
606 
607         /**
608          * @hide
609          * Add a custom tag stored as a string
610          * @param tag
611          * @return the same Builder instance.
612          */
addTag(String tag)613         public Builder addTag(String tag) {
614             mTags.add(tag);
615             return this;
616         }
617 
618         /**
619          * Sets attributes as inferred from the legacy stream types.
620          * Use this method when building an {@link AudioAttributes} instance to initialize some of
621          * the attributes by information derived from a legacy stream type.
622          * @param streamType one of {@link AudioManager#STREAM_VOICE_CALL},
623          *   {@link AudioManager#STREAM_SYSTEM}, {@link AudioManager#STREAM_RING},
624          *   {@link AudioManager#STREAM_MUSIC}, {@link AudioManager#STREAM_ALARM},
625          *    or {@link AudioManager#STREAM_NOTIFICATION}.
626          * @return the same Builder instance.
627          */
setLegacyStreamType(int streamType)628         public Builder setLegacyStreamType(int streamType) {
629             if (streamType == AudioManager.STREAM_ACCESSIBILITY) {
630                 throw new IllegalArgumentException("STREAM_ACCESSIBILITY is not a legacy stream "
631                         + "type that was used for audio playback");
632             }
633             return setInternalLegacyStreamType(streamType);
634         }
635 
636         /**
637          * @hide
638          * For internal framework use only, enables building from hidden stream types.
639          * @param streamType
640          * @return the same Builder instance.
641          */
setInternalLegacyStreamType(int streamType)642         public Builder setInternalLegacyStreamType(int streamType) {
643             switch(streamType) {
644                 case AudioSystem.STREAM_VOICE_CALL:
645                     mContentType = CONTENT_TYPE_SPEECH;
646                     break;
647                 case AudioSystem.STREAM_SYSTEM_ENFORCED:
648                     mFlags |= FLAG_AUDIBILITY_ENFORCED;
649                     // intended fall through, attributes in common with STREAM_SYSTEM
650                 case AudioSystem.STREAM_SYSTEM:
651                     mContentType = CONTENT_TYPE_SONIFICATION;
652                     break;
653                 case AudioSystem.STREAM_RING:
654                     mContentType = CONTENT_TYPE_SONIFICATION;
655                     break;
656                 case AudioSystem.STREAM_MUSIC:
657                     mContentType = CONTENT_TYPE_MUSIC;
658                     break;
659                 case AudioSystem.STREAM_ALARM:
660                     mContentType = CONTENT_TYPE_SONIFICATION;
661                     break;
662                 case AudioSystem.STREAM_NOTIFICATION:
663                     mContentType = CONTENT_TYPE_SONIFICATION;
664                     break;
665                 case AudioSystem.STREAM_BLUETOOTH_SCO:
666                     mContentType = CONTENT_TYPE_SPEECH;
667                     mFlags |= FLAG_SCO;
668                     break;
669                 case AudioSystem.STREAM_DTMF:
670                     mContentType = CONTENT_TYPE_SONIFICATION;
671                     break;
672                 case AudioSystem.STREAM_TTS:
673                     mContentType = CONTENT_TYPE_SONIFICATION;
674                     break;
675                 case AudioSystem.STREAM_ACCESSIBILITY:
676                     mContentType = CONTENT_TYPE_SPEECH;
677                     break;
678                 default:
679                     Log.e(TAG, "Invalid stream type " + streamType + " for AudioAttributes");
680             }
681             mUsage = usageForStreamType(streamType);
682             return this;
683         }
684 
685         /**
686          * @hide
687          * Sets the capture preset.
688          * Use this audio attributes configuration method when building an {@link AudioRecord}
689          * instance with {@link AudioRecord#AudioRecord(AudioAttributes, AudioFormat, int)}.
690          * @param preset one of {@link MediaRecorder.AudioSource#DEFAULT},
691          *     {@link MediaRecorder.AudioSource#MIC}, {@link MediaRecorder.AudioSource#CAMCORDER},
692          *     {@link MediaRecorder.AudioSource#VOICE_RECOGNITION},
693          *     {@link MediaRecorder.AudioSource#VOICE_COMMUNICATION} or
694          *     {@link MediaRecorder.AudioSource#UNPROCESSED}
695          * @return the same Builder instance.
696          */
697         @SystemApi
setCapturePreset(int preset)698         public Builder setCapturePreset(int preset) {
699             switch (preset) {
700                 case MediaRecorder.AudioSource.DEFAULT:
701                 case MediaRecorder.AudioSource.MIC:
702                 case MediaRecorder.AudioSource.CAMCORDER:
703                 case MediaRecorder.AudioSource.VOICE_RECOGNITION:
704                 case MediaRecorder.AudioSource.VOICE_COMMUNICATION:
705                 case MediaRecorder.AudioSource.UNPROCESSED:
706                     mSource = preset;
707                     break;
708                 default:
709                     Log.e(TAG, "Invalid capture preset " + preset + " for AudioAttributes");
710             }
711             return this;
712         }
713 
714         /**
715          * @hide
716          * Same as {@link #setCapturePreset(int)} but authorizes the use of HOTWORD,
717          * REMOTE_SUBMIX and RADIO_TUNER.
718          * @param preset
719          * @return the same Builder instance.
720          */
721         @SystemApi
setInternalCapturePreset(int preset)722         public Builder setInternalCapturePreset(int preset) {
723             if ((preset == MediaRecorder.AudioSource.HOTWORD)
724                     || (preset == MediaRecorder.AudioSource.REMOTE_SUBMIX)
725                     || (preset == MediaRecorder.AudioSource.RADIO_TUNER)) {
726                 mSource = preset;
727             } else {
728                 setCapturePreset(preset);
729             }
730             return this;
731         }
732     };
733 
734     @Override
describeContents()735     public int describeContents() {
736         return 0;
737     }
738 
739     /**
740      * @hide
741      * Used to indicate that when parcelling, the tags should be parcelled through the flattened
742      * formatted string, not through the array of strings.
743      * Keep in sync with frameworks/av/media/libmediaplayerservice/MediaPlayerService.cpp
744      * see definition of kAudioAttributesMarshallTagFlattenTags
745      */
746     public final static int FLATTEN_TAGS = 0x1;
747 
748     private final static int ATTR_PARCEL_IS_NULL_BUNDLE = -1977;
749     private final static int ATTR_PARCEL_IS_VALID_BUNDLE = 1980;
750 
751     /**
752      * When adding tags for writeToParcel(Parcel, int), add them in the list of flags (| NEW_FLAG)
753      */
754     private final static int ALL_PARCEL_FLAGS = FLATTEN_TAGS;
755     @Override
writeToParcel(Parcel dest, int flags)756     public void writeToParcel(Parcel dest, int flags) {
757         dest.writeInt(mUsage);
758         dest.writeInt(mContentType);
759         dest.writeInt(mSource);
760         dest.writeInt(mFlags);
761         dest.writeInt(flags & ALL_PARCEL_FLAGS);
762         if ((flags & FLATTEN_TAGS) == 0) {
763             String[] tagsArray = new String[mTags.size()];
764             mTags.toArray(tagsArray);
765             dest.writeStringArray(tagsArray);
766         } else if ((flags & FLATTEN_TAGS) == FLATTEN_TAGS) {
767             dest.writeString(mFormattedTags);
768         }
769         if (mBundle == null) {
770             dest.writeInt(ATTR_PARCEL_IS_NULL_BUNDLE);
771         } else {
772             dest.writeInt(ATTR_PARCEL_IS_VALID_BUNDLE);
773             dest.writeBundle(mBundle);
774         }
775     }
776 
AudioAttributes(Parcel in)777     private AudioAttributes(Parcel in) {
778         mUsage = in.readInt();
779         mContentType = in.readInt();
780         mSource = in.readInt();
781         mFlags = in.readInt();
782         boolean hasFlattenedTags = ((in.readInt() & FLATTEN_TAGS) == FLATTEN_TAGS);
783         mTags = new HashSet<String>();
784         if (hasFlattenedTags) {
785             mFormattedTags = new String(in.readString());
786             mTags.add(mFormattedTags);
787         } else {
788             String[] tagsArray = in.readStringArray();
789             for (int i = tagsArray.length - 1 ; i >= 0 ; i--) {
790                 mTags.add(tagsArray[i]);
791             }
792             mFormattedTags = TextUtils.join(";", mTags);
793         }
794         switch (in.readInt()) {
795             case ATTR_PARCEL_IS_NULL_BUNDLE:
796                 mBundle = null;
797                 break;
798             case ATTR_PARCEL_IS_VALID_BUNDLE:
799                 mBundle = new Bundle(in.readBundle());
800                 break;
801             default:
802                 Log.e(TAG, "Illegal value unmarshalling AudioAttributes, can't initialize bundle");
803         }
804     }
805 
806     public static final Parcelable.Creator<AudioAttributes> CREATOR
807             = new Parcelable.Creator<AudioAttributes>() {
808         /**
809          * Rebuilds an AudioAttributes previously stored with writeToParcel().
810          * @param p Parcel object to read the AudioAttributes from
811          * @return a new AudioAttributes created from the data in the parcel
812          */
813         public AudioAttributes createFromParcel(Parcel p) {
814             return new AudioAttributes(p);
815         }
816         public AudioAttributes[] newArray(int size) {
817             return new AudioAttributes[size];
818         }
819     };
820 
821     @Override
equals(Object o)822     public boolean equals(Object o) {
823         if (this == o) return true;
824         if (o == null || getClass() != o.getClass()) return false;
825 
826         AudioAttributes that = (AudioAttributes) o;
827 
828         return ((mContentType == that.mContentType)
829                 && (mFlags == that.mFlags)
830                 && (mSource == that.mSource)
831                 && (mUsage == that.mUsage)
832                 //mFormattedTags is never null due to assignment in Builder or unmarshalling
833                 && (mFormattedTags.equals(that.mFormattedTags)));
834     }
835 
836     @Override
hashCode()837     public int hashCode() {
838         return Objects.hash(mContentType, mFlags, mSource, mUsage, mFormattedTags, mBundle);
839     }
840 
841     @Override
toString()842     public String toString () {
843         return new String("AudioAttributes:"
844                 + " usage=" + mUsage
845                 + " content=" + mContentType
846                 + " flags=0x" + Integer.toHexString(mFlags).toUpperCase()
847                 + " tags=" + mFormattedTags
848                 + " bundle=" + (mBundle == null ? "null" : mBundle.toString()));
849     }
850 
851     /** @hide */
usageToString()852     public String usageToString() {
853         return usageToString(mUsage);
854     }
855 
856     /** @hide */
usageToString(int usage)857     public static String usageToString(int usage) {
858         switch(usage) {
859             case USAGE_UNKNOWN:
860                 return new String("USAGE_UNKNOWN");
861             case USAGE_MEDIA:
862                 return new String("USAGE_MEDIA");
863             case USAGE_VOICE_COMMUNICATION:
864                 return new String("USAGE_VOICE_COMMUNICATION");
865             case USAGE_VOICE_COMMUNICATION_SIGNALLING:
866                 return new String("USAGE_VOICE_COMMUNICATION_SIGNALLING");
867             case USAGE_ALARM:
868                 return new String("USAGE_ALARM");
869             case USAGE_NOTIFICATION:
870                 return new String("USAGE_NOTIFICATION");
871             case USAGE_NOTIFICATION_RINGTONE:
872                 return new String("USAGE_NOTIFICATION_RINGTONE");
873             case USAGE_NOTIFICATION_COMMUNICATION_REQUEST:
874                 return new String("USAGE_NOTIFICATION_COMMUNICATION_REQUEST");
875             case USAGE_NOTIFICATION_COMMUNICATION_INSTANT:
876                 return new String("USAGE_NOTIFICATION_COMMUNICATION_INSTANT");
877             case USAGE_NOTIFICATION_COMMUNICATION_DELAYED:
878                 return new String("USAGE_NOTIFICATION_COMMUNICATION_DELAYED");
879             case USAGE_NOTIFICATION_EVENT:
880                 return new String("USAGE_NOTIFICATION_EVENT");
881             case USAGE_ASSISTANCE_ACCESSIBILITY:
882                 return new String("USAGE_ASSISTANCE_ACCESSIBILITY");
883             case USAGE_ASSISTANCE_NAVIGATION_GUIDANCE:
884                 return new String("USAGE_ASSISTANCE_NAVIGATION_GUIDANCE");
885             case USAGE_ASSISTANCE_SONIFICATION:
886                 return new String("USAGE_ASSISTANCE_SONIFICATION");
887             case USAGE_GAME:
888                 return new String("USAGE_GAME");
889             case USAGE_ASSISTANT:
890                 return new String("USAGE_ASSISTANT");
891             default:
892                 return new String("unknown usage " + usage);
893         }
894     }
895 
usageForStreamType(int streamType)896     private static int usageForStreamType(int streamType) {
897         switch(streamType) {
898             case AudioSystem.STREAM_VOICE_CALL:
899                 return USAGE_VOICE_COMMUNICATION;
900             case AudioSystem.STREAM_SYSTEM_ENFORCED:
901             case AudioSystem.STREAM_SYSTEM:
902                 return USAGE_ASSISTANCE_SONIFICATION;
903             case AudioSystem.STREAM_RING:
904                 return USAGE_NOTIFICATION_RINGTONE;
905             case AudioSystem.STREAM_MUSIC:
906                 return USAGE_MEDIA;
907             case AudioSystem.STREAM_ALARM:
908                 return USAGE_ALARM;
909             case AudioSystem.STREAM_NOTIFICATION:
910                 return USAGE_NOTIFICATION;
911             case AudioSystem.STREAM_BLUETOOTH_SCO:
912                 return USAGE_VOICE_COMMUNICATION;
913             case AudioSystem.STREAM_DTMF:
914                 return USAGE_VOICE_COMMUNICATION_SIGNALLING;
915             case AudioSystem.STREAM_ACCESSIBILITY:
916                 return USAGE_ASSISTANCE_ACCESSIBILITY;
917             case AudioSystem.STREAM_TTS:
918             default:
919                 return USAGE_UNKNOWN;
920         }
921     }
922 
923     /**
924      * Returns the stream type matching this {@code AudioAttributes} instance for volume control.
925      * Use this method to derive the stream type needed to configure the volume
926      * control slider in an {@link android.app.Activity} with
927      * {@link android.app.Activity#setVolumeControlStream(int)} for playback conducted with these
928      * attributes.
929      * <BR>Do not use this method to set the stream type on an audio player object
930      * (e.g. {@link AudioTrack}, {@link MediaPlayer}) as this is deprecated,
931      * use {@code AudioAttributes} instead.
932      * @return a valid stream type for {@code Activity} or stream volume control that matches
933      *     the attributes, or {@link AudioManager#USE_DEFAULT_STREAM_TYPE} if there isn't a direct
934      *     match. Note that {@code USE_DEFAULT_STREAM_TYPE} is not a valid value
935      *     for {@link AudioManager#setStreamVolume(int, int, int)}.
936      */
getVolumeControlStream()937     public int getVolumeControlStream() {
938         return toVolumeStreamType(true /*fromGetVolumeControlStream*/, this);
939     }
940 
941     /**
942      * @hide
943      * Only use to get which stream type should be used for volume control, NOT for audio playback
944      * (all audio playback APIs are supposed to take AudioAttributes as input parameters)
945      * @param aa non-null AudioAttributes.
946      * @return a valid stream type for volume control that matches the attributes.
947      */
toLegacyStreamType(@onNull AudioAttributes aa)948     public static int toLegacyStreamType(@NonNull AudioAttributes aa) {
949         return toVolumeStreamType(false /*fromGetVolumeControlStream*/, aa);
950     }
951 
toVolumeStreamType(boolean fromGetVolumeControlStream, AudioAttributes aa)952     private static int toVolumeStreamType(boolean fromGetVolumeControlStream, AudioAttributes aa) {
953         // flags to stream type mapping
954         if ((aa.getFlags() & FLAG_AUDIBILITY_ENFORCED) == FLAG_AUDIBILITY_ENFORCED) {
955             return fromGetVolumeControlStream ?
956                     AudioSystem.STREAM_SYSTEM : AudioSystem.STREAM_SYSTEM_ENFORCED;
957         }
958         if ((aa.getFlags() & FLAG_SCO) == FLAG_SCO) {
959             return fromGetVolumeControlStream ?
960                     AudioSystem.STREAM_VOICE_CALL : AudioSystem.STREAM_BLUETOOTH_SCO;
961         }
962 
963         // usage to stream type mapping
964         switch (aa.getUsage()) {
965             case USAGE_MEDIA:
966             case USAGE_GAME:
967             case USAGE_ASSISTANCE_NAVIGATION_GUIDANCE:
968             case USAGE_ASSISTANT:
969                 return AudioSystem.STREAM_MUSIC;
970             case USAGE_ASSISTANCE_SONIFICATION:
971                 return AudioSystem.STREAM_SYSTEM;
972             case USAGE_VOICE_COMMUNICATION:
973                 return AudioSystem.STREAM_VOICE_CALL;
974             case USAGE_VOICE_COMMUNICATION_SIGNALLING:
975                 return fromGetVolumeControlStream ?
976                         AudioSystem.STREAM_VOICE_CALL : AudioSystem.STREAM_DTMF;
977             case USAGE_ALARM:
978                 return AudioSystem.STREAM_ALARM;
979             case USAGE_NOTIFICATION_RINGTONE:
980                 return AudioSystem.STREAM_RING;
981             case USAGE_NOTIFICATION:
982             case USAGE_NOTIFICATION_COMMUNICATION_REQUEST:
983             case USAGE_NOTIFICATION_COMMUNICATION_INSTANT:
984             case USAGE_NOTIFICATION_COMMUNICATION_DELAYED:
985             case USAGE_NOTIFICATION_EVENT:
986                 return AudioSystem.STREAM_NOTIFICATION;
987             case USAGE_ASSISTANCE_ACCESSIBILITY:
988                 return AudioSystem.STREAM_ACCESSIBILITY;
989             case USAGE_UNKNOWN:
990                 return fromGetVolumeControlStream ?
991                         AudioManager.USE_DEFAULT_STREAM_TYPE : AudioSystem.STREAM_MUSIC;
992             default:
993                 if (fromGetVolumeControlStream) {
994                     throw new IllegalArgumentException("Unknown usage value " + aa.getUsage() +
995                             " in audio attributes");
996                 } else {
997                     return AudioSystem.STREAM_MUSIC;
998                 }
999         }
1000     }
1001 
1002     /** @hide */
1003     @IntDef({
1004         USAGE_UNKNOWN,
1005         USAGE_MEDIA,
1006         USAGE_VOICE_COMMUNICATION,
1007         USAGE_VOICE_COMMUNICATION_SIGNALLING,
1008         USAGE_ALARM,
1009         USAGE_NOTIFICATION,
1010         USAGE_NOTIFICATION_RINGTONE,
1011         USAGE_NOTIFICATION_COMMUNICATION_REQUEST,
1012         USAGE_NOTIFICATION_COMMUNICATION_INSTANT,
1013         USAGE_NOTIFICATION_COMMUNICATION_DELAYED,
1014         USAGE_NOTIFICATION_EVENT,
1015         USAGE_ASSISTANCE_ACCESSIBILITY,
1016         USAGE_ASSISTANCE_NAVIGATION_GUIDANCE,
1017         USAGE_ASSISTANCE_SONIFICATION,
1018         USAGE_GAME,
1019         USAGE_ASSISTANT,
1020     })
1021     @Retention(RetentionPolicy.SOURCE)
1022     public @interface AttributeUsage {}
1023 
1024     /** @hide */
1025     @IntDef({
1026         CONTENT_TYPE_UNKNOWN,
1027         CONTENT_TYPE_SPEECH,
1028         CONTENT_TYPE_MUSIC,
1029         CONTENT_TYPE_MOVIE,
1030         CONTENT_TYPE_SONIFICATION
1031     })
1032     @Retention(RetentionPolicy.SOURCE)
1033     public @interface AttributeContentType {}
1034 }
1035