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.RequiresPermission; 22 import android.annotation.SystemApi; 23 import android.annotation.TestApi; 24 import android.audio.policy.configuration.V7_0.AudioUsage; 25 import android.compat.annotation.UnsupportedAppUsage; 26 import android.media.audiopolicy.AudioProductStrategy; 27 import android.os.Build; 28 import android.os.Bundle; 29 import android.os.Parcel; 30 import android.os.Parcelable; 31 import android.text.TextUtils; 32 import android.util.Log; 33 import android.util.SparseIntArray; 34 import android.util.proto.ProtoOutputStream; 35 36 import java.lang.annotation.Retention; 37 import java.lang.annotation.RetentionPolicy; 38 import java.util.Collections; 39 import java.util.HashMap; 40 import java.util.HashSet; 41 import java.util.Map; 42 import java.util.Objects; 43 import java.util.Set; 44 45 /** 46 * A class to encapsulate a collection of attributes describing information about an audio 47 * stream. 48 * <p><code>AudioAttributes</code> supersede the notion of stream types (see for instance 49 * {@link AudioManager#STREAM_MUSIC} or {@link AudioManager#STREAM_ALARM}) for defining the 50 * behavior of audio playback. Attributes allow an application to specify more information than is 51 * conveyed in a stream type by allowing the application to define: 52 * <ul> 53 * <li>usage: "why" you are playing a sound, what is this sound used for. This is achieved with 54 * the "usage" information. Examples of usage are {@link #USAGE_MEDIA} and {@link #USAGE_ALARM}. 55 * These two examples are the closest to stream types, but more detailed use cases are 56 * available. Usage information is more expressive than a stream type, and allows certain 57 * platforms or routing policies to use this information for more refined volume or routing 58 * decisions. Usage is the most important information to supply in <code>AudioAttributes</code> 59 * and it is recommended to build any instance with this information supplied, see 60 * {@link AudioAttributes.Builder} for exceptions.</li> 61 * <li>content type: "what" you are playing. The content type expresses the general category of 62 * the content. This information is optional. But in case it is known (for instance 63 * {@link #CONTENT_TYPE_MOVIE} for a movie streaming service or {@link #CONTENT_TYPE_MUSIC} for 64 * a music playback application) this information might be used by the audio framework to 65 * selectively configure some audio post-processing blocks.</li> 66 * <li>flags: "how" is playback to be affected, see the flag definitions for the specific playback 67 * behaviors they control. </li> 68 * </ul> 69 * <p><code>AudioAttributes</code> are used for example in one of the {@link AudioTrack} 70 * constructors (see {@link AudioTrack#AudioTrack(AudioAttributes, AudioFormat, int, int, int)}), 71 * to configure a {@link MediaPlayer} 72 * (see {@link MediaPlayer#setAudioAttributes(AudioAttributes)} or a 73 * {@link android.app.Notification} (see {@link android.app.Notification#audioAttributes}). An 74 * <code>AudioAttributes</code> instance is built through its builder, 75 * {@link AudioAttributes.Builder}. 76 */ 77 public final class AudioAttributes implements Parcelable { 78 private final static String TAG = "AudioAttributes"; 79 80 /** 81 * Content type value to use when the content type is unknown, or other than the ones defined. 82 */ 83 public final static int CONTENT_TYPE_UNKNOWN = 0; 84 /** 85 * Content type value to use when the content type is speech. 86 */ 87 public final static int CONTENT_TYPE_SPEECH = 1; 88 /** 89 * Content type value to use when the content type is music. 90 */ 91 public final static int CONTENT_TYPE_MUSIC = 2; 92 /** 93 * Content type value to use when the content type is a soundtrack, typically accompanying 94 * a movie or TV program. 95 */ 96 public final static int CONTENT_TYPE_MOVIE = 3; 97 /** 98 * Content type value to use when the content type is a sound used to accompany a user 99 * action, such as a beep or sound effect expressing a key click, or event, such as the 100 * type of a sound for a bonus being received in a game. These sounds are mostly synthesized 101 * or short Foley sounds. 102 */ 103 public final static int CONTENT_TYPE_SONIFICATION = 4; 104 105 /** 106 * Invalid value, only ever used for an uninitialized usage value 107 */ 108 private static final int USAGE_INVALID = -1; 109 /** 110 * Usage value to use when the usage is unknown. 111 */ 112 public final static int USAGE_UNKNOWN = 0; 113 /** 114 * Usage value to use when the usage is media, such as music, or movie 115 * soundtracks. 116 */ 117 public final static int USAGE_MEDIA = 1; 118 /** 119 * Usage value to use when the usage is voice communications, such as telephony 120 * or VoIP. 121 */ 122 public final static int USAGE_VOICE_COMMUNICATION = 2; 123 /** 124 * Usage value to use when the usage is in-call signalling, such as with 125 * a "busy" beep, or DTMF tones. 126 */ 127 public final static int USAGE_VOICE_COMMUNICATION_SIGNALLING = 3; 128 /** 129 * Usage value to use when the usage is an alarm (e.g. wake-up alarm). 130 */ 131 public final static int USAGE_ALARM = 4; 132 /** 133 * Usage value to use when the usage is notification. See other 134 * notification usages for more specialized uses. 135 */ 136 public final static int USAGE_NOTIFICATION = 5; 137 /** 138 * Usage value to use when the usage is telephony ringtone. 139 */ 140 public final static int USAGE_NOTIFICATION_RINGTONE = 6; 141 /** 142 * Usage value to use when the usage is a request to enter/end a 143 * communication, such as a VoIP communication or video-conference. 144 */ 145 public final static int USAGE_NOTIFICATION_COMMUNICATION_REQUEST = 7; 146 /** 147 * Usage value to use when the usage is notification for an "instant" 148 * communication such as a chat, or SMS. 149 */ 150 public final static int USAGE_NOTIFICATION_COMMUNICATION_INSTANT = 8; 151 /** 152 * Usage value to use when the usage is notification for a 153 * non-immediate type of communication such as e-mail. 154 */ 155 public final static int USAGE_NOTIFICATION_COMMUNICATION_DELAYED = 9; 156 /** 157 * Usage value to use when the usage is to attract the user's attention, 158 * such as a reminder or low battery warning. 159 */ 160 public final static int USAGE_NOTIFICATION_EVENT = 10; 161 /** 162 * Usage value to use when the usage is for accessibility, such as with 163 * a screen reader. 164 */ 165 public final static int USAGE_ASSISTANCE_ACCESSIBILITY = 11; 166 /** 167 * Usage value to use when the usage is driving or navigation directions. 168 */ 169 public final static int USAGE_ASSISTANCE_NAVIGATION_GUIDANCE = 12; 170 /** 171 * Usage value to use when the usage is sonification, such as with user 172 * interface sounds. 173 */ 174 public final static int USAGE_ASSISTANCE_SONIFICATION = 13; 175 /** 176 * Usage value to use when the usage is for game audio. 177 */ 178 public final static int USAGE_GAME = 14; 179 /** 180 * @hide 181 * Usage value to use when feeding audio to the platform and replacing "traditional" audio 182 * source, such as audio capture devices. 183 */ 184 public final static int USAGE_VIRTUAL_SOURCE = 15; 185 /** 186 * Usage value to use for audio responses to user queries, audio instructions or help 187 * utterances. 188 */ 189 public final static int USAGE_ASSISTANT = 16; 190 /** 191 * @hide 192 * Usage value to use for assistant voice interaction with remote caller on Cell and VoIP calls. 193 */ 194 @SystemApi 195 @RequiresPermission(allOf = { 196 android.Manifest.permission.MODIFY_PHONE_STATE, 197 android.Manifest.permission.MODIFY_AUDIO_ROUTING 198 }) 199 public static final int USAGE_CALL_ASSISTANT = 17; 200 201 private static final int SYSTEM_USAGE_OFFSET = 1000; 202 203 /** 204 * @hide 205 * Usage value to use when the usage is an emergency. 206 */ 207 @SystemApi 208 @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) 209 public static final int USAGE_EMERGENCY = SYSTEM_USAGE_OFFSET; 210 /** 211 * @hide 212 * Usage value to use when the usage is a safety sound. 213 */ 214 @SystemApi 215 @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) 216 public static final int USAGE_SAFETY = SYSTEM_USAGE_OFFSET + 1; 217 /** 218 * @hide 219 * Usage value to use when the usage is a vehicle status. 220 */ 221 @SystemApi 222 @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) 223 public static final int USAGE_VEHICLE_STATUS = SYSTEM_USAGE_OFFSET + 2; 224 /** 225 * @hide 226 * Usage value to use when the usage is an announcement. 227 */ 228 @SystemApi 229 @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) 230 public static final int USAGE_ANNOUNCEMENT = SYSTEM_USAGE_OFFSET + 3; 231 232 /** 233 * IMPORTANT: when adding new usage types, add them to SDK_USAGES and update SUPPRESSIBLE_USAGES 234 * if applicable, as well as audioattributes.proto. 235 * Also consider adding them to <aaudio/AAudio.h> for the NDK. 236 * Also consider adding them to UsageTypeConverter for service dump and etc. 237 */ 238 239 /** 240 * @hide 241 * Denotes a usage for notifications that do not expect immediate intervention from the user, 242 * will be muted when the Zen mode disables notifications 243 * @see #SUPPRESSIBLE_USAGES 244 */ 245 public final static int SUPPRESSIBLE_NOTIFICATION = 1; 246 /** 247 * @hide 248 * Denotes a usage for notifications that do expect immediate intervention from the user, 249 * will be muted when the Zen mode disables calls 250 * @see #SUPPRESSIBLE_USAGES 251 */ 252 public final static int SUPPRESSIBLE_CALL = 2; 253 /** 254 * @hide 255 * Denotes a usage that is never going to be muted, even in Total Silence. 256 * @see #SUPPRESSIBLE_USAGES 257 */ 258 public final static int SUPPRESSIBLE_NEVER = 3; 259 /** 260 * @hide 261 * Denotes a usage for alarms, 262 * will be muted when the Zen mode priority doesn't allow alarms or in Alarms Only Mode 263 * @see #SUPPRESSIBLE_USAGES 264 */ 265 public final static int SUPPRESSIBLE_ALARM = 4; 266 /** 267 * @hide 268 * Denotes a usage for media, game, assistant, and navigation 269 * will be muted when the Zen priority mode doesn't allow media 270 * @see #SUPPRESSIBLE_USAGES 271 */ 272 public final static int SUPPRESSIBLE_MEDIA = 5; 273 /** 274 * @hide 275 * Denotes a usage for sounds not caught in SUPPRESSIBLE_NOTIFICATION, 276 * SUPPRESSIBLE_CALL,SUPPRESSIBLE_NEVER, SUPPRESSIBLE_ALARM or SUPPRESSIBLE_MEDIA. 277 * This includes sonification sounds. 278 * These will be muted when the Zen priority mode doesn't allow system sounds 279 * @see #SUPPRESSIBLE_USAGES 280 */ 281 public final static int SUPPRESSIBLE_SYSTEM = 6; 282 283 /** 284 * @hide 285 * Array of all usage types for calls and notifications to assign the suppression behavior, 286 * used by the Zen mode restrictions. 287 * @see com.android.server.notification.ZenModeHelper 288 */ 289 public static final SparseIntArray SUPPRESSIBLE_USAGES; 290 291 static { 292 SUPPRESSIBLE_USAGES = new SparseIntArray(); SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION, SUPPRESSIBLE_NOTIFICATION)293 SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION, SUPPRESSIBLE_NOTIFICATION); SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_RINGTONE, SUPPRESSIBLE_CALL)294 SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_RINGTONE, SUPPRESSIBLE_CALL); SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_REQUEST,SUPPRESSIBLE_CALL)295 SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_REQUEST,SUPPRESSIBLE_CALL); SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_INSTANT,SUPPRESSIBLE_NOTIFICATION)296 SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_INSTANT,SUPPRESSIBLE_NOTIFICATION); SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_DELAYED,SUPPRESSIBLE_NOTIFICATION)297 SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_COMMUNICATION_DELAYED,SUPPRESSIBLE_NOTIFICATION); SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_EVENT, SUPPRESSIBLE_NOTIFICATION)298 SUPPRESSIBLE_USAGES.put(USAGE_NOTIFICATION_EVENT, SUPPRESSIBLE_NOTIFICATION); SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANCE_ACCESSIBILITY, SUPPRESSIBLE_NEVER)299 SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANCE_ACCESSIBILITY, SUPPRESSIBLE_NEVER); SUPPRESSIBLE_USAGES.put(USAGE_VOICE_COMMUNICATION, SUPPRESSIBLE_NEVER)300 SUPPRESSIBLE_USAGES.put(USAGE_VOICE_COMMUNICATION, SUPPRESSIBLE_NEVER); SUPPRESSIBLE_USAGES.put(USAGE_VOICE_COMMUNICATION_SIGNALLING, SUPPRESSIBLE_NEVER)301 SUPPRESSIBLE_USAGES.put(USAGE_VOICE_COMMUNICATION_SIGNALLING, SUPPRESSIBLE_NEVER); SUPPRESSIBLE_USAGES.put(USAGE_ALARM, SUPPRESSIBLE_ALARM)302 SUPPRESSIBLE_USAGES.put(USAGE_ALARM, SUPPRESSIBLE_ALARM); SUPPRESSIBLE_USAGES.put(USAGE_MEDIA, SUPPRESSIBLE_MEDIA)303 SUPPRESSIBLE_USAGES.put(USAGE_MEDIA, SUPPRESSIBLE_MEDIA); SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANCE_NAVIGATION_GUIDANCE, SUPPRESSIBLE_MEDIA)304 SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANCE_NAVIGATION_GUIDANCE, SUPPRESSIBLE_MEDIA); SUPPRESSIBLE_USAGES.put(USAGE_GAME, SUPPRESSIBLE_MEDIA)305 SUPPRESSIBLE_USAGES.put(USAGE_GAME, SUPPRESSIBLE_MEDIA); SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANT, SUPPRESSIBLE_MEDIA)306 SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANT, SUPPRESSIBLE_MEDIA); SUPPRESSIBLE_USAGES.put(USAGE_CALL_ASSISTANT, SUPPRESSIBLE_NEVER)307 SUPPRESSIBLE_USAGES.put(USAGE_CALL_ASSISTANT, SUPPRESSIBLE_NEVER); 308 /** default volume assignment is STREAM_MUSIC, handle unknown usage as media */ SUPPRESSIBLE_USAGES.put(USAGE_UNKNOWN, SUPPRESSIBLE_MEDIA)309 SUPPRESSIBLE_USAGES.put(USAGE_UNKNOWN, SUPPRESSIBLE_MEDIA); SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANCE_SONIFICATION, SUPPRESSIBLE_SYSTEM)310 SUPPRESSIBLE_USAGES.put(USAGE_ASSISTANCE_SONIFICATION, SUPPRESSIBLE_SYSTEM); 311 } 312 313 /** 314 * @hide 315 * Array of all usage types exposed in the SDK that applications can use. 316 */ 317 public final static int[] SDK_USAGES = { 318 USAGE_UNKNOWN, 319 USAGE_MEDIA, 320 USAGE_VOICE_COMMUNICATION, 321 USAGE_VOICE_COMMUNICATION_SIGNALLING, 322 USAGE_ALARM, 323 USAGE_NOTIFICATION, 324 USAGE_NOTIFICATION_RINGTONE, 325 USAGE_NOTIFICATION_COMMUNICATION_REQUEST, 326 USAGE_NOTIFICATION_COMMUNICATION_INSTANT, 327 USAGE_NOTIFICATION_COMMUNICATION_DELAYED, 328 USAGE_NOTIFICATION_EVENT, 329 USAGE_ASSISTANCE_ACCESSIBILITY, 330 USAGE_ASSISTANCE_NAVIGATION_GUIDANCE, 331 USAGE_ASSISTANCE_SONIFICATION, 332 USAGE_GAME, 333 USAGE_ASSISTANT, 334 }; 335 336 /** 337 * Flag defining a behavior where the audibility of the sound will be ensured by the system. 338 */ 339 public final static int FLAG_AUDIBILITY_ENFORCED = 0x1 << 0; 340 /** 341 * @hide 342 * Flag defining a behavior where the playback of the sound is ensured without 343 * degradation only when going to a secure sink. 344 */ 345 // FIXME not guaranteed yet 346 // TODO add in FLAG_ALL_PUBLIC when supported and in public API 347 public final static int FLAG_SECURE = 0x1 << 1; 348 /** 349 * @hide 350 * Flag to enable when the stream is associated with SCO usage. 351 * Internal use only for dealing with legacy STREAM_BLUETOOTH_SCO 352 */ 353 public final static int FLAG_SCO = 0x1 << 2; 354 /** 355 * @hide 356 * Flag defining a behavior where the system ensures that the playback of the sound will 357 * be compatible with its use as a broadcast for surrounding people and/or devices. 358 * Ensures audibility with no or minimal post-processing applied. 359 */ 360 @SystemApi 361 public final static int FLAG_BEACON = 0x1 << 3; 362 363 /** 364 * Flag requesting the use of an output stream supporting hardware A/V synchronization. 365 */ 366 public final static int FLAG_HW_AV_SYNC = 0x1 << 4; 367 368 /** 369 * @hide 370 * Flag requesting capture from the source used for hardware hotword detection. 371 * To be used with capture preset MediaRecorder.AudioSource.HOTWORD or 372 * MediaRecorder.AudioSource.VOICE_RECOGNITION. 373 */ 374 @SystemApi 375 public final static int FLAG_HW_HOTWORD = 0x1 << 5; 376 377 /** 378 * @hide 379 * Flag requesting audible playback even under limited interruptions. 380 */ 381 @SystemApi 382 public final static int FLAG_BYPASS_INTERRUPTION_POLICY = 0x1 << 6; 383 384 /** 385 * @hide 386 * Flag requesting audible playback even when the underlying stream is muted. 387 */ 388 @SystemApi 389 public final static int FLAG_BYPASS_MUTE = 0x1 << 7; 390 391 /** 392 * Flag requesting a low latency path when creating an AudioTrack. 393 * When using this flag, the sample rate must match the native sample rate 394 * of the device. Effects processing is also unavailable. 395 * 396 * Note that if this flag is used without specifying a bufferSizeInBytes then the 397 * AudioTrack's actual buffer size may be too small. It is recommended that a fairly 398 * large buffer should be specified when the AudioTrack is created. 399 * Then the actual size can be reduced by calling 400 * {@link AudioTrack#setBufferSizeInFrames(int)}. The buffer size can be optimized 401 * by lowering it after each write() call until the audio glitches, which is detected by calling 402 * {@link AudioTrack#getUnderrunCount()}. Then the buffer size can be increased 403 * until there are no glitches. 404 * This tuning step should be done while playing silence. 405 * This technique provides a compromise between latency and glitch rate. 406 * 407 * @deprecated Use {@link AudioTrack.Builder#setPerformanceMode(int)} with 408 * {@link AudioTrack#PERFORMANCE_MODE_LOW_LATENCY} to control performance. 409 */ 410 public final static int FLAG_LOW_LATENCY = 0x1 << 8; 411 412 /** 413 * @hide 414 * Flag requesting a deep buffer path when creating an {@code AudioTrack}. 415 * 416 * A deep buffer path, if available, may consume less power and is 417 * suitable for media playback where latency is not a concern. 418 * Use {@link AudioTrack.Builder#setPerformanceMode(int)} with 419 * {@link AudioTrack#PERFORMANCE_MODE_POWER_SAVING} to enable. 420 */ 421 public final static int FLAG_DEEP_BUFFER = 0x1 << 9; 422 423 /** 424 * @hide 425 * Flag specifying that the audio shall not be captured by third-party apps 426 * with a MediaProjection. 427 */ 428 public static final int FLAG_NO_MEDIA_PROJECTION = 0x1 << 10; 429 430 /** 431 * @hide 432 * Flag indicating force muting haptic channels. 433 */ 434 public static final int FLAG_MUTE_HAPTIC = 0x1 << 11; 435 436 /** 437 * @hide 438 * Flag specifying that the audio shall not be captured by any apps, not even system apps. 439 */ 440 public static final int FLAG_NO_SYSTEM_CAPTURE = 0x1 << 12; 441 442 /** 443 * @hide 444 * Flag requesting private audio capture. When set in audio attributes passed to an 445 * AudioRecord, this prevents a privileged Assistant from capturing audio while this 446 * AudioRecord is active. 447 */ 448 public static final int FLAG_CAPTURE_PRIVATE = 0x1 << 13; 449 450 /** 451 * @hide 452 * Flag indicating the audio content has been processed to provide a virtual multichannel 453 * audio experience 454 */ 455 public static final int FLAG_CONTENT_SPATIALIZED = 0x1 << 14; 456 457 /** 458 * @hide 459 * Flag indicating the audio content is to never be spatialized 460 */ 461 public static final int FLAG_NEVER_SPATIALIZE = 0x1 << 15; 462 463 // Note that even though FLAG_MUTE_HAPTIC is stored as a flag bit, it is not here since 464 // it is known as a boolean value outside of AudioAttributes. 465 private static final int FLAG_ALL = FLAG_AUDIBILITY_ENFORCED | FLAG_SECURE | FLAG_SCO 466 | FLAG_BEACON | FLAG_HW_AV_SYNC | FLAG_HW_HOTWORD | FLAG_BYPASS_INTERRUPTION_POLICY 467 | FLAG_BYPASS_MUTE | FLAG_LOW_LATENCY | FLAG_DEEP_BUFFER | FLAG_NO_MEDIA_PROJECTION 468 | FLAG_NO_SYSTEM_CAPTURE | FLAG_CAPTURE_PRIVATE | FLAG_CONTENT_SPATIALIZED 469 | FLAG_NEVER_SPATIALIZE; 470 private final static int FLAG_ALL_PUBLIC = FLAG_AUDIBILITY_ENFORCED | 471 FLAG_HW_AV_SYNC | FLAG_LOW_LATENCY; 472 /* mask of flags that can be set by SDK and System APIs through the Builder */ 473 private static final int FLAG_ALL_API_SET = FLAG_ALL_PUBLIC 474 | FLAG_BYPASS_INTERRUPTION_POLICY 475 | FLAG_BYPASS_MUTE; 476 477 /** 478 * Indicates that the audio may be captured by any app. 479 * 480 * For privacy, the following usages cannot be recorded: VOICE_COMMUNICATION*, 481 * USAGE_NOTIFICATION*, USAGE_ASSISTANCE* and USAGE_ASSISTANT. 482 * 483 * On {@link android.os.Build.VERSION_CODES#Q}, this means only {@link #USAGE_UNKNOWN}, 484 * {@link #USAGE_MEDIA} and {@link #USAGE_GAME} may be captured. 485 * 486 * See {@link android.media.projection.MediaProjection} and 487 * {@link Builder#setAllowedCapturePolicy}. 488 */ 489 public static final int ALLOW_CAPTURE_BY_ALL = 1; 490 /** 491 * Indicates that the audio may only be captured by system apps. 492 * 493 * System apps can capture for many purposes like accessibility, live captions, user guidance... 494 * but abide to the following restrictions: 495 * - the audio cannot leave the device 496 * - the audio cannot be passed to a third party app 497 * - the audio cannot be recorded at a higher quality than 16kHz 16bit mono 498 * 499 * See {@link Builder#setAllowedCapturePolicy}. 500 */ 501 public static final int ALLOW_CAPTURE_BY_SYSTEM = 2; 502 /** 503 * Indicates that the audio is not to be recorded by any app, even if it is a system app. 504 * 505 * It is encouraged to use {@link #ALLOW_CAPTURE_BY_SYSTEM} instead of this value as system apps 506 * provide significant and useful features for the user (such as live captioning 507 * and accessibility). 508 * 509 * See {@link Builder#setAllowedCapturePolicy}. 510 */ 511 public static final int ALLOW_CAPTURE_BY_NONE = 3; 512 513 /** @hide */ 514 @IntDef({ 515 ALLOW_CAPTURE_BY_ALL, 516 ALLOW_CAPTURE_BY_SYSTEM, 517 ALLOW_CAPTURE_BY_NONE, 518 }) 519 @Retention(RetentionPolicy.SOURCE) 520 public @interface CapturePolicy {} 521 522 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 523 private int mUsage = USAGE_UNKNOWN; 524 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023) 525 private int mContentType = CONTENT_TYPE_UNKNOWN; 526 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023) 527 private int mSource = MediaRecorder.AudioSource.AUDIO_SOURCE_INVALID; 528 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023) 529 private int mFlags = 0x0; 530 private HashSet<String> mTags; 531 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 532 private String mFormattedTags; 533 private Bundle mBundle; // lazy-initialized, may be null 534 AudioAttributes()535 private AudioAttributes() { 536 } 537 538 /** 539 * Return the content type. 540 * @return one of the values that can be set in {@link Builder#setContentType(int)} 541 */ getContentType()542 public int getContentType() { 543 return mContentType; 544 } 545 546 /** 547 * Return the usage. 548 * @return one of the values that can be set in {@link Builder#setUsage(int)} 549 */ getUsage()550 public int getUsage() { 551 if (isSystemUsage(mUsage)) { 552 return USAGE_UNKNOWN; 553 } 554 return mUsage; 555 } 556 557 /** 558 * @hide 559 * Return the system usage. 560 * @return one of the values that can be set in {@link Builder#setUsage(int)} or 561 * {@link Builder#setSystemUsage(int)} 562 */ 563 @SystemApi getSystemUsage()564 public int getSystemUsage() { 565 return mUsage; 566 } 567 568 /** 569 * @hide 570 * Return the capture preset. 571 * @return one of the values that can be set in {@link Builder#setCapturePreset(int)} or a 572 * negative value if none has been set. 573 */ 574 @SystemApi getCapturePreset()575 public int getCapturePreset() { 576 return mSource; 577 } 578 579 /** 580 * Return the flags. 581 * @return a combined mask of all flags 582 */ getFlags()583 public int getFlags() { 584 // only return the flags that are public 585 return (mFlags & (FLAG_ALL_PUBLIC)); 586 } 587 588 /** 589 * @hide 590 * Return all the flags, even the non-public ones. 591 * Internal use only 592 * @return a combined mask of all flags 593 */ 594 @SystemApi getAllFlags()595 public int getAllFlags() { 596 return (mFlags & FLAG_ALL); 597 } 598 599 /** 600 * @hide 601 * Return the Bundle of data. 602 * @return a copy of the Bundle for this instance, may be null. 603 */ 604 @SystemApi getBundle()605 public Bundle getBundle() { 606 if (mBundle == null) { 607 return mBundle; 608 } else { 609 return new Bundle(mBundle); 610 } 611 } 612 613 /** 614 * @hide 615 * Return the set of tags. 616 * @return a read-only set of all tags stored as strings. 617 */ getTags()618 public Set<String> getTags() { 619 return Collections.unmodifiableSet(mTags); 620 } 621 622 /** 623 * Return if haptic channels are muted. 624 * @return {@code true} if haptic channels are muted, {@code false} otherwise. 625 */ areHapticChannelsMuted()626 public boolean areHapticChannelsMuted() { 627 return (mFlags & FLAG_MUTE_HAPTIC) != 0; 628 } 629 630 /** 631 * Return true if the audio content associated with these attributes has already been 632 * spatialized, that is it has already been processed to offer a binaural or transaural 633 * immersive audio experience. 634 * @return {@code true} if the content has been processed 635 */ isContentSpatialized()636 public boolean isContentSpatialized() { 637 return (mFlags & FLAG_CONTENT_SPATIALIZED) != 0; 638 } 639 640 /** @hide */ 641 @IntDef(flag = false, value = { 642 SPATIALIZATION_BEHAVIOR_AUTO, 643 SPATIALIZATION_BEHAVIOR_NEVER, 644 }) 645 @Retention(RetentionPolicy.SOURCE) 646 public @interface SpatializationBehavior {}; 647 648 /** 649 * Constant indicating the audio content associated with these attributes will follow the 650 * default platform behavior with regards to which content will be spatialized or not. 651 * @see #getSpatializationBehavior() 652 * @see Spatializer 653 */ 654 public static final int SPATIALIZATION_BEHAVIOR_AUTO = 0; 655 656 /** 657 * Constant indicating the audio content associated with these attributes should never 658 * be virtualized. 659 * @see #getSpatializationBehavior() 660 * @see Spatializer 661 */ 662 public static final int SPATIALIZATION_BEHAVIOR_NEVER = 1; 663 664 /** 665 * Return the behavior affecting whether spatialization will be used. 666 * @return the spatialization behavior 667 */ getSpatializationBehavior()668 public @SpatializationBehavior int getSpatializationBehavior() { 669 return ((mFlags & FLAG_NEVER_SPATIALIZE) != 0) 670 ? SPATIALIZATION_BEHAVIOR_NEVER : SPATIALIZATION_BEHAVIOR_AUTO; 671 } 672 673 /** 674 * Return the capture policy. 675 * @return the capture policy set by {@link Builder#setAllowedCapturePolicy(int)} or 676 * the default if it was not called. 677 */ 678 @CapturePolicy getAllowedCapturePolicy()679 public int getAllowedCapturePolicy() { 680 if ((mFlags & FLAG_NO_SYSTEM_CAPTURE) == FLAG_NO_SYSTEM_CAPTURE) { 681 return ALLOW_CAPTURE_BY_NONE; 682 } 683 if ((mFlags & FLAG_NO_MEDIA_PROJECTION) == FLAG_NO_MEDIA_PROJECTION) { 684 return ALLOW_CAPTURE_BY_SYSTEM; 685 } 686 return ALLOW_CAPTURE_BY_ALL; 687 } 688 689 690 /** 691 * Builder class for {@link AudioAttributes} objects. 692 * <p> Here is an example where <code>Builder</code> is used to define the 693 * {@link AudioAttributes} to be used by a new <code>AudioTrack</code> instance: 694 * 695 * <pre class="prettyprint"> 696 * AudioTrack myTrack = new AudioTrack( 697 * new AudioAttributes.Builder() 698 * .setUsage(AudioAttributes.USAGE_MEDIA) 699 * .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC) 700 * .build(), 701 * myFormat, myBuffSize, AudioTrack.MODE_STREAM, mySession); 702 * </pre> 703 * 704 * <p>By default all types of information (usage, content type, flags) conveyed by an 705 * <code>AudioAttributes</code> instance are set to "unknown". Unknown information will be 706 * interpreted as a default value that is dependent on the context of use, for instance a 707 * {@link MediaPlayer} will use a default usage of {@link AudioAttributes#USAGE_MEDIA}. 708 */ 709 public static class Builder { 710 private int mUsage = USAGE_INVALID; 711 private int mSystemUsage = USAGE_INVALID; 712 private int mContentType = CONTENT_TYPE_UNKNOWN; 713 private int mSource = MediaRecorder.AudioSource.AUDIO_SOURCE_INVALID; 714 private int mFlags = 0x0; 715 private boolean mMuteHapticChannels = true; 716 private boolean mIsContentSpatialized = false; 717 private int mSpatializationBehavior = SPATIALIZATION_BEHAVIOR_AUTO; 718 private HashSet<String> mTags = new HashSet<String>(); 719 private Bundle mBundle; 720 private int mPrivacySensitive = PRIVACY_SENSITIVE_DEFAULT; 721 722 private static final int PRIVACY_SENSITIVE_DEFAULT = -1; 723 private static final int PRIVACY_SENSITIVE_DISABLED = 0; 724 private static final int PRIVACY_SENSITIVE_ENABLED = 1; 725 726 /** 727 * Constructs a new Builder with the defaults. 728 * By default, usage and content type are respectively {@link AudioAttributes#USAGE_UNKNOWN} 729 * and {@link AudioAttributes#CONTENT_TYPE_UNKNOWN}, and flags are 0. It is recommended to 730 * configure the usage (with {@link #setUsage(int)}) or deriving attributes from a legacy 731 * stream type (with {@link #setLegacyStreamType(int)}) before calling {@link #build()} 732 * to override any default playback behavior in terms of routing and volume management. 733 */ Builder()734 public Builder() { 735 } 736 737 /** 738 * Constructs a new Builder from a given AudioAttributes 739 * @param aa the AudioAttributes object whose data will be reused in the new Builder. 740 */ 741 @SuppressWarnings("unchecked") // for cloning of mTags Builder(AudioAttributes aa)742 public Builder(AudioAttributes aa) { 743 mUsage = aa.mUsage; 744 mContentType = aa.mContentType; 745 mFlags = aa.getAllFlags(); 746 mTags = (HashSet<String>) aa.mTags.clone(); 747 mMuteHapticChannels = aa.areHapticChannelsMuted(); 748 mIsContentSpatialized = aa.isContentSpatialized(); 749 mSpatializationBehavior = aa.getSpatializationBehavior(); 750 } 751 752 /** 753 * Combines all of the attributes that have been set and return a new 754 * {@link AudioAttributes} object. 755 * @return a new {@link AudioAttributes} object 756 */ 757 @SuppressWarnings("unchecked") // for cloning of mTags build()758 public AudioAttributes build() { 759 AudioAttributes aa = new AudioAttributes(); 760 aa.mContentType = mContentType; 761 762 if (mUsage == USAGE_INVALID) { 763 if (mSystemUsage == USAGE_INVALID) { 764 aa.mUsage = USAGE_UNKNOWN; 765 } else { 766 aa.mUsage = mSystemUsage; 767 } 768 } else { 769 if (mSystemUsage == USAGE_INVALID) { 770 aa.mUsage = mUsage; 771 } else { 772 throw new IllegalArgumentException( 773 "Cannot set both usage and system usage on same builder"); 774 } 775 } 776 777 aa.mSource = mSource; 778 aa.mFlags = mFlags; 779 if (mMuteHapticChannels) { 780 aa.mFlags |= FLAG_MUTE_HAPTIC; 781 } 782 if (mIsContentSpatialized) { 783 aa.mFlags |= FLAG_CONTENT_SPATIALIZED; 784 } 785 if (mSpatializationBehavior == SPATIALIZATION_BEHAVIOR_NEVER) { 786 aa.mFlags |= FLAG_NEVER_SPATIALIZE; 787 } 788 789 if (mPrivacySensitive == PRIVACY_SENSITIVE_DEFAULT) { 790 // capturing for camcorder or communication is private by default to 791 // reflect legacy behavior 792 if (mSource == MediaRecorder.AudioSource.VOICE_COMMUNICATION 793 || mSource == MediaRecorder.AudioSource.CAMCORDER) { 794 aa.mFlags |= FLAG_CAPTURE_PRIVATE; 795 } else { 796 aa.mFlags &= ~FLAG_CAPTURE_PRIVATE; 797 } 798 } else if (mPrivacySensitive == PRIVACY_SENSITIVE_ENABLED) { 799 aa.mFlags |= FLAG_CAPTURE_PRIVATE; 800 } else { 801 aa.mFlags &= ~FLAG_CAPTURE_PRIVATE; 802 } 803 aa.mTags = (HashSet<String>) mTags.clone(); 804 aa.mFormattedTags = TextUtils.join(";", mTags); 805 if (mBundle != null) { 806 aa.mBundle = new Bundle(mBundle); 807 } 808 809 // Allow the FLAG_HW_HOTWORD only for AudioSource.VOICE_RECOGNITION 810 if (mSource != MediaRecorder.AudioSource.VOICE_RECOGNITION 811 && (mFlags & FLAG_HW_HOTWORD) == FLAG_HW_HOTWORD) { 812 aa.mFlags &= ~FLAG_HW_HOTWORD; 813 } 814 815 return aa; 816 } 817 818 /** 819 * Sets the attribute describing what is the intended use of the audio signal, 820 * such as alarm or ringtone. 821 * @param usage one of {@link AttributeSdkUsage#USAGE_UNKNOWN}, 822 * {@link AttributeSdkUsage#USAGE_MEDIA}, 823 * {@link AttributeSdkUsage#USAGE_VOICE_COMMUNICATION}, 824 * {@link AttributeSdkUsage#USAGE_VOICE_COMMUNICATION_SIGNALLING}, 825 * {@link AttributeSdkUsage#USAGE_ALARM}, {@link AudioAttributes#USAGE_NOTIFICATION}, 826 * {@link AttributeSdkUsage#USAGE_NOTIFICATION_RINGTONE}, 827 * {@link AttributeSdkUsage#USAGE_NOTIFICATION_COMMUNICATION_REQUEST}, 828 * {@link AttributeSdkUsage#USAGE_NOTIFICATION_COMMUNICATION_INSTANT}, 829 * {@link AttributeSdkUsage#USAGE_NOTIFICATION_COMMUNICATION_DELAYED}, 830 * {@link AttributeSdkUsage#USAGE_NOTIFICATION_EVENT}, 831 * {@link AttributeSdkUsage#USAGE_ASSISTANT}, 832 * {@link AttributeSdkUsage#USAGE_ASSISTANCE_ACCESSIBILITY}, 833 * {@link AttributeSdkUsage#USAGE_ASSISTANCE_NAVIGATION_GUIDANCE}, 834 * {@link AttributeSdkUsage#USAGE_ASSISTANCE_SONIFICATION}, 835 * {@link AttributeSdkUsage#USAGE_GAME}. 836 * @return the same Builder instance. 837 */ setUsage(@ttributeSdkUsage int usage)838 public Builder setUsage(@AttributeSdkUsage int usage) { 839 switch (usage) { 840 case USAGE_UNKNOWN: 841 case USAGE_MEDIA: 842 case USAGE_VOICE_COMMUNICATION: 843 case USAGE_VOICE_COMMUNICATION_SIGNALLING: 844 case USAGE_ALARM: 845 case USAGE_NOTIFICATION: 846 case USAGE_NOTIFICATION_RINGTONE: 847 case USAGE_NOTIFICATION_COMMUNICATION_REQUEST: 848 case USAGE_NOTIFICATION_COMMUNICATION_INSTANT: 849 case USAGE_NOTIFICATION_COMMUNICATION_DELAYED: 850 case USAGE_NOTIFICATION_EVENT: 851 case USAGE_ASSISTANCE_ACCESSIBILITY: 852 case USAGE_ASSISTANCE_NAVIGATION_GUIDANCE: 853 case USAGE_ASSISTANCE_SONIFICATION: 854 case USAGE_GAME: 855 case USAGE_VIRTUAL_SOURCE: 856 case USAGE_ASSISTANT: 857 mUsage = usage; 858 break; 859 default: 860 throw new IllegalArgumentException("Invalid usage " + usage); 861 } 862 return this; 863 } 864 865 /** 866 * @hide 867 * Sets the attribute describing what is the intended use of the audio signal for categories 868 * of sounds restricted to the system, such as vehicle status or emergency. 869 * 870 * <p>Note that the AudioAttributes have a single usage value, therefore it is illegal to 871 * call both this method and {@link #setUsage(int)}. 872 * @param systemUsage the system-restricted usage. 873 * @return the same Builder instance. 874 */ 875 @SystemApi 876 @RequiresPermission(android.Manifest.permission.MODIFY_AUDIO_ROUTING) setSystemUsage(@ttributeSystemUsage int systemUsage)877 public @NonNull Builder setSystemUsage(@AttributeSystemUsage int systemUsage) { 878 if (isSystemUsage(systemUsage)) { 879 mSystemUsage = systemUsage; 880 } else { 881 throw new IllegalArgumentException("Invalid system usage " + systemUsage); 882 } 883 884 return this; 885 } 886 887 /** 888 * Sets the attribute describing the content type of the audio signal, such as speech, 889 * or music. 890 * @param contentType the content type values, one of 891 * {@link AudioAttributes#CONTENT_TYPE_MOVIE}, 892 * {@link AudioAttributes#CONTENT_TYPE_MUSIC}, 893 * {@link AudioAttributes#CONTENT_TYPE_SONIFICATION}, 894 * {@link AudioAttributes#CONTENT_TYPE_SPEECH}, 895 * {@link AudioAttributes#CONTENT_TYPE_UNKNOWN}. 896 * @return the same Builder instance. 897 */ setContentType(@ttributeContentType int contentType)898 public Builder setContentType(@AttributeContentType int contentType) { 899 switch (contentType) { 900 case CONTENT_TYPE_UNKNOWN: 901 case CONTENT_TYPE_MOVIE: 902 case CONTENT_TYPE_MUSIC: 903 case CONTENT_TYPE_SONIFICATION: 904 case CONTENT_TYPE_SPEECH: 905 mContentType = contentType; 906 break; 907 default: 908 throw new IllegalArgumentException("Invalid content type " + contentType); 909 } 910 return this; 911 } 912 913 /** 914 * Sets the combination of flags. 915 * 916 * This is a bitwise OR with the existing flags. 917 * @param flags a combination of {@link AudioAttributes#FLAG_AUDIBILITY_ENFORCED}, 918 * {@link AudioAttributes#FLAG_HW_AV_SYNC}. 919 * @return the same Builder instance. 920 */ setFlags(int flags)921 public Builder setFlags(int flags) { 922 flags &= AudioAttributes.FLAG_ALL_API_SET; 923 mFlags |= flags; 924 return this; 925 } 926 927 /** 928 * @hide 929 * Request for capture in hotword mode. 930 * 931 * Requests an audio path optimized for Hotword detection use cases from 932 * the low power audio DSP. This is valid only for capture with 933 * audio source {@link MediaRecorder.AudioSource#VOICE_RECOGNITION}. 934 * There is no guarantee that this mode is available on the device. 935 * @return the same Builder instance. 936 */ 937 @SystemApi 938 @RequiresPermission(android.Manifest.permission.CAPTURE_AUDIO_HOTWORD) setHotwordModeEnabled(boolean enable)939 public @NonNull Builder setHotwordModeEnabled(boolean enable) { 940 if (enable) { 941 mFlags |= FLAG_HW_HOTWORD; 942 } else { 943 mFlags &= ~FLAG_HW_HOTWORD; 944 } 945 return this; 946 } 947 948 /** 949 * Specifies whether the audio may or may not be captured by other apps or the system. 950 * 951 * The default is {@link AudioAttributes#ALLOW_CAPTURE_BY_ALL}. 952 * 953 * There are multiple ways to set this policy: 954 * <ul> 955 * <li> for each track independently, with this method </li> 956 * <li> application-wide at runtime, with 957 * {@link AudioManager#setAllowedCapturePolicy(int)} </li> 958 * <li> application-wide at build time, see {@code allowAudioPlaybackCapture} in the 959 * application manifest. </li> 960 * </ul> 961 * The most restrictive policy is always applied. 962 * 963 * See {@link AudioPlaybackCaptureConfiguration} for more details on 964 * which audio signals can be captured. 965 * 966 * @return the same Builder instance 967 * @throws IllegalArgumentException if the argument is not a valid value. 968 */ setAllowedCapturePolicy(@apturePolicy int capturePolicy)969 public @NonNull Builder setAllowedCapturePolicy(@CapturePolicy int capturePolicy) { 970 mFlags = capturePolicyToFlags(capturePolicy, mFlags); 971 return this; 972 } 973 974 /** 975 * Specifies whether the content has already been processed for spatialization. 976 * If it has, setting this to true will prevent issues such as double-processing. 977 * @param isSpatialized 978 * @return the same Builder instance 979 */ setIsContentSpatialized(boolean isSpatialized)980 public @NonNull Builder setIsContentSpatialized(boolean isSpatialized) { 981 mIsContentSpatialized = isSpatialized; 982 return this; 983 } 984 985 /** 986 * Sets the behavior affecting whether spatialization will be used. 987 * @param sb the spatialization behavior 988 * @return the same Builder instance 989 * 990 */ setSpatializationBehavior(@patializationBehavior int sb)991 public @NonNull Builder setSpatializationBehavior(@SpatializationBehavior int sb) { 992 switch (sb) { 993 case SPATIALIZATION_BEHAVIOR_NEVER: 994 case SPATIALIZATION_BEHAVIOR_AUTO: 995 break; 996 default: 997 throw new IllegalArgumentException("Invalid spatialization behavior " + sb); 998 } 999 mSpatializationBehavior = sb; 1000 return this; 1001 } 1002 1003 /** 1004 * @hide 1005 * Replaces flags. 1006 * @param flags any combination of {@link AudioAttributes#FLAG_ALL}. 1007 * @return the same Builder instance. 1008 */ replaceFlags(int flags)1009 public Builder replaceFlags(int flags) { 1010 mFlags = flags & AudioAttributes.FLAG_ALL; 1011 return this; 1012 } 1013 1014 /** 1015 * @hide 1016 * Adds a Bundle of data 1017 * @param bundle a non-null Bundle 1018 * @return the same builder instance 1019 */ 1020 @SystemApi addBundle(@onNull Bundle bundle)1021 public Builder addBundle(@NonNull Bundle bundle) { 1022 if (bundle == null) { 1023 throw new IllegalArgumentException("Illegal null bundle"); 1024 } 1025 if (mBundle == null) { 1026 mBundle = new Bundle(bundle); 1027 } else { 1028 mBundle.putAll(bundle); 1029 } 1030 return this; 1031 } 1032 1033 /** 1034 * @hide 1035 * Add a custom tag stored as a string 1036 * @param tag 1037 * @return the same Builder instance. 1038 */ 1039 @UnsupportedAppUsage addTag(String tag)1040 public Builder addTag(String tag) { 1041 mTags.add(tag); 1042 return this; 1043 } 1044 1045 /** 1046 * Sets attributes as inferred from the legacy stream types. 1047 * Warning: do not use this method in combination with setting any other attributes such as 1048 * usage, content type, flags or haptic control, as this method will overwrite (the more 1049 * accurate) information describing the use case previously set in the <code>Builder</code>. 1050 * In general, avoid using it and prefer setting usage and content type directly 1051 * with {@link #setUsage(int)} and {@link #setContentType(int)}. 1052 * <p>Use this method when building an {@link AudioAttributes} instance to initialize some 1053 * of the attributes by information derived from a legacy stream type. 1054 * @param streamType one of {@link AudioManager#STREAM_VOICE_CALL}, 1055 * {@link AudioManager#STREAM_SYSTEM}, {@link AudioManager#STREAM_RING}, 1056 * {@link AudioManager#STREAM_MUSIC}, {@link AudioManager#STREAM_ALARM}, 1057 * or {@link AudioManager#STREAM_NOTIFICATION}. 1058 * @return the same Builder instance. 1059 */ setLegacyStreamType(int streamType)1060 public Builder setLegacyStreamType(int streamType) { 1061 if (streamType == AudioManager.STREAM_ACCESSIBILITY) { 1062 throw new IllegalArgumentException("STREAM_ACCESSIBILITY is not a legacy stream " 1063 + "type that was used for audio playback"); 1064 } 1065 setInternalLegacyStreamType(streamType); 1066 return this; 1067 } 1068 1069 /** 1070 * @hide 1071 * For internal framework use only, enables building from hidden stream types. 1072 * @param streamType 1073 * @return the same Builder instance. 1074 */ 1075 @UnsupportedAppUsage setInternalLegacyStreamType(int streamType)1076 public Builder setInternalLegacyStreamType(int streamType) { 1077 mContentType = CONTENT_TYPE_UNKNOWN; 1078 mUsage = USAGE_UNKNOWN; 1079 if (AudioProductStrategy.getAudioProductStrategies().size() > 0) { 1080 AudioAttributes attributes = 1081 AudioProductStrategy.getAudioAttributesForStrategyWithLegacyStreamType( 1082 streamType); 1083 if (attributes != null) { 1084 mUsage = attributes.mUsage; 1085 mContentType = attributes.mContentType; 1086 mFlags = attributes.getAllFlags(); 1087 mMuteHapticChannels = attributes.areHapticChannelsMuted(); 1088 mIsContentSpatialized = attributes.isContentSpatialized(); 1089 mSpatializationBehavior = attributes.getSpatializationBehavior(); 1090 mTags = attributes.mTags; 1091 mBundle = attributes.mBundle; 1092 mSource = attributes.mSource; 1093 } 1094 } 1095 if (mContentType == CONTENT_TYPE_UNKNOWN) { 1096 switch (streamType) { 1097 case AudioSystem.STREAM_VOICE_CALL: 1098 mContentType = CONTENT_TYPE_SPEECH; 1099 break; 1100 case AudioSystem.STREAM_SYSTEM_ENFORCED: 1101 mFlags |= FLAG_AUDIBILITY_ENFORCED; 1102 // intended fall through, attributes in common with STREAM_SYSTEM 1103 case AudioSystem.STREAM_SYSTEM: 1104 mContentType = CONTENT_TYPE_SONIFICATION; 1105 break; 1106 case AudioSystem.STREAM_RING: 1107 mContentType = CONTENT_TYPE_SONIFICATION; 1108 break; 1109 case AudioSystem.STREAM_MUSIC: 1110 mContentType = CONTENT_TYPE_MUSIC; 1111 break; 1112 case AudioSystem.STREAM_ALARM: 1113 mContentType = CONTENT_TYPE_SONIFICATION; 1114 break; 1115 case AudioSystem.STREAM_NOTIFICATION: 1116 mContentType = CONTENT_TYPE_SONIFICATION; 1117 break; 1118 case AudioSystem.STREAM_BLUETOOTH_SCO: 1119 mContentType = CONTENT_TYPE_SPEECH; 1120 mFlags |= FLAG_SCO; 1121 break; 1122 case AudioSystem.STREAM_DTMF: 1123 mContentType = CONTENT_TYPE_SONIFICATION; 1124 break; 1125 case AudioSystem.STREAM_TTS: 1126 mContentType = CONTENT_TYPE_SONIFICATION; 1127 mFlags |= FLAG_BEACON; 1128 break; 1129 case AudioSystem.STREAM_ACCESSIBILITY: 1130 mContentType = CONTENT_TYPE_SPEECH; 1131 break; 1132 default: 1133 Log.e(TAG, "Invalid stream type " + streamType + " for AudioAttributes"); 1134 } 1135 } 1136 if (mUsage == USAGE_UNKNOWN) { 1137 mUsage = usageForStreamType(streamType); 1138 } 1139 return this; 1140 } 1141 1142 /** 1143 * @hide 1144 * Sets the capture preset. 1145 * Use this audio attributes configuration method when building an {@link AudioRecord} 1146 * instance with {@link AudioRecord#AudioRecord(AudioAttributes, AudioFormat, int)}. 1147 * @param preset one of {@link MediaRecorder.AudioSource#DEFAULT}, 1148 * {@link MediaRecorder.AudioSource#MIC}, {@link MediaRecorder.AudioSource#CAMCORDER}, 1149 * {@link MediaRecorder.AudioSource#VOICE_RECOGNITION}, 1150 * {@link MediaRecorder.AudioSource#VOICE_COMMUNICATION}, 1151 * {@link MediaRecorder.AudioSource#UNPROCESSED} or 1152 * {@link MediaRecorder.AudioSource#VOICE_PERFORMANCE} 1153 * @return the same Builder instance. 1154 */ 1155 @SystemApi setCapturePreset(int preset)1156 public Builder setCapturePreset(int preset) { 1157 switch (preset) { 1158 case MediaRecorder.AudioSource.DEFAULT: 1159 case MediaRecorder.AudioSource.MIC: 1160 case MediaRecorder.AudioSource.CAMCORDER: 1161 case MediaRecorder.AudioSource.VOICE_RECOGNITION: 1162 case MediaRecorder.AudioSource.VOICE_COMMUNICATION: 1163 case MediaRecorder.AudioSource.UNPROCESSED: 1164 case MediaRecorder.AudioSource.VOICE_PERFORMANCE: 1165 mSource = preset; 1166 break; 1167 default: 1168 Log.e(TAG, "Invalid capture preset " + preset + " for AudioAttributes"); 1169 } 1170 return this; 1171 } 1172 1173 /** 1174 * @hide 1175 * Same as {@link #setCapturePreset(int)} but authorizes the use of HOTWORD, 1176 * REMOTE_SUBMIX, RADIO_TUNER, VOICE_DOWNLINK, VOICE_UPLINK, VOICE_CALL and ECHO_REFERENCE. 1177 * @param preset 1178 * @return the same Builder instance. 1179 */ 1180 @SystemApi setInternalCapturePreset(int preset)1181 public Builder setInternalCapturePreset(int preset) { 1182 if ((preset == MediaRecorder.AudioSource.HOTWORD) 1183 || (preset == MediaRecorder.AudioSource.REMOTE_SUBMIX) 1184 || (preset == MediaRecorder.AudioSource.RADIO_TUNER) 1185 || (preset == MediaRecorder.AudioSource.VOICE_DOWNLINK) 1186 || (preset == MediaRecorder.AudioSource.VOICE_UPLINK) 1187 || (preset == MediaRecorder.AudioSource.VOICE_CALL) 1188 || (preset == MediaRecorder.AudioSource.ECHO_REFERENCE)) { 1189 mSource = preset; 1190 } else { 1191 setCapturePreset(preset); 1192 } 1193 return this; 1194 } 1195 1196 /** 1197 * Specifying if haptic should be muted or not when playing audio-haptic coupled data. 1198 * By default, haptic channels are disabled. 1199 * @param muted true to force muting haptic channels. 1200 * @return the same Builder instance. 1201 */ setHapticChannelsMuted(boolean muted)1202 public @NonNull Builder setHapticChannelsMuted(boolean muted) { 1203 mMuteHapticChannels = muted; 1204 return this; 1205 } 1206 1207 /** 1208 * @hide 1209 * Indicates if an AudioRecord build with this AudioAttributes is privacy sensitive or not. 1210 * See {@link AudioRecord.Builder#setPrivacySensitive(boolean)}. 1211 * @param privacySensitive True if capture must be marked as privacy sensitive, 1212 * false otherwise. 1213 * @return the same Builder instance. 1214 */ setPrivacySensitive(boolean privacySensitive)1215 public @NonNull Builder setPrivacySensitive(boolean privacySensitive) { 1216 mPrivacySensitive = 1217 privacySensitive ? PRIVACY_SENSITIVE_ENABLED : PRIVACY_SENSITIVE_DISABLED; 1218 return this; 1219 } 1220 }; 1221 1222 @Override describeContents()1223 public int describeContents() { 1224 return 0; 1225 } 1226 1227 /** 1228 * @hide 1229 * Used to indicate that when parcelling, the tags should be parcelled through the flattened 1230 * formatted string, not through the array of strings. 1231 * Keep in sync with frameworks/av/media/libmediaplayerservice/MediaPlayerService.cpp 1232 * see definition of kAudioAttributesMarshallTagFlattenTags 1233 */ 1234 public final static int FLATTEN_TAGS = 0x1; 1235 1236 private final static int ATTR_PARCEL_IS_NULL_BUNDLE = -1977; 1237 private final static int ATTR_PARCEL_IS_VALID_BUNDLE = 1980; 1238 1239 /** 1240 * When adding tags for writeToParcel(Parcel, int), add them in the list of flags (| NEW_FLAG) 1241 */ 1242 private final static int ALL_PARCEL_FLAGS = FLATTEN_TAGS; 1243 @Override writeToParcel(Parcel dest, int flags)1244 public void writeToParcel(Parcel dest, int flags) { 1245 dest.writeInt(mUsage); 1246 dest.writeInt(mContentType); 1247 dest.writeInt(mSource); 1248 dest.writeInt(mFlags); 1249 dest.writeInt(flags & ALL_PARCEL_FLAGS); 1250 if ((flags & FLATTEN_TAGS) == 0) { 1251 String[] tagsArray = new String[mTags.size()]; 1252 mTags.toArray(tagsArray); 1253 dest.writeStringArray(tagsArray); 1254 } else if ((flags & FLATTEN_TAGS) == FLATTEN_TAGS) { 1255 dest.writeString(mFormattedTags); 1256 } 1257 if (mBundle == null) { 1258 dest.writeInt(ATTR_PARCEL_IS_NULL_BUNDLE); 1259 } else { 1260 dest.writeInt(ATTR_PARCEL_IS_VALID_BUNDLE); 1261 dest.writeBundle(mBundle); 1262 } 1263 } 1264 AudioAttributes(Parcel in)1265 private AudioAttributes(Parcel in) { 1266 mUsage = in.readInt(); 1267 mContentType = in.readInt(); 1268 mSource = in.readInt(); 1269 mFlags = in.readInt(); 1270 boolean hasFlattenedTags = ((in.readInt() & FLATTEN_TAGS) == FLATTEN_TAGS); 1271 mTags = new HashSet<String>(); 1272 if (hasFlattenedTags) { 1273 mFormattedTags = new String(in.readString()); 1274 mTags.add(mFormattedTags); 1275 } else { 1276 String[] tagsArray = in.readStringArray(); 1277 for (int i = tagsArray.length - 1 ; i >= 0 ; i--) { 1278 mTags.add(tagsArray[i]); 1279 } 1280 mFormattedTags = TextUtils.join(";", mTags); 1281 } 1282 switch (in.readInt()) { 1283 case ATTR_PARCEL_IS_NULL_BUNDLE: 1284 mBundle = null; 1285 break; 1286 case ATTR_PARCEL_IS_VALID_BUNDLE: 1287 mBundle = new Bundle(in.readBundle()); 1288 break; 1289 default: 1290 Log.e(TAG, "Illegal value unmarshalling AudioAttributes, can't initialize bundle"); 1291 } 1292 } 1293 1294 public static final @android.annotation.NonNull Parcelable.Creator<AudioAttributes> CREATOR 1295 = new Parcelable.Creator<AudioAttributes>() { 1296 /** 1297 * Rebuilds an AudioAttributes previously stored with writeToParcel(). 1298 * @param p Parcel object to read the AudioAttributes from 1299 * @return a new AudioAttributes created from the data in the parcel 1300 */ 1301 public AudioAttributes createFromParcel(Parcel p) { 1302 return new AudioAttributes(p); 1303 } 1304 public AudioAttributes[] newArray(int size) { 1305 return new AudioAttributes[size]; 1306 } 1307 }; 1308 1309 @Override equals(Object o)1310 public boolean equals(Object o) { 1311 if (this == o) return true; 1312 if (o == null || getClass() != o.getClass()) return false; 1313 1314 AudioAttributes that = (AudioAttributes) o; 1315 1316 return ((mContentType == that.mContentType) 1317 && (mFlags == that.mFlags) 1318 && (mSource == that.mSource) 1319 && (mUsage == that.mUsage) 1320 //mFormattedTags is never null due to assignment in Builder or unmarshalling 1321 && (mFormattedTags.equals(that.mFormattedTags))); 1322 } 1323 1324 @Override hashCode()1325 public int hashCode() { 1326 return Objects.hash(mContentType, mFlags, mSource, mUsage, mFormattedTags, mBundle); 1327 } 1328 1329 @Override toString()1330 public String toString () { 1331 return new String("AudioAttributes:" 1332 + " usage=" + usageToString() 1333 + " content=" + contentTypeToString() 1334 + " flags=0x" + Integer.toHexString(mFlags).toUpperCase() 1335 + " tags=" + mFormattedTags 1336 + " bundle=" + (mBundle == null ? "null" : mBundle.toString())); 1337 } 1338 1339 /** @hide */ dumpDebug(ProtoOutputStream proto, long fieldId)1340 public void dumpDebug(ProtoOutputStream proto, long fieldId) { 1341 final long token = proto.start(fieldId); 1342 1343 proto.write(AudioAttributesProto.USAGE, mUsage); 1344 proto.write(AudioAttributesProto.CONTENT_TYPE, mContentType); 1345 proto.write(AudioAttributesProto.FLAGS, mFlags); 1346 // mFormattedTags is never null due to assignment in Builder or unmarshalling. 1347 for (String t : mFormattedTags.split(";")) { 1348 t = t.trim(); 1349 if (t != "") { 1350 proto.write(AudioAttributesProto.TAGS, t); 1351 } 1352 } 1353 // TODO: is the data in mBundle useful for debugging? 1354 1355 proto.end(token); 1356 } 1357 1358 /** @hide */ usageToString()1359 public String usageToString() { 1360 return usageToString(mUsage); 1361 } 1362 1363 /** 1364 * Returns the string representation for the usage constant passed as parameter. 1365 * 1366 * @param usage one of the {@link AudioAttributes} usage constants 1367 * @return string representing the {@link AudioAttributes} usage constant passed as a parameter 1368 * 1369 * @hide 1370 */ 1371 @NonNull usageToString(@ttributeSdkUsage int usage)1372 public static String usageToString(@AttributeSdkUsage int usage) { 1373 switch(usage) { 1374 case USAGE_UNKNOWN: 1375 return "USAGE_UNKNOWN"; 1376 case USAGE_MEDIA: 1377 return "USAGE_MEDIA"; 1378 case USAGE_VOICE_COMMUNICATION: 1379 return "USAGE_VOICE_COMMUNICATION"; 1380 case USAGE_VOICE_COMMUNICATION_SIGNALLING: 1381 return "USAGE_VOICE_COMMUNICATION_SIGNALLING"; 1382 case USAGE_ALARM: 1383 return "USAGE_ALARM"; 1384 case USAGE_NOTIFICATION: 1385 return "USAGE_NOTIFICATION"; 1386 case USAGE_NOTIFICATION_RINGTONE: 1387 return "USAGE_NOTIFICATION_RINGTONE"; 1388 case USAGE_NOTIFICATION_COMMUNICATION_REQUEST: 1389 return "USAGE_NOTIFICATION_COMMUNICATION_REQUEST"; 1390 case USAGE_NOTIFICATION_COMMUNICATION_INSTANT: 1391 return "USAGE_NOTIFICATION_COMMUNICATION_INSTANT"; 1392 case USAGE_NOTIFICATION_COMMUNICATION_DELAYED: 1393 return "USAGE_NOTIFICATION_COMMUNICATION_DELAYED"; 1394 case USAGE_NOTIFICATION_EVENT: 1395 return "USAGE_NOTIFICATION_EVENT"; 1396 case USAGE_ASSISTANCE_ACCESSIBILITY: 1397 return "USAGE_ASSISTANCE_ACCESSIBILITY"; 1398 case USAGE_ASSISTANCE_NAVIGATION_GUIDANCE: 1399 return "USAGE_ASSISTANCE_NAVIGATION_GUIDANCE"; 1400 case USAGE_ASSISTANCE_SONIFICATION: 1401 return "USAGE_ASSISTANCE_SONIFICATION"; 1402 case USAGE_GAME: 1403 return "USAGE_GAME"; 1404 case USAGE_ASSISTANT: 1405 return "USAGE_ASSISTANT"; 1406 case USAGE_CALL_ASSISTANT: 1407 return "USAGE_CALL_ASSISTANT"; 1408 case USAGE_EMERGENCY: 1409 return "USAGE_EMERGENCY"; 1410 case USAGE_SAFETY: 1411 return "USAGE_SAFETY"; 1412 case USAGE_VEHICLE_STATUS: 1413 return "USAGE_VEHICLE_STATUS"; 1414 case USAGE_ANNOUNCEMENT: 1415 return "USAGE_ANNOUNCEMENT"; 1416 default: 1417 return "unknown usage " + usage; 1418 } 1419 } 1420 1421 /** @hide **/ 1422 @TestApi 1423 @NonNull usageToXsdString(@ttributeUsage int usage)1424 public static String usageToXsdString(@AttributeUsage int usage) { 1425 switch (usage) { 1426 case AudioAttributes.USAGE_UNKNOWN: 1427 return AudioUsage.AUDIO_USAGE_UNKNOWN.toString(); 1428 case AudioAttributes.USAGE_MEDIA: 1429 return AudioUsage.AUDIO_USAGE_MEDIA.toString(); 1430 case AudioAttributes.USAGE_VOICE_COMMUNICATION: 1431 return AudioUsage.AUDIO_USAGE_VOICE_COMMUNICATION.toString(); 1432 case AudioAttributes.USAGE_VOICE_COMMUNICATION_SIGNALLING: 1433 return AudioUsage.AUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING.toString(); 1434 case AudioAttributes.USAGE_ALARM: 1435 return AudioUsage.AUDIO_USAGE_ALARM.toString(); 1436 case AudioAttributes.USAGE_NOTIFICATION: 1437 return AudioUsage.AUDIO_USAGE_NOTIFICATION.toString(); 1438 case AudioAttributes.USAGE_NOTIFICATION_RINGTONE: 1439 return AudioUsage.AUDIO_USAGE_NOTIFICATION_TELEPHONY_RINGTONE.toString(); 1440 case AudioAttributes.USAGE_ASSISTANCE_ACCESSIBILITY: 1441 return AudioUsage.AUDIO_USAGE_ASSISTANCE_ACCESSIBILITY.toString(); 1442 case AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE: 1443 return AudioUsage.AUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE.toString(); 1444 case AudioAttributes.USAGE_ASSISTANCE_SONIFICATION: 1445 return AudioUsage.AUDIO_USAGE_ASSISTANCE_SONIFICATION.toString(); 1446 case AudioAttributes.USAGE_GAME: 1447 return AudioUsage.AUDIO_USAGE_GAME.toString(); 1448 case AudioAttributes.USAGE_VIRTUAL_SOURCE: 1449 return AudioUsage.AUDIO_USAGE_VIRTUAL_SOURCE.toString(); 1450 case AudioAttributes.USAGE_ASSISTANT: 1451 return AudioUsage.AUDIO_USAGE_ASSISTANT.toString(); 1452 case AudioAttributes.USAGE_CALL_ASSISTANT: 1453 return AudioUsage.AUDIO_USAGE_CALL_ASSISTANT.toString(); 1454 case AudioAttributes.USAGE_EMERGENCY: 1455 return AudioUsage.AUDIO_USAGE_EMERGENCY.toString(); 1456 case AudioAttributes.USAGE_SAFETY: 1457 return AudioUsage.AUDIO_USAGE_SAFETY.toString(); 1458 case AudioAttributes.USAGE_VEHICLE_STATUS: 1459 return AudioUsage.AUDIO_USAGE_VEHICLE_STATUS.toString(); 1460 case AudioAttributes.USAGE_ANNOUNCEMENT: 1461 return AudioUsage.AUDIO_USAGE_ANNOUNCEMENT.toString(); 1462 default: 1463 Log.w(TAG, "Unknown usage value " + usage); 1464 return AudioUsage.AUDIO_USAGE_UNKNOWN.toString(); 1465 } 1466 } 1467 1468 private static final Map<String, Integer> sXsdStringToUsage = new HashMap<>(); 1469 1470 static { AudioUsage.AUDIO_USAGE_UNKNOWN.toString()1471 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_UNKNOWN.toString(), USAGE_UNKNOWN); AudioUsage.AUDIO_USAGE_UNKNOWN.toString()1472 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_UNKNOWN.toString(), USAGE_UNKNOWN); AudioUsage.AUDIO_USAGE_MEDIA.toString()1473 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_MEDIA.toString(), USAGE_MEDIA); AudioUsage.AUDIO_USAGE_VOICE_COMMUNICATION.toString()1474 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_VOICE_COMMUNICATION.toString(), 1475 USAGE_VOICE_COMMUNICATION); AudioUsage.AUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING.toString()1476 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING.toString(), 1477 USAGE_VOICE_COMMUNICATION_SIGNALLING); AudioUsage.AUDIO_USAGE_ALARM.toString()1478 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_ALARM.toString(), USAGE_ALARM); AudioUsage.AUDIO_USAGE_NOTIFICATION.toString()1479 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_NOTIFICATION.toString(), USAGE_NOTIFICATION); AudioUsage.AUDIO_USAGE_NOTIFICATION_TELEPHONY_RINGTONE.toString()1480 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_NOTIFICATION_TELEPHONY_RINGTONE.toString(), 1481 USAGE_NOTIFICATION_RINGTONE); AudioUsage.AUDIO_USAGE_ASSISTANCE_ACCESSIBILITY.toString()1482 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_ASSISTANCE_ACCESSIBILITY.toString(), 1483 USAGE_ASSISTANCE_ACCESSIBILITY); AudioUsage.AUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE.toString()1484 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE.toString(), 1485 USAGE_ASSISTANCE_NAVIGATION_GUIDANCE); AudioUsage.AUDIO_USAGE_ASSISTANCE_SONIFICATION.toString()1486 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_ASSISTANCE_SONIFICATION.toString(), 1487 USAGE_ASSISTANCE_SONIFICATION); AudioUsage.AUDIO_USAGE_GAME.toString()1488 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_GAME.toString(), USAGE_GAME); AudioUsage.AUDIO_USAGE_VIRTUAL_SOURCE.toString()1489 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_VIRTUAL_SOURCE.toString(), 1490 USAGE_VIRTUAL_SOURCE); AudioUsage.AUDIO_USAGE_ASSISTANT.toString()1491 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_ASSISTANT.toString(), USAGE_ASSISTANT); AudioUsage.AUDIO_USAGE_CALL_ASSISTANT.toString()1492 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_CALL_ASSISTANT.toString(), 1493 USAGE_CALL_ASSISTANT); AudioUsage.AUDIO_USAGE_EMERGENCY.toString()1494 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_EMERGENCY.toString(), USAGE_EMERGENCY); AudioUsage.AUDIO_USAGE_SAFETY.toString()1495 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_SAFETY.toString(), USAGE_SAFETY); AudioUsage.AUDIO_USAGE_VEHICLE_STATUS.toString()1496 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_VEHICLE_STATUS.toString(), 1497 USAGE_VEHICLE_STATUS); AudioUsage.AUDIO_USAGE_ANNOUNCEMENT.toString()1498 sXsdStringToUsage.put(AudioUsage.AUDIO_USAGE_ANNOUNCEMENT.toString(), USAGE_ANNOUNCEMENT); 1499 } 1500 1501 /** @hide **/ 1502 @TestApi xsdStringToUsage(@onNull String xsdUsage)1503 public static @AttributeUsage int xsdStringToUsage(@NonNull String xsdUsage) { 1504 if (sXsdStringToUsage.containsKey(xsdUsage)) { 1505 return sXsdStringToUsage.get(xsdUsage); 1506 } else { 1507 Log.w(TAG, "Usage name not found in AudioUsage enum: " + xsdUsage); 1508 return USAGE_UNKNOWN; 1509 } 1510 } 1511 1512 /** @hide */ contentTypeToString()1513 public String contentTypeToString() { 1514 switch(mContentType) { 1515 case CONTENT_TYPE_UNKNOWN: 1516 return new String("CONTENT_TYPE_UNKNOWN"); 1517 case CONTENT_TYPE_SPEECH: return new String("CONTENT_TYPE_SPEECH"); 1518 case CONTENT_TYPE_MUSIC: return new String("CONTENT_TYPE_MUSIC"); 1519 case CONTENT_TYPE_MOVIE: return new String("CONTENT_TYPE_MOVIE"); 1520 case CONTENT_TYPE_SONIFICATION: return new String("CONTENT_TYPE_SONIFICATION"); 1521 default: return new String("unknown content type " + mContentType); 1522 } 1523 } 1524 usageForStreamType(int streamType)1525 private static int usageForStreamType(int streamType) { 1526 switch(streamType) { 1527 case AudioSystem.STREAM_VOICE_CALL: 1528 return USAGE_VOICE_COMMUNICATION; 1529 case AudioSystem.STREAM_SYSTEM_ENFORCED: 1530 case AudioSystem.STREAM_SYSTEM: 1531 return USAGE_ASSISTANCE_SONIFICATION; 1532 case AudioSystem.STREAM_RING: 1533 return USAGE_NOTIFICATION_RINGTONE; 1534 case AudioSystem.STREAM_MUSIC: 1535 return USAGE_MEDIA; 1536 case AudioSystem.STREAM_ALARM: 1537 return USAGE_ALARM; 1538 case AudioSystem.STREAM_NOTIFICATION: 1539 return USAGE_NOTIFICATION; 1540 case AudioSystem.STREAM_BLUETOOTH_SCO: 1541 return USAGE_VOICE_COMMUNICATION; 1542 case AudioSystem.STREAM_DTMF: 1543 return USAGE_VOICE_COMMUNICATION_SIGNALLING; 1544 case AudioSystem.STREAM_ACCESSIBILITY: 1545 return USAGE_ASSISTANCE_ACCESSIBILITY; 1546 case AudioSystem.STREAM_TTS: 1547 default: 1548 return USAGE_UNKNOWN; 1549 } 1550 } 1551 1552 /** 1553 * @param usage one of {@link AttributeSystemUsage}, 1554 * {@link AttributeSystemUsage#USAGE_CALL_ASSISTANT}, 1555 * {@link AttributeSystemUsage#USAGE_EMERGENCY}, 1556 * {@link AttributeSystemUsage#USAGE_SAFETY}, 1557 * {@link AttributeSystemUsage#USAGE_VEHICLE_STATUS}, 1558 * {@link AttributeSystemUsage#USAGE_ANNOUNCEMENT} 1559 * @return boolean indicating if the usage is a system usage or not 1560 * @hide 1561 */ 1562 @SystemApi isSystemUsage(@ttributeSystemUsage int usage)1563 public static boolean isSystemUsage(@AttributeSystemUsage int usage) { 1564 return (usage == USAGE_CALL_ASSISTANT 1565 || usage == USAGE_EMERGENCY 1566 || usage == USAGE_SAFETY 1567 || usage == USAGE_VEHICLE_STATUS 1568 || usage == USAGE_ANNOUNCEMENT); 1569 } 1570 1571 /** 1572 * Returns the stream type matching this {@code AudioAttributes} instance for volume control. 1573 * Use this method to derive the stream type needed to configure the volume 1574 * control slider in an {@link android.app.Activity} with 1575 * {@link android.app.Activity#setVolumeControlStream(int)} for playback conducted with these 1576 * attributes. 1577 * <BR>Do not use this method to set the stream type on an audio player object 1578 * (e.g. {@link AudioTrack}, {@link MediaPlayer}) as this is deprecated, 1579 * use {@code AudioAttributes} instead. 1580 * @return a valid stream type for {@code Activity} or stream volume control that matches 1581 * the attributes, or {@link AudioManager#USE_DEFAULT_STREAM_TYPE} if there isn't a direct 1582 * match. Note that {@code USE_DEFAULT_STREAM_TYPE} is not a valid value 1583 * for {@link AudioManager#setStreamVolume(int, int, int)}. 1584 */ getVolumeControlStream()1585 public int getVolumeControlStream() { 1586 return toVolumeStreamType(true /*fromGetVolumeControlStream*/, this); 1587 } 1588 1589 /** 1590 * @hide 1591 * Only use to get which stream type should be used for volume control, NOT for audio playback 1592 * (all audio playback APIs are supposed to take AudioAttributes as input parameters) 1593 * @param aa non-null AudioAttributes. 1594 * @return a valid stream type for volume control that matches the attributes. 1595 */ 1596 @UnsupportedAppUsage toLegacyStreamType(@onNull AudioAttributes aa)1597 public static int toLegacyStreamType(@NonNull AudioAttributes aa) { 1598 return toVolumeStreamType(false /*fromGetVolumeControlStream*/, aa); 1599 } 1600 toVolumeStreamType(boolean fromGetVolumeControlStream, AudioAttributes aa)1601 private static int toVolumeStreamType(boolean fromGetVolumeControlStream, AudioAttributes aa) { 1602 // flags to stream type mapping 1603 if ((aa.getFlags() & FLAG_AUDIBILITY_ENFORCED) == FLAG_AUDIBILITY_ENFORCED) { 1604 return fromGetVolumeControlStream ? 1605 AudioSystem.STREAM_SYSTEM : AudioSystem.STREAM_SYSTEM_ENFORCED; 1606 } 1607 if ((aa.getAllFlags() & FLAG_SCO) == FLAG_SCO) { 1608 return fromGetVolumeControlStream ? 1609 AudioSystem.STREAM_VOICE_CALL : AudioSystem.STREAM_BLUETOOTH_SCO; 1610 } 1611 if ((aa.getAllFlags() & FLAG_BEACON) == FLAG_BEACON) { 1612 return fromGetVolumeControlStream ? 1613 AudioSystem.STREAM_MUSIC : AudioSystem.STREAM_TTS; 1614 } 1615 1616 if (AudioProductStrategy.getAudioProductStrategies().size() > 0) { 1617 return AudioProductStrategy.getLegacyStreamTypeForStrategyWithAudioAttributes(aa); 1618 } 1619 // usage to stream type mapping 1620 switch (aa.getUsage()) { 1621 case USAGE_MEDIA: 1622 case USAGE_GAME: 1623 case USAGE_ASSISTANCE_NAVIGATION_GUIDANCE: 1624 case USAGE_ASSISTANT: 1625 return AudioSystem.STREAM_MUSIC; 1626 case USAGE_ASSISTANCE_SONIFICATION: 1627 return AudioSystem.STREAM_SYSTEM; 1628 case USAGE_VOICE_COMMUNICATION: 1629 case USAGE_CALL_ASSISTANT: 1630 return AudioSystem.STREAM_VOICE_CALL; 1631 case USAGE_VOICE_COMMUNICATION_SIGNALLING: 1632 return fromGetVolumeControlStream ? 1633 AudioSystem.STREAM_VOICE_CALL : AudioSystem.STREAM_DTMF; 1634 case USAGE_ALARM: 1635 return AudioSystem.STREAM_ALARM; 1636 case USAGE_NOTIFICATION_RINGTONE: 1637 return AudioSystem.STREAM_RING; 1638 case USAGE_NOTIFICATION: 1639 case USAGE_NOTIFICATION_COMMUNICATION_REQUEST: 1640 case USAGE_NOTIFICATION_COMMUNICATION_INSTANT: 1641 case USAGE_NOTIFICATION_COMMUNICATION_DELAYED: 1642 case USAGE_NOTIFICATION_EVENT: 1643 return AudioSystem.STREAM_NOTIFICATION; 1644 case USAGE_ASSISTANCE_ACCESSIBILITY: 1645 return AudioSystem.STREAM_ACCESSIBILITY; 1646 case USAGE_EMERGENCY: 1647 case USAGE_SAFETY: 1648 case USAGE_VEHICLE_STATUS: 1649 case USAGE_ANNOUNCEMENT: 1650 case USAGE_UNKNOWN: 1651 return AudioSystem.STREAM_MUSIC; 1652 default: 1653 if (fromGetVolumeControlStream) { 1654 throw new IllegalArgumentException("Unknown usage value " + aa.getUsage() + 1655 " in audio attributes"); 1656 } else { 1657 return AudioSystem.STREAM_MUSIC; 1658 } 1659 } 1660 } 1661 1662 /** 1663 * @hide 1664 */ capturePolicyToFlags(@apturePolicy int capturePolicy, int flags)1665 public static int capturePolicyToFlags(@CapturePolicy int capturePolicy, int flags) { 1666 switch (capturePolicy) { 1667 case ALLOW_CAPTURE_BY_NONE: 1668 flags |= FLAG_NO_MEDIA_PROJECTION | FLAG_NO_SYSTEM_CAPTURE; 1669 break; 1670 case ALLOW_CAPTURE_BY_SYSTEM: 1671 flags |= FLAG_NO_MEDIA_PROJECTION; 1672 flags &= ~FLAG_NO_SYSTEM_CAPTURE; 1673 break; 1674 case ALLOW_CAPTURE_BY_ALL: 1675 flags &= ~FLAG_NO_SYSTEM_CAPTURE & ~FLAG_NO_MEDIA_PROJECTION; 1676 break; 1677 default: 1678 throw new IllegalArgumentException("Unknown allow playback capture policy"); 1679 } 1680 return flags; 1681 } 1682 1683 /** @hide */ 1684 @IntDef({ 1685 USAGE_CALL_ASSISTANT, 1686 USAGE_EMERGENCY, 1687 USAGE_SAFETY, 1688 USAGE_VEHICLE_STATUS, 1689 USAGE_ANNOUNCEMENT 1690 }) 1691 @Retention(RetentionPolicy.SOURCE) 1692 public @interface AttributeSystemUsage {} 1693 1694 /** @hide */ 1695 @IntDef({ 1696 USAGE_UNKNOWN, 1697 USAGE_MEDIA, 1698 USAGE_VOICE_COMMUNICATION, 1699 USAGE_VOICE_COMMUNICATION_SIGNALLING, 1700 USAGE_ALARM, 1701 USAGE_NOTIFICATION, 1702 USAGE_NOTIFICATION_RINGTONE, 1703 USAGE_NOTIFICATION_COMMUNICATION_REQUEST, 1704 USAGE_NOTIFICATION_COMMUNICATION_INSTANT, 1705 USAGE_NOTIFICATION_COMMUNICATION_DELAYED, 1706 USAGE_NOTIFICATION_EVENT, 1707 USAGE_ASSISTANCE_ACCESSIBILITY, 1708 USAGE_ASSISTANCE_NAVIGATION_GUIDANCE, 1709 USAGE_ASSISTANCE_SONIFICATION, 1710 USAGE_GAME, 1711 USAGE_ASSISTANT, 1712 }) 1713 @Retention(RetentionPolicy.SOURCE) 1714 public @interface AttributeSdkUsage {} 1715 1716 /** @hide */ 1717 @IntDef({ 1718 USAGE_UNKNOWN, 1719 USAGE_MEDIA, 1720 USAGE_VOICE_COMMUNICATION, 1721 USAGE_VOICE_COMMUNICATION_SIGNALLING, 1722 USAGE_ALARM, 1723 USAGE_NOTIFICATION, 1724 USAGE_NOTIFICATION_RINGTONE, 1725 USAGE_NOTIFICATION_COMMUNICATION_REQUEST, 1726 USAGE_NOTIFICATION_COMMUNICATION_INSTANT, 1727 USAGE_NOTIFICATION_COMMUNICATION_DELAYED, 1728 USAGE_NOTIFICATION_EVENT, 1729 USAGE_ASSISTANCE_ACCESSIBILITY, 1730 USAGE_ASSISTANCE_NAVIGATION_GUIDANCE, 1731 USAGE_ASSISTANCE_SONIFICATION, 1732 USAGE_GAME, 1733 USAGE_ASSISTANT, 1734 USAGE_CALL_ASSISTANT, 1735 USAGE_EMERGENCY, 1736 USAGE_SAFETY, 1737 USAGE_VEHICLE_STATUS, 1738 USAGE_ANNOUNCEMENT, 1739 }) 1740 @Retention(RetentionPolicy.SOURCE) 1741 public @interface AttributeUsage {} 1742 1743 /** @hide */ 1744 @IntDef({ 1745 CONTENT_TYPE_UNKNOWN, 1746 CONTENT_TYPE_SPEECH, 1747 CONTENT_TYPE_MUSIC, 1748 CONTENT_TYPE_MOVIE, 1749 CONTENT_TYPE_SONIFICATION 1750 }) 1751 @Retention(RetentionPolicy.SOURCE) 1752 public @interface AttributeContentType {} 1753 } 1754