audio.h revision fcbb23adc939dd27122d962e5f7e7f016259f03e
1/* 2 * Copyright (C) 2011 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 18#ifndef ANDROID_AUDIO_CORE_H 19#define ANDROID_AUDIO_CORE_H 20 21#include <stdbool.h> 22#include <stdint.h> 23#include <stdio.h> 24#include <sys/cdefs.h> 25#include <sys/types.h> 26 27#include <cutils/bitops.h> 28 29__BEGIN_DECLS 30 31/* The enums were moved here mostly from 32 * frameworks/base/include/media/AudioSystem.h 33 */ 34 35/* device address used to refer to the standard remote submix */ 36#define AUDIO_REMOTE_SUBMIX_DEVICE_ADDRESS "0" 37 38/* AudioFlinger and AudioPolicy services use I/O handles to identify audio sources and sinks */ 39typedef int audio_io_handle_t; 40#define AUDIO_IO_HANDLE_NONE 0 41 42/* Audio stream types */ 43typedef enum { 44 /* These values must kept in sync with 45 * frameworks/base/media/java/android/media/AudioSystem.java 46 */ 47 AUDIO_STREAM_DEFAULT = -1, 48 AUDIO_STREAM_MIN = 0, 49 AUDIO_STREAM_VOICE_CALL = 0, 50 AUDIO_STREAM_SYSTEM = 1, 51 AUDIO_STREAM_RING = 2, 52 AUDIO_STREAM_MUSIC = 3, 53 AUDIO_STREAM_ALARM = 4, 54 AUDIO_STREAM_NOTIFICATION = 5, 55 AUDIO_STREAM_BLUETOOTH_SCO = 6, 56 AUDIO_STREAM_ENFORCED_AUDIBLE = 7, /* Sounds that cannot be muted by user 57 * and must be routed to speaker 58 */ 59 AUDIO_STREAM_DTMF = 8, 60 AUDIO_STREAM_TTS = 9, 61 62 AUDIO_STREAM_CNT, 63 AUDIO_STREAM_MAX = AUDIO_STREAM_CNT - 1, 64} audio_stream_type_t; 65 66/* Do not change these values without updating their counterparts 67 * in frameworks/base/media/java/android/media/AudioAttributes.java 68 */ 69typedef enum { 70 AUDIO_CONTENT_TYPE_UNKNOWN = 0, 71 AUDIO_CONTENT_TYPE_SPEECH = 1, 72 AUDIO_CONTENT_TYPE_MUSIC = 2, 73 AUDIO_CONTENT_TYPE_MOVIE = 3, 74 AUDIO_CONTENT_TYPE_SONIFICATION = 4, 75 76 AUDIO_CONTENT_TYPE_CNT, 77 AUDIO_CONTENT_TYPE_MAX = AUDIO_CONTENT_TYPE_CNT - 1, 78} audio_content_type_t; 79 80/* Do not change these values without updating their counterparts 81 * in frameworks/base/media/java/android/media/AudioAttributes.java 82 */ 83typedef enum { 84 AUDIO_USAGE_UNKNOWN = 0, 85 AUDIO_USAGE_MEDIA = 1, 86 AUDIO_USAGE_VOICE_COMMUNICATION = 2, 87 AUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING = 3, 88 AUDIO_USAGE_ALARM = 4, 89 AUDIO_USAGE_NOTIFICATION = 5, 90 AUDIO_USAGE_NOTIFICATION_TELEPHONY_RINGTONE = 6, 91 AUDIO_USAGE_NOTIFICATION_COMMUNICATION_REQUEST = 7, 92 AUDIO_USAGE_NOTIFICATION_COMMUNICATION_INSTANT = 8, 93 AUDIO_USAGE_NOTIFICATION_COMMUNICATION_DELAYED = 9, 94 AUDIO_USAGE_NOTIFICATION_EVENT = 10, 95 AUDIO_USAGE_ASSISTANCE_ACCESSIBILITY = 11, 96 AUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE = 12, 97 AUDIO_USAGE_ASSISTANCE_SONIFICATION = 13, 98 AUDIO_USAGE_GAME = 14, 99 100 AUDIO_USAGE_CNT, 101 AUDIO_USAGE_MAX = AUDIO_USAGE_CNT - 1, 102} audio_usage_t; 103 104typedef uint32_t audio_flags_mask_t; 105 106/* Do not change these values without updating their counterparts 107 * in frameworks/base/media/java/android/media/AudioAttributes.java 108 */ 109enum { 110 AUDIO_FLAG_AUDIBILITY_ENFORCED = 0x1, 111 AUDIO_FLAG_SECURE = 0x2, 112 AUDIO_FLAG_SCO = 0x4, 113 AUDIO_FLAG_BEACON = 0x8, 114 AUDIO_FLAG_HW_AV_SYNC = 0x10, 115 AUDIO_FLAG_HW_HOTWORD = 0x20, 116}; 117 118/* Do not change these values without updating their counterparts 119 * in frameworks/base/media/java/android/media/MediaRecorder.java, 120 * frameworks/av/services/audiopolicy/AudioPolicyService.cpp, 121 * and system/media/audio_effects/include/audio_effects/audio_effects_conf.h! 122 */ 123typedef enum { 124 AUDIO_SOURCE_DEFAULT = 0, 125 AUDIO_SOURCE_MIC = 1, 126 AUDIO_SOURCE_VOICE_UPLINK = 2, 127 AUDIO_SOURCE_VOICE_DOWNLINK = 3, 128 AUDIO_SOURCE_VOICE_CALL = 4, 129 AUDIO_SOURCE_CAMCORDER = 5, 130 AUDIO_SOURCE_VOICE_RECOGNITION = 6, 131 AUDIO_SOURCE_VOICE_COMMUNICATION = 7, 132 AUDIO_SOURCE_REMOTE_SUBMIX = 8, /* Source for the mix to be presented remotely. */ 133 /* An example of remote presentation is Wifi Display */ 134 /* where a dongle attached to a TV can be used to */ 135 /* play the mix captured by this audio source. */ 136 AUDIO_SOURCE_FM_TUNER = 9, 137 AUDIO_SOURCE_CNT, 138 AUDIO_SOURCE_MAX = AUDIO_SOURCE_CNT - 1, 139 AUDIO_SOURCE_HOTWORD = 1999, /* A low-priority, preemptible audio source for 140 for background software hotword detection. 141 Same tuning as AUDIO_SOURCE_VOICE_RECOGNITION. 142 Used only internally to the framework. Not exposed 143 at the audio HAL. */ 144} audio_source_t; 145 146/* Audio attributes */ 147#define AUDIO_ATTRIBUTES_TAGS_MAX_SIZE 256 148typedef struct { 149 audio_content_type_t content_type; 150 audio_usage_t usage; 151 audio_source_t source; 152 audio_flags_mask_t flags; 153 char tags[AUDIO_ATTRIBUTES_TAGS_MAX_SIZE]; /* UTF8 */ 154} audio_attributes_t; 155 156/* special audio session values 157 * (XXX: should this be living in the audio effects land?) 158 */ 159typedef enum { 160 /* session for effects attached to a particular output stream 161 * (value must be less than 0) 162 */ 163 AUDIO_SESSION_OUTPUT_STAGE = -1, 164 165 /* session for effects applied to output mix. These effects can 166 * be moved by audio policy manager to another output stream 167 * (value must be 0) 168 */ 169 AUDIO_SESSION_OUTPUT_MIX = 0, 170 171 /* application does not specify an explicit session ID to be used, 172 * and requests a new session ID to be allocated 173 * TODO use unique values for AUDIO_SESSION_OUTPUT_MIX and AUDIO_SESSION_ALLOCATE, 174 * after all uses have been updated from 0 to the appropriate symbol, and have been tested. 175 */ 176 AUDIO_SESSION_ALLOCATE = 0, 177} audio_session_t; 178 179/* a unique ID allocated by AudioFlinger for use as a audio_io_handle_t or audio_session_t */ 180typedef int audio_unique_id_t; 181 182#define AUDIO_UNIQUE_ID_ALLOCATE AUDIO_SESSION_ALLOCATE 183 184/* Audio sub formats (see enum audio_format). */ 185 186/* PCM sub formats */ 187typedef enum { 188 /* All of these are in native byte order */ 189 AUDIO_FORMAT_PCM_SUB_16_BIT = 0x1, /* DO NOT CHANGE - PCM signed 16 bits */ 190 AUDIO_FORMAT_PCM_SUB_8_BIT = 0x2, /* DO NOT CHANGE - PCM unsigned 8 bits */ 191 AUDIO_FORMAT_PCM_SUB_32_BIT = 0x3, /* PCM signed .31 fixed point */ 192 AUDIO_FORMAT_PCM_SUB_8_24_BIT = 0x4, /* PCM signed 7.24 fixed point */ 193 AUDIO_FORMAT_PCM_SUB_FLOAT = 0x5, /* PCM single-precision floating point */ 194 AUDIO_FORMAT_PCM_SUB_24_BIT_PACKED = 0x6, /* PCM signed .23 fixed point packed in 3 bytes */ 195} audio_format_pcm_sub_fmt_t; 196 197/* The audio_format_*_sub_fmt_t declarations are not currently used */ 198 199/* MP3 sub format field definition : can use 11 LSBs in the same way as MP3 200 * frame header to specify bit rate, stereo mode, version... 201 */ 202typedef enum { 203 AUDIO_FORMAT_MP3_SUB_NONE = 0x0, 204} audio_format_mp3_sub_fmt_t; 205 206/* AMR NB/WB sub format field definition: specify frame block interleaving, 207 * bandwidth efficient or octet aligned, encoding mode for recording... 208 */ 209typedef enum { 210 AUDIO_FORMAT_AMR_SUB_NONE = 0x0, 211} audio_format_amr_sub_fmt_t; 212 213/* AAC sub format field definition: specify profile or bitrate for recording... */ 214typedef enum { 215 AUDIO_FORMAT_AAC_SUB_MAIN = 0x1, 216 AUDIO_FORMAT_AAC_SUB_LC = 0x2, 217 AUDIO_FORMAT_AAC_SUB_SSR = 0x4, 218 AUDIO_FORMAT_AAC_SUB_LTP = 0x8, 219 AUDIO_FORMAT_AAC_SUB_HE_V1 = 0x10, 220 AUDIO_FORMAT_AAC_SUB_SCALABLE = 0x20, 221 AUDIO_FORMAT_AAC_SUB_ERLC = 0x40, 222 AUDIO_FORMAT_AAC_SUB_LD = 0x80, 223 AUDIO_FORMAT_AAC_SUB_HE_V2 = 0x100, 224 AUDIO_FORMAT_AAC_SUB_ELD = 0x200, 225} audio_format_aac_sub_fmt_t; 226 227/* VORBIS sub format field definition: specify quality for recording... */ 228typedef enum { 229 AUDIO_FORMAT_VORBIS_SUB_NONE = 0x0, 230} audio_format_vorbis_sub_fmt_t; 231 232/* Audio format consists of a main format field (upper 8 bits) and a sub format 233 * field (lower 24 bits). 234 * 235 * The main format indicates the main codec type. The sub format field 236 * indicates options and parameters for each format. The sub format is mainly 237 * used for record to indicate for instance the requested bitrate or profile. 238 * It can also be used for certain formats to give informations not present in 239 * the encoded audio stream (e.g. octet alignement for AMR). 240 */ 241typedef enum { 242 AUDIO_FORMAT_INVALID = 0xFFFFFFFFUL, 243 AUDIO_FORMAT_DEFAULT = 0, 244 AUDIO_FORMAT_PCM = 0x00000000UL, /* DO NOT CHANGE */ 245 AUDIO_FORMAT_MP3 = 0x01000000UL, 246 AUDIO_FORMAT_AMR_NB = 0x02000000UL, 247 AUDIO_FORMAT_AMR_WB = 0x03000000UL, 248 AUDIO_FORMAT_AAC = 0x04000000UL, 249 AUDIO_FORMAT_HE_AAC_V1 = 0x05000000UL, /* Deprecated, Use AUDIO_FORMAT_AAC_HE_V1*/ 250 AUDIO_FORMAT_HE_AAC_V2 = 0x06000000UL, /* Deprecated, Use AUDIO_FORMAT_AAC_HE_V2*/ 251 AUDIO_FORMAT_VORBIS = 0x07000000UL, 252 AUDIO_FORMAT_OPUS = 0x08000000UL, 253 AUDIO_FORMAT_AC3 = 0x09000000UL, 254 AUDIO_FORMAT_E_AC3 = 0x0A000000UL, 255 AUDIO_FORMAT_MAIN_MASK = 0xFF000000UL, 256 AUDIO_FORMAT_SUB_MASK = 0x00FFFFFFUL, 257 258 /* Aliases */ 259 /* note != AudioFormat.ENCODING_PCM_16BIT */ 260 AUDIO_FORMAT_PCM_16_BIT = (AUDIO_FORMAT_PCM | 261 AUDIO_FORMAT_PCM_SUB_16_BIT), 262 /* note != AudioFormat.ENCODING_PCM_8BIT */ 263 AUDIO_FORMAT_PCM_8_BIT = (AUDIO_FORMAT_PCM | 264 AUDIO_FORMAT_PCM_SUB_8_BIT), 265 AUDIO_FORMAT_PCM_32_BIT = (AUDIO_FORMAT_PCM | 266 AUDIO_FORMAT_PCM_SUB_32_BIT), 267 AUDIO_FORMAT_PCM_8_24_BIT = (AUDIO_FORMAT_PCM | 268 AUDIO_FORMAT_PCM_SUB_8_24_BIT), 269 AUDIO_FORMAT_PCM_FLOAT = (AUDIO_FORMAT_PCM | 270 AUDIO_FORMAT_PCM_SUB_FLOAT), 271 AUDIO_FORMAT_PCM_24_BIT_PACKED = (AUDIO_FORMAT_PCM | 272 AUDIO_FORMAT_PCM_SUB_24_BIT_PACKED), 273 AUDIO_FORMAT_AAC_MAIN = (AUDIO_FORMAT_AAC | 274 AUDIO_FORMAT_AAC_SUB_MAIN), 275 AUDIO_FORMAT_AAC_LC = (AUDIO_FORMAT_AAC | 276 AUDIO_FORMAT_AAC_SUB_LC), 277 AUDIO_FORMAT_AAC_SSR = (AUDIO_FORMAT_AAC | 278 AUDIO_FORMAT_AAC_SUB_SSR), 279 AUDIO_FORMAT_AAC_LTP = (AUDIO_FORMAT_AAC | 280 AUDIO_FORMAT_AAC_SUB_LTP), 281 AUDIO_FORMAT_AAC_HE_V1 = (AUDIO_FORMAT_AAC | 282 AUDIO_FORMAT_AAC_SUB_HE_V1), 283 AUDIO_FORMAT_AAC_SCALABLE = (AUDIO_FORMAT_AAC | 284 AUDIO_FORMAT_AAC_SUB_SCALABLE), 285 AUDIO_FORMAT_AAC_ERLC = (AUDIO_FORMAT_AAC | 286 AUDIO_FORMAT_AAC_SUB_ERLC), 287 AUDIO_FORMAT_AAC_LD = (AUDIO_FORMAT_AAC | 288 AUDIO_FORMAT_AAC_SUB_LD), 289 AUDIO_FORMAT_AAC_HE_V2 = (AUDIO_FORMAT_AAC | 290 AUDIO_FORMAT_AAC_SUB_HE_V2), 291 AUDIO_FORMAT_AAC_ELD = (AUDIO_FORMAT_AAC | 292 AUDIO_FORMAT_AAC_SUB_ELD), 293} audio_format_t; 294 295/* For the channel mask for position assignment representation */ 296enum { 297 298/* These can be a complete audio_channel_mask_t. */ 299 300 AUDIO_CHANNEL_NONE = 0x0, 301 AUDIO_CHANNEL_INVALID = 0xC0000000, 302 303/* These can be the bits portion of an audio_channel_mask_t 304 * with representation AUDIO_CHANNEL_REPRESENTATION_POSITION. 305 * Using these bits as a complete audio_channel_mask_t is deprecated. 306 */ 307 308 /* output channels */ 309 AUDIO_CHANNEL_OUT_FRONT_LEFT = 0x1, 310 AUDIO_CHANNEL_OUT_FRONT_RIGHT = 0x2, 311 AUDIO_CHANNEL_OUT_FRONT_CENTER = 0x4, 312 AUDIO_CHANNEL_OUT_LOW_FREQUENCY = 0x8, 313 AUDIO_CHANNEL_OUT_BACK_LEFT = 0x10, 314 AUDIO_CHANNEL_OUT_BACK_RIGHT = 0x20, 315 AUDIO_CHANNEL_OUT_FRONT_LEFT_OF_CENTER = 0x40, 316 AUDIO_CHANNEL_OUT_FRONT_RIGHT_OF_CENTER = 0x80, 317 AUDIO_CHANNEL_OUT_BACK_CENTER = 0x100, 318 AUDIO_CHANNEL_OUT_SIDE_LEFT = 0x200, 319 AUDIO_CHANNEL_OUT_SIDE_RIGHT = 0x400, 320 AUDIO_CHANNEL_OUT_TOP_CENTER = 0x800, 321 AUDIO_CHANNEL_OUT_TOP_FRONT_LEFT = 0x1000, 322 AUDIO_CHANNEL_OUT_TOP_FRONT_CENTER = 0x2000, 323 AUDIO_CHANNEL_OUT_TOP_FRONT_RIGHT = 0x4000, 324 AUDIO_CHANNEL_OUT_TOP_BACK_LEFT = 0x8000, 325 AUDIO_CHANNEL_OUT_TOP_BACK_CENTER = 0x10000, 326 AUDIO_CHANNEL_OUT_TOP_BACK_RIGHT = 0x20000, 327 328/* TODO: should these be considered complete channel masks, or only bits? */ 329 330 AUDIO_CHANNEL_OUT_MONO = AUDIO_CHANNEL_OUT_FRONT_LEFT, 331 AUDIO_CHANNEL_OUT_STEREO = (AUDIO_CHANNEL_OUT_FRONT_LEFT | 332 AUDIO_CHANNEL_OUT_FRONT_RIGHT), 333 AUDIO_CHANNEL_OUT_QUAD = (AUDIO_CHANNEL_OUT_FRONT_LEFT | 334 AUDIO_CHANNEL_OUT_FRONT_RIGHT | 335 AUDIO_CHANNEL_OUT_BACK_LEFT | 336 AUDIO_CHANNEL_OUT_BACK_RIGHT), 337 AUDIO_CHANNEL_OUT_QUAD_BACK = AUDIO_CHANNEL_OUT_QUAD, 338 /* like AUDIO_CHANNEL_OUT_QUAD_BACK with *_SIDE_* instead of *_BACK_* */ 339 AUDIO_CHANNEL_OUT_QUAD_SIDE = (AUDIO_CHANNEL_OUT_FRONT_LEFT | 340 AUDIO_CHANNEL_OUT_FRONT_RIGHT | 341 AUDIO_CHANNEL_OUT_SIDE_LEFT | 342 AUDIO_CHANNEL_OUT_SIDE_RIGHT), 343 AUDIO_CHANNEL_OUT_5POINT1 = (AUDIO_CHANNEL_OUT_FRONT_LEFT | 344 AUDIO_CHANNEL_OUT_FRONT_RIGHT | 345 AUDIO_CHANNEL_OUT_FRONT_CENTER | 346 AUDIO_CHANNEL_OUT_LOW_FREQUENCY | 347 AUDIO_CHANNEL_OUT_BACK_LEFT | 348 AUDIO_CHANNEL_OUT_BACK_RIGHT), 349 AUDIO_CHANNEL_OUT_5POINT1_BACK = AUDIO_CHANNEL_OUT_5POINT1, 350 /* like AUDIO_CHANNEL_OUT_5POINT1_BACK with *_SIDE_* instead of *_BACK_* */ 351 AUDIO_CHANNEL_OUT_5POINT1_SIDE = (AUDIO_CHANNEL_OUT_FRONT_LEFT | 352 AUDIO_CHANNEL_OUT_FRONT_RIGHT | 353 AUDIO_CHANNEL_OUT_FRONT_CENTER | 354 AUDIO_CHANNEL_OUT_LOW_FREQUENCY | 355 AUDIO_CHANNEL_OUT_SIDE_LEFT | 356 AUDIO_CHANNEL_OUT_SIDE_RIGHT), 357 // matches the correct AudioFormat.CHANNEL_OUT_7POINT1_SURROUND definition for 7.1 358 AUDIO_CHANNEL_OUT_7POINT1 = (AUDIO_CHANNEL_OUT_FRONT_LEFT | 359 AUDIO_CHANNEL_OUT_FRONT_RIGHT | 360 AUDIO_CHANNEL_OUT_FRONT_CENTER | 361 AUDIO_CHANNEL_OUT_LOW_FREQUENCY | 362 AUDIO_CHANNEL_OUT_BACK_LEFT | 363 AUDIO_CHANNEL_OUT_BACK_RIGHT | 364 AUDIO_CHANNEL_OUT_SIDE_LEFT | 365 AUDIO_CHANNEL_OUT_SIDE_RIGHT), 366 AUDIO_CHANNEL_OUT_ALL = (AUDIO_CHANNEL_OUT_FRONT_LEFT | 367 AUDIO_CHANNEL_OUT_FRONT_RIGHT | 368 AUDIO_CHANNEL_OUT_FRONT_CENTER | 369 AUDIO_CHANNEL_OUT_LOW_FREQUENCY | 370 AUDIO_CHANNEL_OUT_BACK_LEFT | 371 AUDIO_CHANNEL_OUT_BACK_RIGHT | 372 AUDIO_CHANNEL_OUT_FRONT_LEFT_OF_CENTER | 373 AUDIO_CHANNEL_OUT_FRONT_RIGHT_OF_CENTER | 374 AUDIO_CHANNEL_OUT_BACK_CENTER| 375 AUDIO_CHANNEL_OUT_SIDE_LEFT| 376 AUDIO_CHANNEL_OUT_SIDE_RIGHT| 377 AUDIO_CHANNEL_OUT_TOP_CENTER| 378 AUDIO_CHANNEL_OUT_TOP_FRONT_LEFT| 379 AUDIO_CHANNEL_OUT_TOP_FRONT_CENTER| 380 AUDIO_CHANNEL_OUT_TOP_FRONT_RIGHT| 381 AUDIO_CHANNEL_OUT_TOP_BACK_LEFT| 382 AUDIO_CHANNEL_OUT_TOP_BACK_CENTER| 383 AUDIO_CHANNEL_OUT_TOP_BACK_RIGHT), 384 385/* These are bits only, not complete values */ 386 387 /* input channels */ 388 AUDIO_CHANNEL_IN_LEFT = 0x4, 389 AUDIO_CHANNEL_IN_RIGHT = 0x8, 390 AUDIO_CHANNEL_IN_FRONT = 0x10, 391 AUDIO_CHANNEL_IN_BACK = 0x20, 392 AUDIO_CHANNEL_IN_LEFT_PROCESSED = 0x40, 393 AUDIO_CHANNEL_IN_RIGHT_PROCESSED = 0x80, 394 AUDIO_CHANNEL_IN_FRONT_PROCESSED = 0x100, 395 AUDIO_CHANNEL_IN_BACK_PROCESSED = 0x200, 396 AUDIO_CHANNEL_IN_PRESSURE = 0x400, 397 AUDIO_CHANNEL_IN_X_AXIS = 0x800, 398 AUDIO_CHANNEL_IN_Y_AXIS = 0x1000, 399 AUDIO_CHANNEL_IN_Z_AXIS = 0x2000, 400 AUDIO_CHANNEL_IN_VOICE_UPLINK = 0x4000, 401 AUDIO_CHANNEL_IN_VOICE_DNLINK = 0x8000, 402 403/* TODO: should these be considered complete channel masks, or only bits, or deprecated? */ 404 405 AUDIO_CHANNEL_IN_MONO = AUDIO_CHANNEL_IN_FRONT, 406 AUDIO_CHANNEL_IN_STEREO = (AUDIO_CHANNEL_IN_LEFT | AUDIO_CHANNEL_IN_RIGHT), 407 AUDIO_CHANNEL_IN_FRONT_BACK = (AUDIO_CHANNEL_IN_FRONT | AUDIO_CHANNEL_IN_BACK), 408 AUDIO_CHANNEL_IN_ALL = (AUDIO_CHANNEL_IN_LEFT | 409 AUDIO_CHANNEL_IN_RIGHT | 410 AUDIO_CHANNEL_IN_FRONT | 411 AUDIO_CHANNEL_IN_BACK| 412 AUDIO_CHANNEL_IN_LEFT_PROCESSED | 413 AUDIO_CHANNEL_IN_RIGHT_PROCESSED | 414 AUDIO_CHANNEL_IN_FRONT_PROCESSED | 415 AUDIO_CHANNEL_IN_BACK_PROCESSED| 416 AUDIO_CHANNEL_IN_PRESSURE | 417 AUDIO_CHANNEL_IN_X_AXIS | 418 AUDIO_CHANNEL_IN_Y_AXIS | 419 AUDIO_CHANNEL_IN_Z_AXIS | 420 AUDIO_CHANNEL_IN_VOICE_UPLINK | 421 AUDIO_CHANNEL_IN_VOICE_DNLINK), 422}; 423 424/* A channel mask per se only defines the presence or absence of a channel, not the order. 425 * But see AUDIO_INTERLEAVE_* below for the platform convention of order. 426 * 427 * audio_channel_mask_t is an opaque type and its internal layout should not 428 * be assumed as it may change in the future. 429 * Instead, always use the functions declared in this header to examine. 430 * 431 * These are the current representations: 432 * 433 * AUDIO_CHANNEL_REPRESENTATION_POSITION 434 * is a channel mask representation for position assignment. 435 * Each low-order bit corresponds to the spatial position of a transducer (output), 436 * or interpretation of channel (input). 437 * The user of a channel mask needs to know the context of whether it is for output or input. 438 * The constants AUDIO_CHANNEL_OUT_* or AUDIO_CHANNEL_IN_* apply to the bits portion. 439 * It is not permitted for no bits to be set. 440 * 441 * AUDIO_CHANNEL_REPRESENTATION_INDEX 442 * is a channel mask representation for index assignment. 443 * Each low-order bit corresponds to a selected channel. 444 * There is no platform interpretation of the various bits. 445 * There is no concept of output or input. 446 * It is not permitted for no bits to be set. 447 * 448 * All other representations are reserved for future use. 449 * 450 * Warning: current representation distinguishes between input and output, but this will not the be 451 * case in future revisions of the platform. Wherever there is an ambiguity between input and output 452 * that is currently resolved by checking the channel mask, the implementer should look for ways to 453 * fix it with additional information outside of the mask. 454 */ 455typedef uint32_t audio_channel_mask_t; 456 457/* Maximum number of channels for all representations */ 458#define AUDIO_CHANNEL_COUNT_MAX 30 459 460/* log(2) of maximum number of representations, not part of public API */ 461#define AUDIO_CHANNEL_REPRESENTATION_LOG2 2 462 463/* Representations */ 464typedef enum { 465 AUDIO_CHANNEL_REPRESENTATION_POSITION = 0, // must be zero for compatibility 466 // 1 is reserved for future use 467 AUDIO_CHANNEL_REPRESENTATION_INDEX = 2, 468 // 3 is reserved for future use 469} audio_channel_representation_t; 470 471/* The return value is undefined if the channel mask is invalid. */ 472static inline uint32_t audio_channel_mask_get_bits(audio_channel_mask_t channel) 473{ 474 return channel & ((1 << AUDIO_CHANNEL_COUNT_MAX) - 1); 475} 476 477/* The return value is undefined if the channel mask is invalid. */ 478static inline audio_channel_representation_t audio_channel_mask_get_representation( 479 audio_channel_mask_t channel) 480{ 481 // The right shift should be sufficient, but also "and" for safety in case mask is not 32 bits 482 return (audio_channel_representation_t) 483 ((channel >> AUDIO_CHANNEL_COUNT_MAX) & ((1 << AUDIO_CHANNEL_REPRESENTATION_LOG2) - 1)); 484} 485 486/* Returns true if the channel mask is valid, 487 * or returns false for AUDIO_CHANNEL_NONE, AUDIO_CHANNEL_INVALID, and other invalid values. 488 * This function is unable to determine whether a channel mask for position assignment 489 * is invalid because an output mask has an invalid output bit set, 490 * or because an input mask has an invalid input bit set. 491 * All other APIs that take a channel mask assume that it is valid. 492 */ 493static inline bool audio_channel_mask_is_valid(audio_channel_mask_t channel) 494{ 495 uint32_t bits = audio_channel_mask_get_bits(channel); 496 audio_channel_representation_t representation = audio_channel_mask_get_representation(channel); 497 switch (representation) { 498 case AUDIO_CHANNEL_REPRESENTATION_POSITION: 499 case AUDIO_CHANNEL_REPRESENTATION_INDEX: 500 break; 501 default: 502 bits = 0; 503 break; 504 } 505 return bits != 0; 506} 507 508/* Not part of public API */ 509static inline audio_channel_mask_t audio_channel_mask_from_representation_and_bits( 510 audio_channel_representation_t representation, uint32_t bits) 511{ 512 return (audio_channel_mask_t) ((representation << AUDIO_CHANNEL_COUNT_MAX) | bits); 513} 514 515/* Expresses the convention when stereo audio samples are stored interleaved 516 * in an array. This should improve readability by allowing code to use 517 * symbolic indices instead of hard-coded [0] and [1]. 518 * 519 * For multi-channel beyond stereo, the platform convention is that channels 520 * are interleaved in order from least significant channel mask bit 521 * to most significant channel mask bit, with unused bits skipped. 522 * Any exceptions to this convention will be noted at the appropriate API. 523 */ 524enum { 525 AUDIO_INTERLEAVE_LEFT = 0, 526 AUDIO_INTERLEAVE_RIGHT = 1, 527}; 528 529typedef enum { 530 AUDIO_MODE_INVALID = -2, 531 AUDIO_MODE_CURRENT = -1, 532 AUDIO_MODE_NORMAL = 0, 533 AUDIO_MODE_RINGTONE = 1, 534 AUDIO_MODE_IN_CALL = 2, 535 AUDIO_MODE_IN_COMMUNICATION = 3, 536 537 AUDIO_MODE_CNT, 538 AUDIO_MODE_MAX = AUDIO_MODE_CNT - 1, 539} audio_mode_t; 540 541/* This enum is deprecated */ 542typedef enum { 543 AUDIO_IN_ACOUSTICS_NONE = 0, 544 AUDIO_IN_ACOUSTICS_AGC_ENABLE = 0x0001, 545 AUDIO_IN_ACOUSTICS_AGC_DISABLE = 0, 546 AUDIO_IN_ACOUSTICS_NS_ENABLE = 0x0002, 547 AUDIO_IN_ACOUSTICS_NS_DISABLE = 0, 548 AUDIO_IN_ACOUSTICS_TX_IIR_ENABLE = 0x0004, 549 AUDIO_IN_ACOUSTICS_TX_DISABLE = 0, 550} audio_in_acoustics_t; 551 552enum { 553 AUDIO_DEVICE_NONE = 0x0, 554 /* reserved bits */ 555 AUDIO_DEVICE_BIT_IN = 0x80000000, 556 AUDIO_DEVICE_BIT_DEFAULT = 0x40000000, 557 /* output devices */ 558 AUDIO_DEVICE_OUT_EARPIECE = 0x1, 559 AUDIO_DEVICE_OUT_SPEAKER = 0x2, 560 AUDIO_DEVICE_OUT_WIRED_HEADSET = 0x4, 561 AUDIO_DEVICE_OUT_WIRED_HEADPHONE = 0x8, 562 AUDIO_DEVICE_OUT_BLUETOOTH_SCO = 0x10, 563 AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET = 0x20, 564 AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT = 0x40, 565 AUDIO_DEVICE_OUT_BLUETOOTH_A2DP = 0x80, 566 AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES = 0x100, 567 AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER = 0x200, 568 AUDIO_DEVICE_OUT_AUX_DIGITAL = 0x400, 569 AUDIO_DEVICE_OUT_HDMI = AUDIO_DEVICE_OUT_AUX_DIGITAL, 570 /* uses an analog connection (multiplexed over the USB connector pins for instance) */ 571 AUDIO_DEVICE_OUT_ANLG_DOCK_HEADSET = 0x800, 572 AUDIO_DEVICE_OUT_DGTL_DOCK_HEADSET = 0x1000, 573 /* USB accessory mode: your Android device is a USB device and the dock is a USB host */ 574 AUDIO_DEVICE_OUT_USB_ACCESSORY = 0x2000, 575 /* USB host mode: your Android device is a USB host and the dock is a USB device */ 576 AUDIO_DEVICE_OUT_USB_DEVICE = 0x4000, 577 AUDIO_DEVICE_OUT_REMOTE_SUBMIX = 0x8000, 578 /* Telephony voice TX path */ 579 AUDIO_DEVICE_OUT_TELEPHONY_TX = 0x10000, 580 /* Analog jack with line impedance detected */ 581 AUDIO_DEVICE_OUT_LINE = 0x20000, 582 /* HDMI Audio Return Channel */ 583 AUDIO_DEVICE_OUT_HDMI_ARC = 0x40000, 584 /* S/PDIF out */ 585 AUDIO_DEVICE_OUT_SPDIF = 0x80000, 586 /* FM transmitter out */ 587 AUDIO_DEVICE_OUT_FM = 0x100000, 588 /* Line out for av devices */ 589 AUDIO_DEVICE_OUT_AUX_LINE = 0x200000, 590 /* limited-output speaker device for acoustic safety */ 591 AUDIO_DEVICE_OUT_SPEAKER_SAFE = 0x400000, 592 AUDIO_DEVICE_OUT_DEFAULT = AUDIO_DEVICE_BIT_DEFAULT, 593 AUDIO_DEVICE_OUT_ALL = (AUDIO_DEVICE_OUT_EARPIECE | 594 AUDIO_DEVICE_OUT_SPEAKER | 595 AUDIO_DEVICE_OUT_WIRED_HEADSET | 596 AUDIO_DEVICE_OUT_WIRED_HEADPHONE | 597 AUDIO_DEVICE_OUT_BLUETOOTH_SCO | 598 AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET | 599 AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT | 600 AUDIO_DEVICE_OUT_BLUETOOTH_A2DP | 601 AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES | 602 AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER | 603 AUDIO_DEVICE_OUT_HDMI | 604 AUDIO_DEVICE_OUT_ANLG_DOCK_HEADSET | 605 AUDIO_DEVICE_OUT_DGTL_DOCK_HEADSET | 606 AUDIO_DEVICE_OUT_USB_ACCESSORY | 607 AUDIO_DEVICE_OUT_USB_DEVICE | 608 AUDIO_DEVICE_OUT_REMOTE_SUBMIX | 609 AUDIO_DEVICE_OUT_TELEPHONY_TX | 610 AUDIO_DEVICE_OUT_LINE | 611 AUDIO_DEVICE_OUT_HDMI_ARC | 612 AUDIO_DEVICE_OUT_SPDIF | 613 AUDIO_DEVICE_OUT_FM | 614 AUDIO_DEVICE_OUT_AUX_LINE | 615 AUDIO_DEVICE_OUT_SPEAKER_SAFE | 616 AUDIO_DEVICE_OUT_DEFAULT), 617 AUDIO_DEVICE_OUT_ALL_A2DP = (AUDIO_DEVICE_OUT_BLUETOOTH_A2DP | 618 AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_HEADPHONES | 619 AUDIO_DEVICE_OUT_BLUETOOTH_A2DP_SPEAKER), 620 AUDIO_DEVICE_OUT_ALL_SCO = (AUDIO_DEVICE_OUT_BLUETOOTH_SCO | 621 AUDIO_DEVICE_OUT_BLUETOOTH_SCO_HEADSET | 622 AUDIO_DEVICE_OUT_BLUETOOTH_SCO_CARKIT), 623 AUDIO_DEVICE_OUT_ALL_USB = (AUDIO_DEVICE_OUT_USB_ACCESSORY | 624 AUDIO_DEVICE_OUT_USB_DEVICE), 625 626 /* input devices */ 627 AUDIO_DEVICE_IN_COMMUNICATION = AUDIO_DEVICE_BIT_IN | 0x1, 628 AUDIO_DEVICE_IN_AMBIENT = AUDIO_DEVICE_BIT_IN | 0x2, 629 AUDIO_DEVICE_IN_BUILTIN_MIC = AUDIO_DEVICE_BIT_IN | 0x4, 630 AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET = AUDIO_DEVICE_BIT_IN | 0x8, 631 AUDIO_DEVICE_IN_WIRED_HEADSET = AUDIO_DEVICE_BIT_IN | 0x10, 632 AUDIO_DEVICE_IN_AUX_DIGITAL = AUDIO_DEVICE_BIT_IN | 0x20, 633 AUDIO_DEVICE_IN_HDMI = AUDIO_DEVICE_IN_AUX_DIGITAL, 634 /* Telephony voice RX path */ 635 AUDIO_DEVICE_IN_VOICE_CALL = AUDIO_DEVICE_BIT_IN | 0x40, 636 AUDIO_DEVICE_IN_TELEPHONY_RX = AUDIO_DEVICE_IN_VOICE_CALL, 637 AUDIO_DEVICE_IN_BACK_MIC = AUDIO_DEVICE_BIT_IN | 0x80, 638 AUDIO_DEVICE_IN_REMOTE_SUBMIX = AUDIO_DEVICE_BIT_IN | 0x100, 639 AUDIO_DEVICE_IN_ANLG_DOCK_HEADSET = AUDIO_DEVICE_BIT_IN | 0x200, 640 AUDIO_DEVICE_IN_DGTL_DOCK_HEADSET = AUDIO_DEVICE_BIT_IN | 0x400, 641 AUDIO_DEVICE_IN_USB_ACCESSORY = AUDIO_DEVICE_BIT_IN | 0x800, 642 AUDIO_DEVICE_IN_USB_DEVICE = AUDIO_DEVICE_BIT_IN | 0x1000, 643 /* FM tuner input */ 644 AUDIO_DEVICE_IN_FM_TUNER = AUDIO_DEVICE_BIT_IN | 0x2000, 645 /* TV tuner input */ 646 AUDIO_DEVICE_IN_TV_TUNER = AUDIO_DEVICE_BIT_IN | 0x4000, 647 /* Analog jack with line impedance detected */ 648 AUDIO_DEVICE_IN_LINE = AUDIO_DEVICE_BIT_IN | 0x8000, 649 /* S/PDIF in */ 650 AUDIO_DEVICE_IN_SPDIF = AUDIO_DEVICE_BIT_IN | 0x10000, 651 AUDIO_DEVICE_IN_BLUETOOTH_A2DP = AUDIO_DEVICE_BIT_IN | 0x20000, 652 AUDIO_DEVICE_IN_LOOPBACK = AUDIO_DEVICE_BIT_IN | 0x40000, 653 AUDIO_DEVICE_IN_DEFAULT = AUDIO_DEVICE_BIT_IN | AUDIO_DEVICE_BIT_DEFAULT, 654 655 AUDIO_DEVICE_IN_ALL = (AUDIO_DEVICE_IN_COMMUNICATION | 656 AUDIO_DEVICE_IN_AMBIENT | 657 AUDIO_DEVICE_IN_BUILTIN_MIC | 658 AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET | 659 AUDIO_DEVICE_IN_WIRED_HEADSET | 660 AUDIO_DEVICE_IN_HDMI | 661 AUDIO_DEVICE_IN_TELEPHONY_RX | 662 AUDIO_DEVICE_IN_BACK_MIC | 663 AUDIO_DEVICE_IN_REMOTE_SUBMIX | 664 AUDIO_DEVICE_IN_ANLG_DOCK_HEADSET | 665 AUDIO_DEVICE_IN_DGTL_DOCK_HEADSET | 666 AUDIO_DEVICE_IN_USB_ACCESSORY | 667 AUDIO_DEVICE_IN_USB_DEVICE | 668 AUDIO_DEVICE_IN_FM_TUNER | 669 AUDIO_DEVICE_IN_TV_TUNER | 670 AUDIO_DEVICE_IN_LINE | 671 AUDIO_DEVICE_IN_SPDIF | 672 AUDIO_DEVICE_IN_BLUETOOTH_A2DP | 673 AUDIO_DEVICE_IN_LOOPBACK | 674 AUDIO_DEVICE_IN_DEFAULT), 675 AUDIO_DEVICE_IN_ALL_SCO = AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET, 676 AUDIO_DEVICE_IN_ALL_USB = (AUDIO_DEVICE_IN_USB_ACCESSORY | 677 AUDIO_DEVICE_IN_USB_DEVICE), 678}; 679 680typedef uint32_t audio_devices_t; 681 682/* the audio output flags serve two purposes: 683 * - when an AudioTrack is created they indicate a "wish" to be connected to an 684 * output stream with attributes corresponding to the specified flags 685 * - when present in an output profile descriptor listed for a particular audio 686 * hardware module, they indicate that an output stream can be opened that 687 * supports the attributes indicated by the flags. 688 * the audio policy manager will try to match the flags in the request 689 * (when getOuput() is called) to an available output stream. 690 */ 691typedef enum { 692 AUDIO_OUTPUT_FLAG_NONE = 0x0, // no attributes 693 AUDIO_OUTPUT_FLAG_DIRECT = 0x1, // this output directly connects a track 694 // to one output stream: no software mixer 695 AUDIO_OUTPUT_FLAG_PRIMARY = 0x2, // this output is the primary output of 696 // the device. It is unique and must be 697 // present. It is opened by default and 698 // receives routing, audio mode and volume 699 // controls related to voice calls. 700 AUDIO_OUTPUT_FLAG_FAST = 0x4, // output supports "fast tracks", 701 // defined elsewhere 702 AUDIO_OUTPUT_FLAG_DEEP_BUFFER = 0x8, // use deep audio buffers 703 AUDIO_OUTPUT_FLAG_COMPRESS_OFFLOAD = 0x10, // offload playback of compressed 704 // streams to hardware codec 705 AUDIO_OUTPUT_FLAG_NON_BLOCKING = 0x20, // use non-blocking write 706 AUDIO_OUTPUT_FLAG_HW_AV_SYNC = 0x40 // output uses a hardware A/V synchronization source 707} audio_output_flags_t; 708 709/* The audio input flags are analogous to audio output flags. 710 * Currently they are used only when an AudioRecord is created, 711 * to indicate a preference to be connected to an input stream with 712 * attributes corresponding to the specified flags. 713 */ 714typedef enum { 715 AUDIO_INPUT_FLAG_NONE = 0x0, // no attributes 716 AUDIO_INPUT_FLAG_FAST = 0x1, // prefer an input that supports "fast tracks" 717 AUDIO_INPUT_FLAG_HW_HOTWORD = 0x2, // prefer an input that captures from hw hotword source 718} audio_input_flags_t; 719 720/* Additional information about compressed streams offloaded to 721 * hardware playback 722 * The version and size fields must be initialized by the caller by using 723 * one of the constants defined here. 724 */ 725typedef struct { 726 uint16_t version; // version of the info structure 727 uint16_t size; // total size of the structure including version and size 728 uint32_t sample_rate; // sample rate in Hz 729 audio_channel_mask_t channel_mask; // channel mask 730 audio_format_t format; // audio format 731 audio_stream_type_t stream_type; // stream type 732 uint32_t bit_rate; // bit rate in bits per second 733 int64_t duration_us; // duration in microseconds, -1 if unknown 734 bool has_video; // true if stream is tied to a video stream 735 bool is_streaming; // true if streaming, false if local playback 736} audio_offload_info_t; 737 738#define AUDIO_MAKE_OFFLOAD_INFO_VERSION(maj,min) \ 739 ((((maj) & 0xff) << 8) | ((min) & 0xff)) 740 741#define AUDIO_OFFLOAD_INFO_VERSION_0_1 AUDIO_MAKE_OFFLOAD_INFO_VERSION(0, 1) 742#define AUDIO_OFFLOAD_INFO_VERSION_CURRENT AUDIO_OFFLOAD_INFO_VERSION_0_1 743 744static const audio_offload_info_t AUDIO_INFO_INITIALIZER = { 745 version: AUDIO_OFFLOAD_INFO_VERSION_CURRENT, 746 size: sizeof(audio_offload_info_t), 747 sample_rate: 0, 748 channel_mask: 0, 749 format: AUDIO_FORMAT_DEFAULT, 750 stream_type: AUDIO_STREAM_VOICE_CALL, 751 bit_rate: 0, 752 duration_us: 0, 753 has_video: false, 754 is_streaming: false 755}; 756 757/* common audio stream configuration parameters 758 * You should memset() the entire structure to zero before use to 759 * ensure forward compatibility 760 */ 761struct audio_config { 762 uint32_t sample_rate; 763 audio_channel_mask_t channel_mask; 764 audio_format_t format; 765 audio_offload_info_t offload_info; 766 size_t frame_count; 767}; 768typedef struct audio_config audio_config_t; 769 770static const audio_config_t AUDIO_CONFIG_INITIALIZER = { 771 sample_rate: 0, 772 channel_mask: AUDIO_CHANNEL_NONE, 773 format: AUDIO_FORMAT_DEFAULT, 774 offload_info: { 775 version: AUDIO_OFFLOAD_INFO_VERSION_CURRENT, 776 size: sizeof(audio_offload_info_t), 777 sample_rate: 0, 778 channel_mask: 0, 779 format: AUDIO_FORMAT_DEFAULT, 780 stream_type: AUDIO_STREAM_VOICE_CALL, 781 bit_rate: 0, 782 duration_us: 0, 783 has_video: false, 784 is_streaming: false 785 }, 786 frame_count: 0, 787}; 788 789 790/* audio hw module handle functions or structures referencing a module */ 791typedef int audio_module_handle_t; 792 793/****************************** 794 * Volume control 795 *****************************/ 796 797/* If the audio hardware supports gain control on some audio paths, 798 * the platform can expose them in the audio_policy.conf file. The audio HAL 799 * will then implement gain control functions that will use the following data 800 * structures. */ 801 802/* Type of gain control exposed by an audio port */ 803#define AUDIO_GAIN_MODE_JOINT 0x1 /* supports joint channel gain control */ 804#define AUDIO_GAIN_MODE_CHANNELS 0x2 /* supports separate channel gain control */ 805#define AUDIO_GAIN_MODE_RAMP 0x4 /* supports gain ramps */ 806 807typedef uint32_t audio_gain_mode_t; 808 809 810/* An audio_gain struct is a representation of a gain stage. 811 * A gain stage is always attached to an audio port. */ 812struct audio_gain { 813 audio_gain_mode_t mode; /* e.g. AUDIO_GAIN_MODE_JOINT */ 814 audio_channel_mask_t channel_mask; /* channels which gain an be controlled. 815 N/A if AUDIO_GAIN_MODE_CHANNELS is not supported */ 816 int min_value; /* minimum gain value in millibels */ 817 int max_value; /* maximum gain value in millibels */ 818 int default_value; /* default gain value in millibels */ 819 unsigned int step_value; /* gain step in millibels */ 820 unsigned int min_ramp_ms; /* minimum ramp duration in ms */ 821 unsigned int max_ramp_ms; /* maximum ramp duration in ms */ 822}; 823 824/* The gain configuration structure is used to get or set the gain values of a 825 * given port */ 826struct audio_gain_config { 827 int index; /* index of the corresponding audio_gain in the 828 audio_port gains[] table */ 829 audio_gain_mode_t mode; /* mode requested for this command */ 830 audio_channel_mask_t channel_mask; /* channels which gain value follows. 831 N/A in joint mode */ 832 int values[sizeof(audio_channel_mask_t) * 8]; /* gain values in millibels 833 for each channel ordered from LSb to MSb in 834 channel mask. The number of values is 1 in joint 835 mode or popcount(channel_mask) */ 836 unsigned int ramp_duration_ms; /* ramp duration in ms */ 837}; 838 839/****************************** 840 * Routing control 841 *****************************/ 842 843/* Types defined here are used to describe an audio source or sink at internal 844 * framework interfaces (audio policy, patch panel) or at the audio HAL. 845 * Sink and sources are grouped in a concept of “audio port” representing an 846 * audio end point at the edge of the system managed by the module exposing 847 * the interface. */ 848 849/* Audio port role: either source or sink */ 850typedef enum { 851 AUDIO_PORT_ROLE_NONE, 852 AUDIO_PORT_ROLE_SOURCE, 853 AUDIO_PORT_ROLE_SINK, 854} audio_port_role_t; 855 856/* Audio port type indicates if it is a session (e.g AudioTrack), 857 * a mix (e.g PlaybackThread output) or a physical device 858 * (e.g AUDIO_DEVICE_OUT_SPEAKER) */ 859typedef enum { 860 AUDIO_PORT_TYPE_NONE, 861 AUDIO_PORT_TYPE_DEVICE, 862 AUDIO_PORT_TYPE_MIX, 863 AUDIO_PORT_TYPE_SESSION, 864} audio_port_type_t; 865 866/* Each port has a unique ID or handle allocated by policy manager */ 867typedef int audio_port_handle_t; 868#define AUDIO_PORT_HANDLE_NONE 0 869 870 871/* maximum audio device address length */ 872#define AUDIO_DEVICE_MAX_ADDRESS_LEN 32 873 874/* extension for audio port configuration structure when the audio port is a 875 * hardware device */ 876struct audio_port_config_device_ext { 877 audio_module_handle_t hw_module; /* module the device is attached to */ 878 audio_devices_t type; /* device type (e.g AUDIO_DEVICE_OUT_SPEAKER) */ 879 char address[AUDIO_DEVICE_MAX_ADDRESS_LEN]; /* device address. "" if N/A */ 880}; 881 882/* extension for audio port configuration structure when the audio port is a 883 * sub mix */ 884struct audio_port_config_mix_ext { 885 audio_module_handle_t hw_module; /* module the stream is attached to */ 886 audio_io_handle_t handle; /* I/O handle of the input/output stream */ 887 union { 888 //TODO: change use case for output streams: use strategy and mixer attributes 889 audio_stream_type_t stream; 890 audio_source_t source; 891 } usecase; 892}; 893 894/* extension for audio port configuration structure when the audio port is an 895 * audio session */ 896struct audio_port_config_session_ext { 897 audio_session_t session; /* audio session */ 898}; 899 900/* Flags indicating which fields are to be considered in struct audio_port_config */ 901#define AUDIO_PORT_CONFIG_SAMPLE_RATE 0x1 902#define AUDIO_PORT_CONFIG_CHANNEL_MASK 0x2 903#define AUDIO_PORT_CONFIG_FORMAT 0x4 904#define AUDIO_PORT_CONFIG_GAIN 0x8 905#define AUDIO_PORT_CONFIG_ALL (AUDIO_PORT_CONFIG_SAMPLE_RATE | \ 906 AUDIO_PORT_CONFIG_CHANNEL_MASK | \ 907 AUDIO_PORT_CONFIG_FORMAT | \ 908 AUDIO_PORT_CONFIG_GAIN) 909 910/* audio port configuration structure used to specify a particular configuration of 911 * an audio port */ 912struct audio_port_config { 913 audio_port_handle_t id; /* port unique ID */ 914 audio_port_role_t role; /* sink or source */ 915 audio_port_type_t type; /* device, mix ... */ 916 unsigned int config_mask; /* e.g AUDIO_PORT_CONFIG_ALL */ 917 unsigned int sample_rate; /* sampling rate in Hz */ 918 audio_channel_mask_t channel_mask; /* channel mask if applicable */ 919 audio_format_t format; /* format if applicable */ 920 struct audio_gain_config gain; /* gain to apply if applicable */ 921 union { 922 struct audio_port_config_device_ext device; /* device specific info */ 923 struct audio_port_config_mix_ext mix; /* mix specific info */ 924 struct audio_port_config_session_ext session; /* session specific info */ 925 } ext; 926}; 927 928 929/* max number of sampling rates in audio port */ 930#define AUDIO_PORT_MAX_SAMPLING_RATES 16 931/* max number of channel masks in audio port */ 932#define AUDIO_PORT_MAX_CHANNEL_MASKS 16 933/* max number of audio formats in audio port */ 934#define AUDIO_PORT_MAX_FORMATS 16 935/* max number of gain controls in audio port */ 936#define AUDIO_PORT_MAX_GAINS 16 937 938/* extension for audio port structure when the audio port is a hardware device */ 939struct audio_port_device_ext { 940 audio_module_handle_t hw_module; /* module the device is attached to */ 941 audio_devices_t type; /* device type (e.g AUDIO_DEVICE_OUT_SPEAKER) */ 942 char address[AUDIO_DEVICE_MAX_ADDRESS_LEN]; 943}; 944 945/* Latency class of the audio mix */ 946typedef enum { 947 AUDIO_LATENCY_LOW, 948 AUDIO_LATENCY_NORMAL, 949} audio_mix_latency_class_t; 950 951/* extension for audio port structure when the audio port is a sub mix */ 952struct audio_port_mix_ext { 953 audio_module_handle_t hw_module; /* module the stream is attached to */ 954 audio_io_handle_t handle; /* I/O handle of the input.output stream */ 955 audio_mix_latency_class_t latency_class; /* latency class */ 956 // other attributes: routing strategies 957}; 958 959/* extension for audio port structure when the audio port is an audio session */ 960struct audio_port_session_ext { 961 audio_session_t session; /* audio session */ 962}; 963 964 965struct audio_port { 966 audio_port_handle_t id; /* port unique ID */ 967 audio_port_role_t role; /* sink or source */ 968 audio_port_type_t type; /* device, mix ... */ 969 unsigned int num_sample_rates; /* number of sampling rates in following array */ 970 unsigned int sample_rates[AUDIO_PORT_MAX_SAMPLING_RATES]; 971 unsigned int num_channel_masks; /* number of channel masks in following array */ 972 audio_channel_mask_t channel_masks[AUDIO_PORT_MAX_CHANNEL_MASKS]; 973 unsigned int num_formats; /* number of formats in following array */ 974 audio_format_t formats[AUDIO_PORT_MAX_FORMATS]; 975 unsigned int num_gains; /* number of gains in following array */ 976 struct audio_gain gains[AUDIO_PORT_MAX_GAINS]; 977 struct audio_port_config active_config; /* current audio port configuration */ 978 union { 979 struct audio_port_device_ext device; 980 struct audio_port_mix_ext mix; 981 struct audio_port_session_ext session; 982 } ext; 983}; 984 985/* An audio patch represents a connection between one or more source ports and 986 * one or more sink ports. Patches are connected and disconnected by audio policy manager or by 987 * applications via framework APIs. 988 * Each patch is identified by a handle at the interface used to create that patch. For instance, 989 * when a patch is created by the audio HAL, the HAL allocates and returns a handle. 990 * This handle is unique to a given audio HAL hardware module. 991 * But the same patch receives another system wide unique handle allocated by the framework. 992 * This unique handle is used for all transactions inside the framework. 993 */ 994typedef int audio_patch_handle_t; 995#define AUDIO_PATCH_HANDLE_NONE 0 996 997#define AUDIO_PATCH_PORTS_MAX 16 998 999struct audio_patch { 1000 audio_patch_handle_t id; /* patch unique ID */ 1001 unsigned int num_sources; /* number of sources in following array */ 1002 struct audio_port_config sources[AUDIO_PATCH_PORTS_MAX]; 1003 unsigned int num_sinks; /* number of sinks in following array */ 1004 struct audio_port_config sinks[AUDIO_PATCH_PORTS_MAX]; 1005}; 1006 1007 1008 1009/* a HW synchronization source returned by the audio HAL */ 1010typedef uint32_t audio_hw_sync_t; 1011 1012/* an invalid HW synchronization source indicating an error */ 1013#define AUDIO_HW_SYNC_INVALID 0 1014 1015static inline bool audio_is_output_device(audio_devices_t device) 1016{ 1017 if (((device & AUDIO_DEVICE_BIT_IN) == 0) && 1018 (popcount(device) == 1) && ((device & ~AUDIO_DEVICE_OUT_ALL) == 0)) 1019 return true; 1020 else 1021 return false; 1022} 1023 1024static inline bool audio_is_input_device(audio_devices_t device) 1025{ 1026 if ((device & AUDIO_DEVICE_BIT_IN) != 0) { 1027 device &= ~AUDIO_DEVICE_BIT_IN; 1028 if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_IN_ALL) == 0)) 1029 return true; 1030 } 1031 return false; 1032} 1033 1034static inline bool audio_is_output_devices(audio_devices_t device) 1035{ 1036 return (device & AUDIO_DEVICE_BIT_IN) == 0; 1037} 1038 1039static inline bool audio_is_a2dp_in_device(audio_devices_t device) 1040{ 1041 if ((device & AUDIO_DEVICE_BIT_IN) != 0) { 1042 device &= ~AUDIO_DEVICE_BIT_IN; 1043 if ((popcount(device) == 1) && (device & AUDIO_DEVICE_IN_BLUETOOTH_A2DP)) 1044 return true; 1045 } 1046 return false; 1047} 1048 1049static inline bool audio_is_a2dp_out_device(audio_devices_t device) 1050{ 1051 if ((popcount(device) == 1) && (device & AUDIO_DEVICE_OUT_ALL_A2DP)) 1052 return true; 1053 else 1054 return false; 1055} 1056 1057// Deprecated - use audio_is_a2dp_out_device() instead 1058static inline bool audio_is_a2dp_device(audio_devices_t device) 1059{ 1060 return audio_is_a2dp_out_device(device); 1061} 1062 1063static inline bool audio_is_bluetooth_sco_device(audio_devices_t device) 1064{ 1065 if ((device & AUDIO_DEVICE_BIT_IN) == 0) { 1066 if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_OUT_ALL_SCO) == 0)) 1067 return true; 1068 } else { 1069 device &= ~AUDIO_DEVICE_BIT_IN; 1070 if ((popcount(device) == 1) && ((device & ~AUDIO_DEVICE_IN_BLUETOOTH_SCO_HEADSET) == 0)) 1071 return true; 1072 } 1073 1074 return false; 1075} 1076 1077static inline bool audio_is_usb_out_device(audio_devices_t device) 1078{ 1079 return ((popcount(device) == 1) && (device & AUDIO_DEVICE_OUT_ALL_USB)); 1080} 1081 1082static inline bool audio_is_usb_in_device(audio_devices_t device) 1083{ 1084 if ((device & AUDIO_DEVICE_BIT_IN) != 0) { 1085 device &= ~AUDIO_DEVICE_BIT_IN; 1086 if (popcount(device) == 1 && (device & AUDIO_DEVICE_IN_ALL_USB) != 0) 1087 return true; 1088 } 1089 return false; 1090} 1091 1092/* OBSOLETE - use audio_is_usb_out_device() instead. */ 1093static inline bool audio_is_usb_device(audio_devices_t device) 1094{ 1095 return audio_is_usb_out_device(device); 1096} 1097 1098static inline bool audio_is_remote_submix_device(audio_devices_t device) 1099{ 1100 if ((device & AUDIO_DEVICE_OUT_REMOTE_SUBMIX) == AUDIO_DEVICE_OUT_REMOTE_SUBMIX 1101 || (device & AUDIO_DEVICE_IN_REMOTE_SUBMIX) == AUDIO_DEVICE_IN_REMOTE_SUBMIX) 1102 return true; 1103 else 1104 return false; 1105} 1106 1107/* Returns true if: 1108 * representation is valid, and 1109 * there is at least one channel bit set which _could_ correspond to an input channel, and 1110 * there are no channel bits set which could _not_ correspond to an input channel. 1111 * Otherwise returns false. 1112 */ 1113static inline bool audio_is_input_channel(audio_channel_mask_t channel) 1114{ 1115 uint32_t bits = audio_channel_mask_get_bits(channel); 1116 switch (audio_channel_mask_get_representation(channel)) { 1117 case AUDIO_CHANNEL_REPRESENTATION_POSITION: 1118 if (bits & ~AUDIO_CHANNEL_IN_ALL) { 1119 bits = 0; 1120 } 1121 // fall through 1122 case AUDIO_CHANNEL_REPRESENTATION_INDEX: 1123 return bits != 0; 1124 default: 1125 return false; 1126 } 1127} 1128 1129/* Returns true if: 1130 * representation is valid, and 1131 * there is at least one channel bit set which _could_ correspond to an output channel, and 1132 * there are no channel bits set which could _not_ correspond to an output channel. 1133 * Otherwise returns false. 1134 */ 1135static inline bool audio_is_output_channel(audio_channel_mask_t channel) 1136{ 1137 uint32_t bits = audio_channel_mask_get_bits(channel); 1138 switch (audio_channel_mask_get_representation(channel)) { 1139 case AUDIO_CHANNEL_REPRESENTATION_POSITION: 1140 if (bits & ~AUDIO_CHANNEL_OUT_ALL) { 1141 bits = 0; 1142 } 1143 // fall through 1144 case AUDIO_CHANNEL_REPRESENTATION_INDEX: 1145 return bits != 0; 1146 default: 1147 return false; 1148 } 1149} 1150 1151/* Returns the number of channels from an input channel mask, 1152 * used in the context of audio input or recording. 1153 * If a channel bit is set which could _not_ correspond to an input channel, 1154 * it is excluded from the count. 1155 * Returns zero if the representation is invalid. 1156 */ 1157static inline uint32_t audio_channel_count_from_in_mask(audio_channel_mask_t channel) 1158{ 1159 uint32_t bits = audio_channel_mask_get_bits(channel); 1160 switch (audio_channel_mask_get_representation(channel)) { 1161 case AUDIO_CHANNEL_REPRESENTATION_POSITION: 1162 // TODO: We can now merge with from_out_mask and remove anding 1163 bits &= AUDIO_CHANNEL_IN_ALL; 1164 // fall through 1165 case AUDIO_CHANNEL_REPRESENTATION_INDEX: 1166 return popcount(bits); 1167 default: 1168 return 0; 1169 } 1170} 1171 1172/* Returns the number of channels from an output channel mask, 1173 * used in the context of audio output or playback. 1174 * If a channel bit is set which could _not_ correspond to an output channel, 1175 * it is excluded from the count. 1176 * Returns zero if the representation is invalid. 1177 */ 1178static inline uint32_t audio_channel_count_from_out_mask(audio_channel_mask_t channel) 1179{ 1180 uint32_t bits = audio_channel_mask_get_bits(channel); 1181 switch (audio_channel_mask_get_representation(channel)) { 1182 case AUDIO_CHANNEL_REPRESENTATION_POSITION: 1183 // TODO: We can now merge with from_in_mask and remove anding 1184 bits &= AUDIO_CHANNEL_OUT_ALL; 1185 // fall through 1186 case AUDIO_CHANNEL_REPRESENTATION_INDEX: 1187 return popcount(bits); 1188 default: 1189 return 0; 1190 } 1191} 1192 1193/* Derive an output channel mask for position assignment from a channel count. 1194 * This is to be used when the content channel mask is unknown. The 1, 2, 4, 5, 6, 7 and 8 channel 1195 * cases are mapped to the standard game/home-theater layouts, but note that 4 is mapped to quad, 1196 * and not stereo + FC + mono surround. A channel count of 3 is arbitrarily mapped to stereo + FC 1197 * for continuity with stereo. 1198 * Returns the matching channel mask, 1199 * or AUDIO_CHANNEL_NONE if the channel count is zero, 1200 * or AUDIO_CHANNEL_INVALID if the channel count exceeds that of the 1201 * configurations for which a default output channel mask is defined. 1202 */ 1203static inline audio_channel_mask_t audio_channel_out_mask_from_count(uint32_t channel_count) 1204{ 1205 uint32_t bits; 1206 switch (channel_count) { 1207 case 0: 1208 return AUDIO_CHANNEL_NONE; 1209 case 1: 1210 bits = AUDIO_CHANNEL_OUT_MONO; 1211 break; 1212 case 2: 1213 bits = AUDIO_CHANNEL_OUT_STEREO; 1214 break; 1215 case 3: 1216 bits = AUDIO_CHANNEL_OUT_STEREO | AUDIO_CHANNEL_OUT_FRONT_CENTER; 1217 break; 1218 case 4: // 4.0 1219 bits = AUDIO_CHANNEL_OUT_QUAD; 1220 break; 1221 case 5: // 5.0 1222 bits = AUDIO_CHANNEL_OUT_QUAD | AUDIO_CHANNEL_OUT_FRONT_CENTER; 1223 break; 1224 case 6: // 5.1 1225 bits = AUDIO_CHANNEL_OUT_5POINT1; 1226 break; 1227 case 7: // 6.1 1228 bits = AUDIO_CHANNEL_OUT_5POINT1 | AUDIO_CHANNEL_OUT_BACK_CENTER; 1229 break; 1230 case 8: 1231 bits = AUDIO_CHANNEL_OUT_7POINT1; 1232 break; 1233 default: 1234 return AUDIO_CHANNEL_INVALID; 1235 } 1236 return audio_channel_mask_from_representation_and_bits( 1237 AUDIO_CHANNEL_REPRESENTATION_POSITION, bits); 1238} 1239 1240/* Derive an input channel mask for position assignment from a channel count. 1241 * Currently handles only mono and stereo. 1242 * Returns the matching channel mask, 1243 * or AUDIO_CHANNEL_NONE if the channel count is zero, 1244 * or AUDIO_CHANNEL_INVALID if the channel count exceeds that of the 1245 * configurations for which a default input channel mask is defined. 1246 */ 1247static inline audio_channel_mask_t audio_channel_in_mask_from_count(uint32_t channel_count) 1248{ 1249 uint32_t bits; 1250 switch (channel_count) { 1251 case 0: 1252 return AUDIO_CHANNEL_NONE; 1253 case 1: 1254 bits = AUDIO_CHANNEL_IN_MONO; 1255 break; 1256 case 2: 1257 bits = AUDIO_CHANNEL_IN_STEREO; 1258 break; 1259 default: 1260 return AUDIO_CHANNEL_INVALID; 1261 } 1262 return audio_channel_mask_from_representation_and_bits( 1263 AUDIO_CHANNEL_REPRESENTATION_POSITION, bits); 1264} 1265 1266/* Derive a channel mask for index assignment from a channel count. 1267 * Returns the matching channel mask, 1268 * or AUDIO_CHANNEL_NONE if the channel count is zero, 1269 * or AUDIO_CHANNEL_INVALID if the channel count exceeds AUDIO_CHANNEL_COUNT_MAX. 1270 */ 1271static inline audio_channel_mask_t audio_channel_mask_for_index_assignment_from_count( 1272 uint32_t channel_count) 1273{ 1274 if (channel_count == 0) { 1275 return AUDIO_CHANNEL_NONE; 1276 } 1277 if (channel_count > AUDIO_CHANNEL_COUNT_MAX) { 1278 return AUDIO_CHANNEL_INVALID; 1279 } 1280 uint32_t bits = (1 << channel_count) - 1; 1281 return audio_channel_mask_from_representation_and_bits( 1282 AUDIO_CHANNEL_REPRESENTATION_INDEX, bits); 1283} 1284 1285static inline bool audio_is_valid_format(audio_format_t format) 1286{ 1287 switch (format & AUDIO_FORMAT_MAIN_MASK) { 1288 case AUDIO_FORMAT_PCM: 1289 switch (format) { 1290 case AUDIO_FORMAT_PCM_16_BIT: 1291 case AUDIO_FORMAT_PCM_8_BIT: 1292 case AUDIO_FORMAT_PCM_32_BIT: 1293 case AUDIO_FORMAT_PCM_8_24_BIT: 1294 case AUDIO_FORMAT_PCM_FLOAT: 1295 case AUDIO_FORMAT_PCM_24_BIT_PACKED: 1296 return true; 1297 default: 1298 return false; 1299 } 1300 /* not reached */ 1301 case AUDIO_FORMAT_MP3: 1302 case AUDIO_FORMAT_AMR_NB: 1303 case AUDIO_FORMAT_AMR_WB: 1304 case AUDIO_FORMAT_AAC: 1305 case AUDIO_FORMAT_HE_AAC_V1: 1306 case AUDIO_FORMAT_HE_AAC_V2: 1307 case AUDIO_FORMAT_VORBIS: 1308 case AUDIO_FORMAT_OPUS: 1309 case AUDIO_FORMAT_AC3: 1310 case AUDIO_FORMAT_E_AC3: 1311 return true; 1312 default: 1313 return false; 1314 } 1315} 1316 1317static inline bool audio_is_linear_pcm(audio_format_t format) 1318{ 1319 return ((format & AUDIO_FORMAT_MAIN_MASK) == AUDIO_FORMAT_PCM); 1320} 1321 1322static inline size_t audio_bytes_per_sample(audio_format_t format) 1323{ 1324 size_t size = 0; 1325 1326 switch (format) { 1327 case AUDIO_FORMAT_PCM_32_BIT: 1328 case AUDIO_FORMAT_PCM_8_24_BIT: 1329 size = sizeof(int32_t); 1330 break; 1331 case AUDIO_FORMAT_PCM_24_BIT_PACKED: 1332 size = sizeof(uint8_t) * 3; 1333 break; 1334 case AUDIO_FORMAT_PCM_16_BIT: 1335 size = sizeof(int16_t); 1336 break; 1337 case AUDIO_FORMAT_PCM_8_BIT: 1338 size = sizeof(uint8_t); 1339 break; 1340 case AUDIO_FORMAT_PCM_FLOAT: 1341 size = sizeof(float); 1342 break; 1343 default: 1344 break; 1345 } 1346 return size; 1347} 1348 1349/* converts device address to string sent to audio HAL via set_parameters */ 1350static char *audio_device_address_to_parameter(audio_devices_t device, const char *address) 1351{ 1352 const size_t kSize = AUDIO_DEVICE_MAX_ADDRESS_LEN + sizeof("a2dp_sink_address="); 1353 char param[kSize]; 1354 1355 if (device & AUDIO_DEVICE_OUT_ALL_A2DP) 1356 snprintf(param, kSize, "%s=%s", "a2dp_sink_address", address); 1357 else if (device & AUDIO_DEVICE_OUT_REMOTE_SUBMIX) 1358 snprintf(param, kSize, "%s=%s", "mix", address); 1359 else 1360 snprintf(param, kSize, "%s", address); 1361 1362 return strdup(param); 1363} 1364 1365 1366__END_DECLS 1367 1368#endif // ANDROID_AUDIO_CORE_H 1369