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