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