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