blob: eeba10c7d655b524e1143a33148a29ea6a9022d2 [file] [log] [blame]
Phil Burk5ed503c2017-02-01 09:38:15 -08001/*
2 * Copyright (C) 2016 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/**
Phil Burka45be8b2017-04-05 14:45:48 -070018 * @addtogroup Audio
19 * @{
20 */
21
22/**
23 * @file AAudio.h
24 */
25
26/**
27 * This is the 'C' API for AAudio.
Phil Burk5ed503c2017-02-01 09:38:15 -080028 */
29#ifndef AAUDIO_AAUDIO_H
30#define AAUDIO_AAUDIO_H
31
Elliott Hughes9c1fca22020-06-12 09:53:12 -070032#include <stdbool.h>
33#include <stdint.h>
Phil Burk3316d5e2017-02-15 11:23:01 -080034#include <time.h>
Phil Burk5ed503c2017-02-01 09:38:15 -080035
36#ifdef __cplusplus
37extern "C" {
38#endif
39
Phil Burka4eb0d82017-04-12 15:44:06 -070040/**
41 * This is used to represent a value that has not been specified.
Kevin Rocardfb7e8462019-03-20 13:26:49 -070042 * For example, an application could use {@link #AAUDIO_UNSPECIFIED} to indicate
Phil Burka4eb0d82017-04-12 15:44:06 -070043 * that is did not not care what the specific value of a parameter was
44 * and would accept whatever it was given.
45 */
46#define AAUDIO_UNSPECIFIED 0
Phil Burka4eb0d82017-04-12 15:44:06 -070047
48enum {
Phil Burk8149eed2018-05-24 14:09:46 -070049 /**
50 * Audio data will travel out of the device, for example through a speaker.
51 */
Phil Burka4eb0d82017-04-12 15:44:06 -070052 AAUDIO_DIRECTION_OUTPUT,
Phil Burk8149eed2018-05-24 14:09:46 -070053
54
55 /**
56 * Audio data will travel into the device, for example from a microphone.
57 */
Phil Burka4eb0d82017-04-12 15:44:06 -070058 AAUDIO_DIRECTION_INPUT
59};
60typedef int32_t aaudio_direction_t;
61
62enum {
63 AAUDIO_FORMAT_INVALID = -1,
64 AAUDIO_FORMAT_UNSPECIFIED = 0,
Phil Burk8149eed2018-05-24 14:09:46 -070065
66 /**
67 * This format uses the int16_t data type.
Phil Burk04e805b2018-03-27 09:13:53 -070068 * The maximum range of the data is -32768 (0x8000) to 32767 (0x7FFF).
Phil Burk8149eed2018-05-24 14:09:46 -070069 */
Phil Burka4eb0d82017-04-12 15:44:06 -070070 AAUDIO_FORMAT_PCM_I16,
Phil Burk8149eed2018-05-24 14:09:46 -070071
72 /**
73 * This format uses the float data type.
74 * The nominal range of the data is [-1.0f, 1.0f).
75 * Values outside that range may be clipped.
76 *
77 * See also 'floatData' at
78 * https://developer.android.com/reference/android/media/AudioTrack#write(float[],%20int,%20int,%20int)
79 */
Phil Burk04e805b2018-03-27 09:13:53 -070080 AAUDIO_FORMAT_PCM_FLOAT,
81
82 /**
83 * This format uses 24-bit samples packed into 3 bytes.
84 * The bytes are in the native endian order.
85 * The maximum range of the data is -8388608 (0x800000)
86 * to 8388607 (0x7FFFFF).
87 *
88 * Note that the lower precision bits may be ignored by the device.
89 *
90 * Available since API level 31.
91 */
92 AAUDIO_FORMAT_PCM_I24_PACKED,
93
94 /**
95 * This format uses 32-bit samples stored in an int32_t data type.
96 * The maximum range of the data is -2147483648 (0x80000000)
97 * to 2147483647 (0x7FFFFFFF).
98 *
99 * Note that the lower precision bits may be ignored by the device.
100 *
101 * Available since API level 31.
102 */
103 AAUDIO_FORMAT_PCM_I32
104
Phil Burka4eb0d82017-04-12 15:44:06 -0700105};
106typedef int32_t aaudio_format_t;
107
Phil Burk8149eed2018-05-24 14:09:46 -0700108/**
109 * These result codes are returned from AAudio functions to indicate success or failure.
110 * Note that error return codes may change in the future so applications should generally
111 * not rely on specific return codes.
112 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700113enum {
Phil Burk8149eed2018-05-24 14:09:46 -0700114 /**
115 * The call was successful.
116 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700117 AAUDIO_OK,
118 AAUDIO_ERROR_BASE = -900, // TODO review
Phil Burk8149eed2018-05-24 14:09:46 -0700119
120 /**
121 * The audio device was disconnected. This could occur, for example, when headphones
122 * are plugged in or unplugged. The stream cannot be used after the device is disconnected.
123 * Applications should stop and close the stream.
124 * If this error is received in an error callback then another thread should be
125 * used to stop and close the stream.
126 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700127 AAUDIO_ERROR_DISCONNECTED,
Phil Burk8149eed2018-05-24 14:09:46 -0700128
129 /**
130 * An invalid parameter was passed to AAudio.
131 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700132 AAUDIO_ERROR_ILLEGAL_ARGUMENT,
Phil Burk17fff382017-05-16 14:06:45 -0700133 // reserved
134 AAUDIO_ERROR_INTERNAL = AAUDIO_ERROR_ILLEGAL_ARGUMENT + 2,
Phil Burk8149eed2018-05-24 14:09:46 -0700135
136 /**
137 * The requested operation is not appropriate for the current state of AAudio.
138 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700139 AAUDIO_ERROR_INVALID_STATE,
Phil Burk17fff382017-05-16 14:06:45 -0700140 // reserved
141 // reserved
Phil Burk8149eed2018-05-24 14:09:46 -0700142 /* The server rejected the handle used to identify the stream.
143 */
Phil Burk17fff382017-05-16 14:06:45 -0700144 AAUDIO_ERROR_INVALID_HANDLE = AAUDIO_ERROR_INVALID_STATE + 3,
145 // reserved
Phil Burk8149eed2018-05-24 14:09:46 -0700146
147 /**
148 * The function is not implemented for this stream.
149 */
Phil Burk17fff382017-05-16 14:06:45 -0700150 AAUDIO_ERROR_UNIMPLEMENTED = AAUDIO_ERROR_INVALID_HANDLE + 2,
Phil Burk8149eed2018-05-24 14:09:46 -0700151
152 /**
153 * A resource or information is unavailable.
154 * This could occur when an application tries to open too many streams,
155 * or a timestamp is not available.
156 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700157 AAUDIO_ERROR_UNAVAILABLE,
158 AAUDIO_ERROR_NO_FREE_HANDLES,
Phil Burk8149eed2018-05-24 14:09:46 -0700159
160 /**
161 * Memory could not be allocated.
162 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700163 AAUDIO_ERROR_NO_MEMORY,
Phil Burk8149eed2018-05-24 14:09:46 -0700164
165 /**
166 * A NULL pointer was passed to AAudio.
167 * Or a NULL pointer was detected internally.
168 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700169 AAUDIO_ERROR_NULL,
Phil Burk8149eed2018-05-24 14:09:46 -0700170
171 /**
172 * An operation took longer than expected.
173 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700174 AAUDIO_ERROR_TIMEOUT,
175 AAUDIO_ERROR_WOULD_BLOCK,
Phil Burk8149eed2018-05-24 14:09:46 -0700176
177 /**
178 * The requested data format is not supported.
179 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700180 AAUDIO_ERROR_INVALID_FORMAT,
Phil Burk8149eed2018-05-24 14:09:46 -0700181
182 /**
183 * A requested was out of range.
184 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700185 AAUDIO_ERROR_OUT_OF_RANGE,
Phil Burk8149eed2018-05-24 14:09:46 -0700186
187 /**
188 * The audio service was not available.
189 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700190 AAUDIO_ERROR_NO_SERVICE,
Phil Burk8149eed2018-05-24 14:09:46 -0700191
192 /**
193 * The requested sample rate was not supported.
194 */
Phil Burka4eb0d82017-04-12 15:44:06 -0700195 AAUDIO_ERROR_INVALID_RATE
196};
197typedef int32_t aaudio_result_t;
198
199enum
200{
201 AAUDIO_STREAM_STATE_UNINITIALIZED = 0,
202 AAUDIO_STREAM_STATE_UNKNOWN,
203 AAUDIO_STREAM_STATE_OPEN,
204 AAUDIO_STREAM_STATE_STARTING,
205 AAUDIO_STREAM_STATE_STARTED,
206 AAUDIO_STREAM_STATE_PAUSING,
207 AAUDIO_STREAM_STATE_PAUSED,
208 AAUDIO_STREAM_STATE_FLUSHING,
209 AAUDIO_STREAM_STATE_FLUSHED,
210 AAUDIO_STREAM_STATE_STOPPING,
211 AAUDIO_STREAM_STATE_STOPPED,
212 AAUDIO_STREAM_STATE_CLOSING,
213 AAUDIO_STREAM_STATE_CLOSED,
214 AAUDIO_STREAM_STATE_DISCONNECTED
215};
216typedef int32_t aaudio_stream_state_t;
217
218
219enum {
220 /**
221 * This will be the only stream using a particular source or sink.
222 * This mode will provide the lowest possible latency.
223 * You should close EXCLUSIVE streams immediately when you are not using them.
224 */
225 AAUDIO_SHARING_MODE_EXCLUSIVE,
226 /**
227 * Multiple applications will be mixed by the AAudio Server.
228 * This will have higher latency than the EXCLUSIVE mode.
229 */
230 AAUDIO_SHARING_MODE_SHARED
231};
232typedef int32_t aaudio_sharing_mode_t;
233
Phil Burke2fbb592017-05-01 15:05:52 -0700234
235enum {
236 /**
237 * No particular performance needs. Default.
238 */
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800239 AAUDIO_PERFORMANCE_MODE_NONE = 10,
Phil Burke2fbb592017-05-01 15:05:52 -0700240
241 /**
Phil Burk8149eed2018-05-24 14:09:46 -0700242 * Extending battery life is more important than low latency.
Phil Burked0a3fe2017-12-05 14:27:43 -0800243 *
244 * This mode is not supported in input streams.
Phil Burk8149eed2018-05-24 14:09:46 -0700245 * For input, mode NONE will be used if this is requested.
Phil Burke2fbb592017-05-01 15:05:52 -0700246 */
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800247 AAUDIO_PERFORMANCE_MODE_POWER_SAVING,
Phil Burke2fbb592017-05-01 15:05:52 -0700248
249 /**
Phil Burk8149eed2018-05-24 14:09:46 -0700250 * Reducing latency is more important than battery life.
Phil Burke2fbb592017-05-01 15:05:52 -0700251 */
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800252 AAUDIO_PERFORMANCE_MODE_LOW_LATENCY
Phil Burke2fbb592017-05-01 15:05:52 -0700253};
254typedef int32_t aaudio_performance_mode_t;
255
Hayden Gomes3e8bbb92020-01-10 13:37:05 -0800256#define AAUDIO_SYSTEM_USAGE_OFFSET 1000
257
Phil Burk361b1422017-12-20 14:24:16 -0800258/**
259 * The USAGE attribute expresses "why" you are playing a sound, what is this sound used for.
260 * This information is used by certain platforms or routing policies
261 * to make more refined volume or routing decisions.
262 *
Kevin Rocard68646ba2019-03-20 13:26:49 -0700263 * Note that these match the equivalent values in {@link android.media.AudioAttributes}
264 * in the Android Java API.
Phil Burk42452c02018-04-10 12:43:33 -0700265 *
266 * Added in API level 28.
Phil Burk361b1422017-12-20 14:24:16 -0800267 */
268enum {
269 /**
270 * Use this for streaming media, music performance, video, podcasts, etcetera.
271 */
272 AAUDIO_USAGE_MEDIA = 1,
273
274 /**
275 * Use this for voice over IP, telephony, etcetera.
276 */
277 AAUDIO_USAGE_VOICE_COMMUNICATION = 2,
278
279 /**
280 * Use this for sounds associated with telephony such as busy tones, DTMF, etcetera.
281 */
282 AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING = 3,
283
284 /**
285 * Use this to demand the users attention.
286 */
287 AAUDIO_USAGE_ALARM = 4,
288
289 /**
290 * Use this for notifying the user when a message has arrived or some
291 * other background event has occured.
292 */
293 AAUDIO_USAGE_NOTIFICATION = 5,
294
295 /**
296 * Use this when the phone rings.
297 */
298 AAUDIO_USAGE_NOTIFICATION_RINGTONE = 6,
299
300 /**
301 * Use this to attract the users attention when, for example, the battery is low.
302 */
303 AAUDIO_USAGE_NOTIFICATION_EVENT = 10,
304
305 /**
306 * Use this for screen readers, etcetera.
307 */
308 AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY = 11,
309
310 /**
311 * Use this for driving or navigation directions.
312 */
313 AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE = 12,
314
315 /**
316 * Use this for user interface sounds, beeps, etcetera.
317 */
318 AAUDIO_USAGE_ASSISTANCE_SONIFICATION = 13,
319
320 /**
321 * Use this for game audio and sound effects.
322 */
323 AAUDIO_USAGE_GAME = 14,
324
325 /**
326 * Use this for audio responses to user queries, audio instructions or help utterances.
327 */
Hayden Gomes3e8bbb92020-01-10 13:37:05 -0800328 AAUDIO_USAGE_ASSISTANT = 16,
329
330 /**
331 * Use this in case of playing sounds in an emergency.
332 * Privileged MODIFY_AUDIO_ROUTING permission required.
333 */
334 AAUDIO_SYSTEM_USAGE_EMERGENCY = AAUDIO_SYSTEM_USAGE_OFFSET,
335
336 /**
337 * Use this for safety sounds and alerts, for example backup camera obstacle detection.
338 * Privileged MODIFY_AUDIO_ROUTING permission required.
339 */
340 AAUDIO_SYSTEM_USAGE_SAFETY = AAUDIO_SYSTEM_USAGE_OFFSET + 1,
341
342 /**
343 * Use this for vehicle status alerts and information, for example the check engine light.
344 * Privileged MODIFY_AUDIO_ROUTING permission required.
345 */
346 AAUDIO_SYSTEM_USAGE_VEHICLE_STATUS = AAUDIO_SYSTEM_USAGE_OFFSET + 2,
347
348 /**
349 * Use this for traffic announcements, etc.
350 * Privileged MODIFY_AUDIO_ROUTING permission required.
351 */
352 AAUDIO_SYSTEM_USAGE_ANNOUNCEMENT = AAUDIO_SYSTEM_USAGE_OFFSET + 3,
Phil Burk361b1422017-12-20 14:24:16 -0800353};
354typedef int32_t aaudio_usage_t;
355
356/**
357 * The CONTENT_TYPE attribute describes "what" you are playing.
358 * It expresses the general category of the content. This information is optional.
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700359 * But in case it is known (for instance AAUDIO_CONTENT_TYPE_MOVIE for a
360 * movie streaming service or AAUDIO_CONTENT_TYPE_SPEECH for
Phil Burk361b1422017-12-20 14:24:16 -0800361 * an audio book application) this information might be used by the audio framework to
362 * enforce audio focus.
363 *
Kevin Rocard68646ba2019-03-20 13:26:49 -0700364 * Note that these match the equivalent values in {@link android.media.AudioAttributes}
365 * in the Android Java API.
Phil Burk42452c02018-04-10 12:43:33 -0700366 *
367 * Added in API level 28.
Phil Burk361b1422017-12-20 14:24:16 -0800368 */
369enum {
370
371 /**
372 * Use this for spoken voice, audio books, etcetera.
373 */
374 AAUDIO_CONTENT_TYPE_SPEECH = 1,
375
376 /**
377 * Use this for pre-recorded or live music.
378 */
379 AAUDIO_CONTENT_TYPE_MUSIC = 2,
380
381 /**
382 * Use this for a movie or video soundtrack.
383 */
384 AAUDIO_CONTENT_TYPE_MOVIE = 3,
385
386 /**
387 * Use this for sound is designed to accompany a user action,
388 * such as a click or beep sound made when the user presses a button.
389 */
390 AAUDIO_CONTENT_TYPE_SONIFICATION = 4
391};
392typedef int32_t aaudio_content_type_t;
393
394/**
395 * Defines the audio source.
396 * An audio source defines both a default physical source of audio signal, and a recording
397 * configuration.
398 *
399 * Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API.
Phil Burk42452c02018-04-10 12:43:33 -0700400 *
401 * Added in API level 28.
Phil Burk361b1422017-12-20 14:24:16 -0800402 */
403enum {
404 /**
405 * Use this preset when other presets do not apply.
406 */
407 AAUDIO_INPUT_PRESET_GENERIC = 1,
408
409 /**
410 * Use this preset when recording video.
411 */
412 AAUDIO_INPUT_PRESET_CAMCORDER = 5,
413
414 /**
415 * Use this preset when doing speech recognition.
416 */
417 AAUDIO_INPUT_PRESET_VOICE_RECOGNITION = 6,
418
419 /**
420 * Use this preset when doing telephony or voice messaging.
421 */
422 AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION = 7,
423
424 /**
425 * Use this preset to obtain an input with no effects.
426 * Note that this input will not have automatic gain control
427 * so the recorded volume may be very low.
428 */
429 AAUDIO_INPUT_PRESET_UNPROCESSED = 9,
Eric Laurentae4b6ec2019-01-15 18:34:38 -0800430
431 /**
432 * Use this preset for capturing audio meant to be processed in real time
433 * and played back for live performance (e.g karaoke).
434 * The capture path will minimize latency and coupling with playback path.
Eric Laurentb51e3ab2020-04-28 18:29:25 -0700435 * Available since API level 29.
Eric Laurentae4b6ec2019-01-15 18:34:38 -0800436 */
437 AAUDIO_INPUT_PRESET_VOICE_PERFORMANCE = 10,
Phil Burk361b1422017-12-20 14:24:16 -0800438};
439typedef int32_t aaudio_input_preset_t;
440
Phil Burk8149eed2018-05-24 14:09:46 -0700441/**
Kevin Rocard68646ba2019-03-20 13:26:49 -0700442 * Specifying if audio may or may not be captured by other apps or the system.
443 *
444 * Note that these match the equivalent values in {@link android.media.AudioAttributes}
445 * in the Android Java API.
446 *
447 * Added in API level 29.
448 */
449enum {
450 /**
451 * Indicates that the audio may be captured by any app.
452 *
453 * For privacy, the following usages can not be recorded: AAUDIO_VOICE_COMMUNICATION*,
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700454 * AAUDIO_USAGE_NOTIFICATION*, AAUDIO_USAGE_ASSISTANCE* and {@link #AAUDIO_USAGE_ASSISTANT}.
Kevin Rocard68646ba2019-03-20 13:26:49 -0700455 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700456 * On {@link android.os.Build.VERSION_CODES#Q}, this means only {@link #AAUDIO_USAGE_MEDIA}
457 * and {@link #AAUDIO_USAGE_GAME} may be captured.
Kevin Rocard68646ba2019-03-20 13:26:49 -0700458 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700459 * See {@link android.media.AudioAttributes#ALLOW_CAPTURE_BY_ALL}.
Kevin Rocard68646ba2019-03-20 13:26:49 -0700460 */
461 AAUDIO_ALLOW_CAPTURE_BY_ALL = 1,
462 /**
463 * Indicates that the audio may only be captured by system apps.
464 *
465 * System apps can capture for many purposes like accessibility, user guidance...
466 * but have strong restriction. See
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700467 * {@link android.media.AudioAttributes#ALLOW_CAPTURE_BY_SYSTEM} for what the system apps
Kevin Rocard68646ba2019-03-20 13:26:49 -0700468 * can do with the capture audio.
469 */
470 AAUDIO_ALLOW_CAPTURE_BY_SYSTEM = 2,
471 /**
472 * Indicates that the audio may not be recorded by any app, even if it is a system app.
473 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700474 * It is encouraged to use {@link #AAUDIO_ALLOW_CAPTURE_BY_SYSTEM} instead of this value as system apps
Kevin Rocard68646ba2019-03-20 13:26:49 -0700475 * provide significant and useful features for the user (eg. accessibility).
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700476 * See {@link android.media.AudioAttributes#ALLOW_CAPTURE_BY_NONE}.
Kevin Rocard68646ba2019-03-20 13:26:49 -0700477 */
478 AAUDIO_ALLOW_CAPTURE_BY_NONE = 3,
479};
480
481typedef int32_t aaudio_allowed_capture_policy_t;
482
483/**
Phil Burk8149eed2018-05-24 14:09:46 -0700484 * These may be used with AAudioStreamBuilder_setSessionId().
485 *
486 * Added in API level 28.
487 */
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800488enum {
489 /**
490 * Do not allocate a session ID.
491 * Effects cannot be used with this stream.
492 * Default.
Phil Burk42452c02018-04-10 12:43:33 -0700493 *
494 * Added in API level 28.
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800495 */
496 AAUDIO_SESSION_ID_NONE = -1,
497
498 /**
499 * Allocate a session ID that can be used to attach and control
500 * effects using the Java AudioEffects API.
Phil Burk8149eed2018-05-24 14:09:46 -0700501 * Note that using this may result in higher latency.
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800502 *
503 * Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE.
Phil Burk42452c02018-04-10 12:43:33 -0700504 *
505 * Added in API level 28.
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800506 */
507 AAUDIO_SESSION_ID_ALLOCATE = 0,
508};
509typedef int32_t aaudio_session_id_t;
510
Phil Burke2155ef2017-02-24 13:50:29 -0800511typedef struct AAudioStreamStruct AAudioStream;
512typedef struct AAudioStreamBuilderStruct AAudioStreamBuilder;
Phil Burk5ed503c2017-02-01 09:38:15 -0800513
Phil Burk5ed503c2017-02-01 09:38:15 -0800514#ifndef AAUDIO_API
Phil Burk3316d5e2017-02-15 11:23:01 -0800515#define AAUDIO_API /* export this symbol */
Phil Burk5ed503c2017-02-01 09:38:15 -0800516#endif
517
518// ============================================================
519// Audio System
520// ============================================================
521
522/**
Phil Burk5ed503c2017-02-01 09:38:15 -0800523 * The text is the ASCII symbol corresponding to the returnCode,
524 * or an English message saying the returnCode is unrecognized.
525 * This is intended for developers to use when debugging.
526 * It is not for display to users.
527 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700528 * Available since API level 26.
529 *
Phil Burk5ed503c2017-02-01 09:38:15 -0800530 * @return pointer to a text representation of an AAudio result code.
531 */
Elliott Hughes85a41532018-06-18 13:17:24 -0700532AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -0800533
534/**
535 * The text is the ASCII symbol corresponding to the stream state,
536 * or an English message saying the state is unrecognized.
537 * This is intended for developers to use when debugging.
538 * It is not for display to users.
539 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700540 * Available since API level 26.
541 *
Phil Burk5ed503c2017-02-01 09:38:15 -0800542 * @return pointer to a text representation of an AAudio state.
543 */
Elliott Hughes85a41532018-06-18 13:17:24 -0700544AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state)
545 __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -0800546
547// ============================================================
548// StreamBuilder
549// ============================================================
550
551/**
552 * Create a StreamBuilder that can be used to open a Stream.
553 *
554 * The deviceId is initially unspecified, meaning that the current default device will be used.
555 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700556 * The default direction is {@link #AAUDIO_DIRECTION_OUTPUT}.
557 * The default sharing mode is {@link #AAUDIO_SHARING_MODE_SHARED}.
Phil Burk5ed503c2017-02-01 09:38:15 -0800558 * The data format, samplesPerFrames and sampleRate are unspecified and will be
559 * chosen by the device when it is opened.
560 *
561 * AAudioStreamBuilder_delete() must be called when you are done using the builder.
Elliott Hughes64a3b062019-10-29 10:09:30 -0700562 *
563 * Available since API level 26.
Phil Burk5ed503c2017-02-01 09:38:15 -0800564 */
Elliott Hughes85a41532018-06-18 13:17:24 -0700565AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder)
566 __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -0800567
568/**
569 * Request an audio device identified device using an ID.
Phil Burk5ed503c2017-02-01 09:38:15 -0800570 * On Android, for example, the ID could be obtained from the Java AudioManager.
571 *
Kevin Rocard6309d882019-03-20 13:26:49 -0700572 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED},
Phil Burke057ca92017-03-28 11:31:34 -0700573 * in which case the primary device will be used.
Phil Burk5ed503c2017-02-01 09:38:15 -0800574 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700575 * Available since API level 26.
576 *
Phil Burk3316d5e2017-02-15 11:23:01 -0800577 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocard6309d882019-03-20 13:26:49 -0700578 * @param deviceId device identifier or {@link #AAUDIO_UNSPECIFIED}
Phil Burk5ed503c2017-02-01 09:38:15 -0800579 */
Phil Burke2155ef2017-02-24 13:50:29 -0800580AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700581 int32_t deviceId) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -0800582
583/**
Phil Burke057ca92017-03-28 11:31:34 -0700584 * Request a sample rate in Hertz.
585 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700586 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}.
Phil Burk8f624892017-05-11 11:44:20 -0700587 * An optimal value will then be chosen when the stream is opened.
588 * After opening a stream with an unspecified value, the application must
589 * query for the actual value, which may vary by device.
590 *
591 * If an exact value is specified then an opened stream will use that value.
592 * If a stream cannot be opened with the specified value then the open will fail.
Phil Burke057ca92017-03-28 11:31:34 -0700593 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700594 * Available since API level 26.
595 *
Phil Burke057ca92017-03-28 11:31:34 -0700596 * @param builder reference provided by AAudio_createStreamBuilder()
597 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz.
Phil Burk5ed503c2017-02-01 09:38:15 -0800598 */
Phil Burke2155ef2017-02-24 13:50:29 -0800599AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700600 int32_t sampleRate) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -0800601
602/**
Phil Burk20523ed2017-04-24 17:04:01 -0700603 * Request a number of channels for the stream.
Phil Burke057ca92017-03-28 11:31:34 -0700604 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700605 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}.
Phil Burk8f624892017-05-11 11:44:20 -0700606 * An optimal value will then be chosen when the stream is opened.
607 * After opening a stream with an unspecified value, the application must
608 * query for the actual value, which may vary by device.
Phil Burk5ed503c2017-02-01 09:38:15 -0800609 *
Phil Burk8f624892017-05-11 11:44:20 -0700610 * If an exact value is specified then an opened stream will use that value.
611 * If a stream cannot be opened with the specified value then the open will fail.
Phil Burke057ca92017-03-28 11:31:34 -0700612 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700613 * Available since API level 26.
614 *
Phil Burke057ca92017-03-28 11:31:34 -0700615 * @param builder reference provided by AAudio_createStreamBuilder()
Phil Burk20523ed2017-04-24 17:04:01 -0700616 * @param channelCount Number of channels desired.
Phil Burk5ed503c2017-02-01 09:38:15 -0800617 */
Phil Burk20523ed2017-04-24 17:04:01 -0700618AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700619 int32_t channelCount) __INTRODUCED_IN(26);
Phil Burk20523ed2017-04-24 17:04:01 -0700620
621/**
Phil Burke74240d2017-08-03 15:25:43 -0700622 * Identical to AAudioStreamBuilder_setChannelCount().
623 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700624 * Available since API level 26.
625 *
Phil Burke74240d2017-08-03 15:25:43 -0700626 * @param builder reference provided by AAudio_createStreamBuilder()
627 * @param samplesPerFrame Number of samples in a frame.
628 */
629AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700630 int32_t samplesPerFrame) __INTRODUCED_IN(26);
Phil Burke74240d2017-08-03 15:25:43 -0700631
632/**
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700633 * Request a sample data format, for example {@link #AAUDIO_FORMAT_PCM_I16}.
Phil Burke057ca92017-03-28 11:31:34 -0700634 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700635 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}.
Phil Burk8f624892017-05-11 11:44:20 -0700636 * An optimal value will then be chosen when the stream is opened.
637 * After opening a stream with an unspecified value, the application must
638 * query for the actual value, which may vary by device.
Phil Burke057ca92017-03-28 11:31:34 -0700639 *
Phil Burk8f624892017-05-11 11:44:20 -0700640 * If an exact value is specified then an opened stream will use that value.
641 * If a stream cannot be opened with the specified value then the open will fail.
Phil Burke057ca92017-03-28 11:31:34 -0700642 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700643 * Available since API level 26.
644 *
Phil Burke057ca92017-03-28 11:31:34 -0700645 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700646 * @param format common formats are {@link #AAUDIO_FORMAT_PCM_FLOAT} and
647 * {@link #AAUDIO_FORMAT_PCM_I16}.
Phil Burk5ed503c2017-02-01 09:38:15 -0800648 */
Phil Burke2155ef2017-02-24 13:50:29 -0800649AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700650 aaudio_format_t format) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -0800651
652/**
Phil Burk5ed503c2017-02-01 09:38:15 -0800653 * Request a mode for sharing the device.
Phil Burke057ca92017-03-28 11:31:34 -0700654 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700655 * The default, if you do not call this function, is {@link #AAUDIO_SHARING_MODE_SHARED}.
Phil Burke057ca92017-03-28 11:31:34 -0700656 *
Phil Burk5ed503c2017-02-01 09:38:15 -0800657 * The requested sharing mode may not be available.
Phil Burke057ca92017-03-28 11:31:34 -0700658 * The application can query for the actual mode after the stream is opened.
Phil Burk5ed503c2017-02-01 09:38:15 -0800659 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700660 * Available since API level 26.
661 *
Phil Burk3316d5e2017-02-15 11:23:01 -0800662 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700663 * @param sharingMode {@link #AAUDIO_SHARING_MODE_SHARED} or {@link #AAUDIO_SHARING_MODE_EXCLUSIVE}
Phil Burk5ed503c2017-02-01 09:38:15 -0800664 */
Phil Burke2155ef2017-02-24 13:50:29 -0800665AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700666 aaudio_sharing_mode_t sharingMode) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -0800667
668/**
Phil Burke057ca92017-03-28 11:31:34 -0700669 * Request the direction for a stream.
670 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700671 * The default, if you do not call this function, is {@link #AAUDIO_DIRECTION_OUTPUT}.
Phil Burk5ed503c2017-02-01 09:38:15 -0800672 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700673 * Available since API level 26.
674 *
Phil Burk3316d5e2017-02-15 11:23:01 -0800675 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700676 * @param direction {@link #AAUDIO_DIRECTION_OUTPUT} or {@link #AAUDIO_DIRECTION_INPUT}
Phil Burk5ed503c2017-02-01 09:38:15 -0800677 */
Phil Burke2155ef2017-02-24 13:50:29 -0800678AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700679 aaudio_direction_t direction) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -0800680
681/**
Phil Burke057ca92017-03-28 11:31:34 -0700682 * Set the requested buffer capacity in frames.
Phil Burk3df348f2017-02-08 11:41:55 -0800683 * The final AAudioStream capacity may differ, but will probably be at least this big.
684 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700685 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}.
Phil Burk3df348f2017-02-08 11:41:55 -0800686 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700687 * Available since API level 26.
688 *
Phil Burk3316d5e2017-02-15 11:23:01 -0800689 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700690 * @param numFrames the desired buffer capacity in frames or {@link #AAUDIO_UNSPECIFIED}
Phil Burk3df348f2017-02-08 11:41:55 -0800691 */
Phil Burke2155ef2017-02-24 13:50:29 -0800692AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700693 int32_t numFrames) __INTRODUCED_IN(26);
Phil Burke2fbb592017-05-01 15:05:52 -0700694
695/**
696 * Set the requested performance mode.
697 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700698 * Supported modes are {@link #AAUDIO_PERFORMANCE_MODE_NONE},
699 * {@link #AAUDIO_PERFORMANCE_MODE_POWER_SAVING} * and {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY}.
Phil Burk8149eed2018-05-24 14:09:46 -0700700 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700701 * The default, if you do not call this function, is {@link #AAUDIO_PERFORMANCE_MODE_NONE}.
Phil Burke2fbb592017-05-01 15:05:52 -0700702 *
Phil Burk8149eed2018-05-24 14:09:46 -0700703 * You may not get the mode you requested.
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700704 * You can call AAudioStream_getPerformanceMode()
705 * to find out the final mode for the stream.
Phil Burk8149eed2018-05-24 14:09:46 -0700706 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700707 * Available since API level 26.
708 *
Phil Burke2fbb592017-05-01 15:05:52 -0700709 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700710 * @param mode the desired performance mode, eg. {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY}
Phil Burke2fbb592017-05-01 15:05:52 -0700711 */
712AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700713 aaudio_performance_mode_t mode) __INTRODUCED_IN(26);
Phil Burke2fbb592017-05-01 15:05:52 -0700714
Phil Burke057ca92017-03-28 11:31:34 -0700715/**
jiabinec3fa352020-08-11 16:29:26 -0700716 * Set the intended use case for the output stream.
Phil Burk361b1422017-12-20 14:24:16 -0800717 *
718 * The AAudio system will use this information to optimize the
719 * behavior of the stream.
720 * This could, for example, affect how volume and focus is handled for the stream.
721 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700722 * The default, if you do not call this function, is {@link #AAUDIO_USAGE_MEDIA}.
Phil Burk361b1422017-12-20 14:24:16 -0800723 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700724 * Available since API level 28.
Phil Burk42452c02018-04-10 12:43:33 -0700725 *
Phil Burk361b1422017-12-20 14:24:16 -0800726 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700727 * @param usage the desired usage, eg. {@link #AAUDIO_USAGE_GAME}
Phil Burk361b1422017-12-20 14:24:16 -0800728 */
729AAUDIO_API void AAudioStreamBuilder_setUsage(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700730 aaudio_usage_t usage) __INTRODUCED_IN(28);
Phil Burk361b1422017-12-20 14:24:16 -0800731
732/**
jiabinec3fa352020-08-11 16:29:26 -0700733 * Set the type of audio data that the output stream will carry.
Phil Burk361b1422017-12-20 14:24:16 -0800734 *
735 * The AAudio system will use this information to optimize the
736 * behavior of the stream.
737 * This could, for example, affect whether a stream is paused when a notification occurs.
738 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700739 * The default, if you do not call this function, is {@link #AAUDIO_CONTENT_TYPE_MUSIC}.
Phil Burk361b1422017-12-20 14:24:16 -0800740 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700741 * Available since API level 28.
Phil Burk42452c02018-04-10 12:43:33 -0700742 *
Phil Burk361b1422017-12-20 14:24:16 -0800743 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700744 * @param contentType the type of audio data, eg. {@link #AAUDIO_CONTENT_TYPE_SPEECH}
Phil Burk361b1422017-12-20 14:24:16 -0800745 */
746AAUDIO_API void AAudioStreamBuilder_setContentType(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700747 aaudio_content_type_t contentType) __INTRODUCED_IN(28);
Phil Burk361b1422017-12-20 14:24:16 -0800748
749/**
750 * Set the input (capture) preset for the stream.
751 *
752 * The AAudio system will use this information to optimize the
753 * behavior of the stream.
754 * This could, for example, affect which microphones are used and how the
755 * recorded data is processed.
756 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700757 * The default, if you do not call this function, is {@link #AAUDIO_INPUT_PRESET_VOICE_RECOGNITION}.
Phil Burkeaef9b92018-01-18 09:09:42 -0800758 * That is because VOICE_RECOGNITION is the preset with the lowest latency
759 * on many platforms.
Phil Burk361b1422017-12-20 14:24:16 -0800760 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700761 * Available since API level 28.
Phil Burk42452c02018-04-10 12:43:33 -0700762 *
Phil Burk361b1422017-12-20 14:24:16 -0800763 * @param builder reference provided by AAudio_createStreamBuilder()
764 * @param inputPreset the desired configuration for recording
765 */
766AAUDIO_API void AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700767 aaudio_input_preset_t inputPreset) __INTRODUCED_IN(28);
Phil Burk361b1422017-12-20 14:24:16 -0800768
Kevin Rocard68646ba2019-03-20 13:26:49 -0700769/**
770 * Specify whether this stream audio may or may not be captured by other apps or the system.
771 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700772 * The default is {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL}.
Kevin Rocard68646ba2019-03-20 13:26:49 -0700773 *
774 * Note that an application can also set its global policy, in which case the most restrictive
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700775 * policy is always applied. See {@link android.media.AudioAttributes#setAllowedCapturePolicy(int)}
Kevin Rocard68646ba2019-03-20 13:26:49 -0700776 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700777 * Available since API level 29.
Kevin Rocard68646ba2019-03-20 13:26:49 -0700778 *
779 * @param builder reference provided by AAudio_createStreamBuilder()
Glenn Kastend3080c32019-10-24 09:54:56 -0700780 * @param capturePolicy the desired level of opt-out from being captured.
Kevin Rocard68646ba2019-03-20 13:26:49 -0700781 */
782AAUDIO_API void AAudioStreamBuilder_setAllowedCapturePolicy(AAudioStreamBuilder* builder,
783 aaudio_allowed_capture_policy_t capturePolicy) __INTRODUCED_IN(29);
784
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800785/** Set the requested session ID.
786 *
787 * The session ID can be used to associate a stream with effects processors.
788 * The effects are controlled using the Android AudioEffect Java API.
789 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700790 * The default, if you do not call this function, is {@link #AAUDIO_SESSION_ID_NONE}.
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800791 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700792 * If set to {@link #AAUDIO_SESSION_ID_ALLOCATE} then a session ID will be allocated
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800793 * when the stream is opened.
794 *
795 * The allocated session ID can be obtained by calling AAudioStream_getSessionId()
796 * and then used with this function when opening another stream.
797 * This allows effects to be shared between streams.
798 *
Phil Burk8149eed2018-05-24 14:09:46 -0700799 * Session IDs from AAudio can be used with the Android Java APIs and vice versa.
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800800 * So a session ID from an AAudio stream can be passed to Java
801 * and effects applied using the Java AudioEffect API.
802 *
Phil Burk8149eed2018-05-24 14:09:46 -0700803 * Note that allocating or setting a session ID may result in a stream with higher latency.
804 *
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800805 * Allocated session IDs will always be positive and nonzero.
806 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700807 * Available since API level 28.
Phil Burk42452c02018-04-10 12:43:33 -0700808 *
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800809 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700810 * @param sessionId an allocated sessionID or {@link #AAUDIO_SESSION_ID_ALLOCATE}
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800811 */
812AAUDIO_API void AAudioStreamBuilder_setSessionId(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700813 aaudio_session_id_t sessionId) __INTRODUCED_IN(28);
Phil Burk7e7dcaa2018-01-03 15:16:15 -0800814
Eric Laurentd17c8502019-10-24 15:58:35 -0700815
816/** Indicates whether this input stream must be marked as privacy sensitive or not.
817 *
818 * When true, this input stream is privacy sensitive and any concurrent capture
819 * is not permitted.
820 *
821 * This is off (false) by default except when the input preset is {@link #AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION}
822 * or {@link #AAUDIO_INPUT_PRESET_CAMCORDER}.
823 *
824 * Always takes precedence over default from input preset when set explicitly.
825 *
826 * Only relevant if the stream direction is {@link #AAUDIO_DIRECTION_INPUT}.
827 *
828 * Added in API level 30.
829 *
830 * @param builder reference provided by AAudio_createStreamBuilder()
831 * @param privacySensitive true if capture from this stream must be marked as privacy sensitive,
832 * false otherwise.
833 */
834AAUDIO_API void AAudioStreamBuilder_setPrivacySensitive(AAudioStreamBuilder* builder,
835 bool privacySensitive) __INTRODUCED_IN(30);
836
Phil Burk361b1422017-12-20 14:24:16 -0800837/**
Phil Burke057ca92017-03-28 11:31:34 -0700838 * Return one of these values from the data callback function.
839 */
840enum {
841
842 /**
843 * Continue calling the callback.
844 */
845 AAUDIO_CALLBACK_RESULT_CONTINUE = 0,
846
847 /**
848 * Stop calling the callback.
849 *
850 * The application will still need to call AAudioStream_requestPause()
851 * or AAudioStream_requestStop().
852 */
853 AAUDIO_CALLBACK_RESULT_STOP,
854
855};
856typedef int32_t aaudio_data_callback_result_t;
857
858/**
859 * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback().
860 *
861 * For an output stream, this function should render and write numFrames of data
862 * in the streams current data format to the audioData buffer.
863 *
864 * For an input stream, this function should read and process numFrames of data
865 * from the audioData buffer.
866 *
Phil Burked0a3fe2017-12-05 14:27:43 -0800867 * The audio data is passed through the buffer. So do NOT call AAudioStream_read() or
868 * AAudioStream_write() on the stream that is making the callback.
869 *
870 * Note that numFrames can vary unless AAudioStreamBuilder_setFramesPerDataCallback()
871 * is called.
872 *
873 * Also note that this callback function should be considered a "real-time" function.
Phil Burke057ca92017-03-28 11:31:34 -0700874 * It must not do anything that could cause an unbounded delay because that can cause the
875 * audio to glitch or pop.
876 *
877 * These are things the function should NOT do:
878 * <ul>
879 * <li>allocate memory using, for example, malloc() or new</li>
880 * <li>any file operations such as opening, closing, reading or writing</li>
881 * <li>any network operations such as streaming</li>
882 * <li>use any mutexes or other synchronization primitives</li>
883 * <li>sleep</li>
Phil Burked0a3fe2017-12-05 14:27:43 -0800884 * <li>stop or close the stream</li>
Phil Burk8149eed2018-05-24 14:09:46 -0700885 * <li>AAudioStream_read()</li>
886 * <li>AAudioStream_write()</li>
887 * </ul>
888 *
889 * The following are OK to call from the data callback:
890 * <ul>
891 * <li>AAudioStream_get*()</li>
892 * <li>AAudio_convertResultToText()</li>
Phil Burke057ca92017-03-28 11:31:34 -0700893 * </ul>
894 *
895 * If you need to move data, eg. MIDI commands, in or out of the callback function then
896 * we recommend the use of non-blocking techniques such as an atomic FIFO.
897 *
898 * @param stream reference provided by AAudioStreamBuilder_openStream()
899 * @param userData the same address that was passed to AAudioStreamBuilder_setCallback()
900 * @param audioData a pointer to the audio data
Phil Burked0a3fe2017-12-05 14:27:43 -0800901 * @param numFrames the number of frames to be processed, which can vary
Phil Burke057ca92017-03-28 11:31:34 -0700902 * @return AAUDIO_CALLBACK_RESULT_*
903 */
904typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)(
905 AAudioStream *stream,
906 void *userData,
907 void *audioData,
908 int32_t numFrames);
909
910/**
911 * Request that AAudio call this functions when the stream is running.
912 *
913 * Note that when using this callback, the audio data will be passed in or out
914 * of the function as an argument.
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700915 * So you cannot call AAudioStream_write() or AAudioStream_read()
916 * on the same stream that has an active data callback.
Phil Burke057ca92017-03-28 11:31:34 -0700917 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700918 * The callback function will start being called after AAudioStream_requestStart()
919 * is called.
Phil Burke057ca92017-03-28 11:31:34 -0700920 * It will stop being called after AAudioStream_requestPause() or
921 * AAudioStream_requestStop() is called.
922 *
923 * This callback function will be called on a real-time thread owned by AAudio. See
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700924 * {@link #AAudioStream_dataCallback} for more information.
Phil Burke057ca92017-03-28 11:31:34 -0700925 *
926 * Note that the AAudio callbacks will never be called simultaneously from multiple threads.
927 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700928 * Available since API level 26.
929 *
Phil Burke057ca92017-03-28 11:31:34 -0700930 * @param builder reference provided by AAudio_createStreamBuilder()
931 * @param callback pointer to a function that will process audio data.
932 * @param userData pointer to an application data structure that will be passed
933 * to the callback functions.
934 */
935AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700936 AAudioStream_dataCallback callback, void *userData) __INTRODUCED_IN(26);
Phil Burke057ca92017-03-28 11:31:34 -0700937
938/**
939 * Set the requested data callback buffer size in frames.
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700940 * See {@link #AAudioStream_dataCallback}.
Phil Burke057ca92017-03-28 11:31:34 -0700941 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700942 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}.
Phil Burke057ca92017-03-28 11:31:34 -0700943 *
944 * For the lowest possible latency, do not call this function. AAudio will then
945 * call the dataProc callback function with whatever size is optimal.
946 * That size may vary from one callback to another.
947 *
948 * Only use this function if the application requires a specific number of frames for processing.
949 * The application might, for example, be using an FFT that requires
950 * a specific power-of-two sized buffer.
951 *
952 * AAudio may need to add additional buffering in order to adapt between the internal
953 * buffer size and the requested buffer size.
954 *
955 * If you do call this function then the requested size should be less than
956 * half the buffer capacity, to allow double buffering.
957 *
Elliott Hughes64a3b062019-10-29 10:09:30 -0700958 * Available since API level 26.
959 *
Phil Burke057ca92017-03-28 11:31:34 -0700960 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -0700961 * @param numFrames the desired buffer size in frames or {@link #AAUDIO_UNSPECIFIED}
Phil Burke057ca92017-03-28 11:31:34 -0700962 */
963AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -0700964 int32_t numFrames) __INTRODUCED_IN(26);
Phil Burke057ca92017-03-28 11:31:34 -0700965
966/**
967 * Prototype for the callback function that is passed to
968 * AAudioStreamBuilder_setErrorCallback().
969 *
Phil Burk8149eed2018-05-24 14:09:46 -0700970 * The following may NOT be called from the error callback:
971 * <ul>
972 * <li>AAudioStream_requestStop()</li>
973 * <li>AAudioStream_requestPause()</li>
974 * <li>AAudioStream_close()</li>
975 * <li>AAudioStream_waitForStateChange()</li>
976 * <li>AAudioStream_read()</li>
977 * <li>AAudioStream_write()</li>
978 * </ul>
979 *
980 * The following are OK to call from the error callback:
981 * <ul>
982 * <li>AAudioStream_get*()</li>
983 * <li>AAudio_convertResultToText()</li>
984 * </ul>
985 *
Phil Burke057ca92017-03-28 11:31:34 -0700986 * @param stream reference provided by AAudioStreamBuilder_openStream()
987 * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback()
988 * @param error an AAUDIO_ERROR_* value.
989 */
990typedef void (*AAudioStream_errorCallback)(
991 AAudioStream *stream,
992 void *userData,
993 aaudio_result_t error);
994
995/**
Phil Burked0a3fe2017-12-05 14:27:43 -0800996 * Request that AAudio call this function if any error occurs or the stream is disconnected.
Phil Burke057ca92017-03-28 11:31:34 -0700997 *
998 * It will be called, for example, if a headset or a USB device is unplugged causing the stream's
Phil Burked0a3fe2017-12-05 14:27:43 -0800999 * device to be unavailable or "disconnected".
Phil Burke057ca92017-03-28 11:31:34 -07001000 * Another possible cause of error would be a timeout or an unanticipated internal error.
1001 *
Phil Burked0a3fe2017-12-05 14:27:43 -08001002 * In response, this function should signal or create another thread to stop
1003 * and close this stream. The other thread could then reopen a stream on another device.
1004 * Do not stop or close the stream, or reopen the new stream, directly from this callback.
1005 *
1006 * This callback will not be called because of actions by the application, such as stopping
1007 * or closing a stream.
1008 *
Phil Burke057ca92017-03-28 11:31:34 -07001009 * Note that the AAudio callbacks will never be called simultaneously from multiple threads.
1010 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001011 * Available since API level 26.
1012 *
Phil Burke057ca92017-03-28 11:31:34 -07001013 * @param builder reference provided by AAudio_createStreamBuilder()
1014 * @param callback pointer to a function that will be called if an error occurs.
1015 * @param userData pointer to an application data structure that will be passed
1016 * to the callback functions.
1017 */
1018AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -07001019 AAudioStream_errorCallback callback, void *userData) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001020
1021/**
1022 * Open a stream based on the options in the StreamBuilder.
1023 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001024 * AAudioStream_close() must be called when finished with the stream to recover
Phil Burk5ed503c2017-02-01 09:38:15 -08001025 * the memory and to free the associated resources.
1026 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001027 * Available since API level 26.
1028 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001029 * @param builder reference provided by AAudio_createStreamBuilder()
1030 * @param stream pointer to a variable to receive the new stream reference
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001031 * @return {@link #AAUDIO_OK} or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001032 */
Phil Burke2155ef2017-02-24 13:50:29 -08001033AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder,
Elliott Hughes85a41532018-06-18 13:17:24 -07001034 AAudioStream** stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001035
1036/**
1037 * Delete the resources associated with the StreamBuilder.
1038 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001039 * Available since API level 26.
1040 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001041 * @param builder reference provided by AAudio_createStreamBuilder()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001042 * @return {@link #AAUDIO_OK} or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001043 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001044AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* builder)
1045 __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001046
1047// ============================================================
1048// Stream Control
1049// ============================================================
1050
Phil Burk8b4e05e2019-12-17 12:12:09 -08001051#if __ANDROID_API__ >= 30
Phil Burk5ed503c2017-02-01 09:38:15 -08001052/**
Phil Burk8b4e05e2019-12-17 12:12:09 -08001053 * Free the audio resources associated with a stream created by
1054 * AAudioStreamBuilder_openStream().
1055 * AAudioStream_close() should be called at some point after calling
1056 * this function.
Phil Burk5ed503c2017-02-01 09:38:15 -08001057 *
Phil Burk8b4e05e2019-12-17 12:12:09 -08001058 * After this call, the stream will be in {@link #AAUDIO_STREAM_STATE_CLOSING}
1059 *
Phil Burk41561762020-02-05 14:20:33 -08001060 * This function is useful if you want to release the audio resources immediately,
1061 * but still allow queries to the stream to occur from other threads. This often
1062 * happens if you are monitoring stream progress from a UI thread.
1063 *
Phil Burk320910f2020-08-12 14:29:10 +00001064 * NOTE: This function is only fully implemented for MMAP streams,
1065 * which are low latency streams supported by some devices.
1066 * On other "Legacy" streams some audio resources will still be in use
1067 * and some callbacks may still be in process after this call.
1068 *
Phil Burk8b4e05e2019-12-17 12:12:09 -08001069 * @param stream reference provided by AAudioStreamBuilder_openStream()
1070 * @return {@link #AAUDIO_OK} or a negative error.
1071 */
1072AAUDIO_API aaudio_result_t AAudioStream_release(AAudioStream* stream) __INTRODUCED_IN(30);
1073#endif // __ANDROID_API__
1074
1075/**
1076 * Delete the internal data structures associated with the stream created
1077 * by AAudioStreamBuilder_openStream().
1078 *
1079 * If AAudioStream_release() has not been called then it will be called automatically.
Elliott Hughes64a3b062019-10-29 10:09:30 -07001080 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001081 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001082 * @return {@link #AAUDIO_OK} or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001083 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001084AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001085
1086/**
1087 * Asynchronously request to start playing the stream. For output streams, one should
1088 * write to the stream to fill the buffer before starting.
1089 * Otherwise it will underflow.
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001090 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_STARTING} or
1091 * {@link #AAUDIO_STREAM_STATE_STARTED}.
Phil Burk5ed503c2017-02-01 09:38:15 -08001092 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001093 * Available since API level 26.
1094 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001095 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001096 * @return {@link #AAUDIO_OK} or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001097 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001098AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001099
1100/**
1101 * Asynchronous request for the stream to pause.
1102 * Pausing a stream will freeze the data flow but not flush any buffers.
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001103 * Use AAudioStream_requestStart() to resume playback after a pause.
1104 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_PAUSING} or
1105 * {@link #AAUDIO_STREAM_STATE_PAUSED}.
Phil Burk5ed503c2017-02-01 09:38:15 -08001106 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001107 * This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams.
Phil Burk068c10f2017-05-08 16:36:41 -07001108 * For input streams use AAudioStream_requestStop().
1109 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001110 * Available since API level 26.
1111 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001112 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001113 * @return {@link #AAUDIO_OK} or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001114 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001115AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001116
1117/**
1118 * Asynchronous request for the stream to flush.
1119 * Flushing will discard any pending data.
1120 * This call only works if the stream is pausing or paused. TODO review
1121 * Frame counters are not reset by a flush. They may be advanced.
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001122 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_FLUSHING} or
1123 * {@link #AAUDIO_STREAM_STATE_FLUSHED}.
Phil Burk5ed503c2017-02-01 09:38:15 -08001124 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001125 * This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams.
Phil Burk068c10f2017-05-08 16:36:41 -07001126 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001127 * Available since API level 26.
1128 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001129 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001130 * @return {@link #AAUDIO_OK} or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001131 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001132AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001133
1134/**
1135 * Asynchronous request for the stream to stop.
1136 * The stream will stop after all of the data currently buffered has been played.
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001137 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_STOPPING} or
1138 * {@link #AAUDIO_STREAM_STATE_STOPPED}.
Phil Burk5ed503c2017-02-01 09:38:15 -08001139 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001140 * Available since API level 26.
1141 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001142 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001143 * @return {@link #AAUDIO_OK} or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001144 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001145AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001146
1147/**
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001148 * Query the current state of the client, eg. {@link #AAUDIO_STREAM_STATE_PAUSING}
Phil Burk5ed503c2017-02-01 09:38:15 -08001149 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001150 * This function will immediately return the state without updating the state.
1151 * If you want to update the client state based on the server state then
1152 * call AAudioStream_waitForStateChange() with currentState
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001153 * set to {@link #AAUDIO_STREAM_STATE_UNKNOWN} and a zero timeout.
Phil Burk3316d5e2017-02-15 11:23:01 -08001154 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001155 * Available since API level 26.
1156 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001157 * @param stream reference provided by AAudioStreamBuilder_openStream()
Phil Burk5ed503c2017-02-01 09:38:15 -08001158 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001159AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001160
1161/**
1162 * Wait until the current state no longer matches the input state.
1163 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001164 * This will update the current client state.
1165 *
Phil Burk5ed503c2017-02-01 09:38:15 -08001166 * <pre><code>
Phil Burked0a3fe2017-12-05 14:27:43 -08001167 * aaudio_result_t result = AAUDIO_OK;
1168 * aaudio_stream_state_t currentState = AAudioStream_getState(stream);
1169 * aaudio_stream_state_t inputState = currentState;
1170 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSED) {
Phil Burk5ed503c2017-02-01 09:38:15 -08001171 * result = AAudioStream_waitForStateChange(
Phil Burked0a3fe2017-12-05 14:27:43 -08001172 * stream, inputState, &currentState, MY_TIMEOUT_NANOS);
1173 * inputState = currentState;
Phil Burk5ed503c2017-02-01 09:38:15 -08001174 * }
1175 * </code></pre>
1176 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001177 * Available since API level 26.
1178 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001179 * @param stream A reference provided by AAudioStreamBuilder_openStream()
Phil Burk5ed503c2017-02-01 09:38:15 -08001180 * @param inputState The state we want to avoid.
1181 * @param nextState Pointer to a variable that will be set to the new state.
1182 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001183 * @return {@link #AAUDIO_OK} or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001184 */
Phil Burke2155ef2017-02-24 13:50:29 -08001185AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream,
Elliott Hughes85a41532018-06-18 13:17:24 -07001186 aaudio_stream_state_t inputState, aaudio_stream_state_t *nextState,
1187 int64_t timeoutNanoseconds) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001188
1189// ============================================================
1190// Stream I/O
1191// ============================================================
1192
1193/**
1194 * Read data from the stream.
1195 *
1196 * The call will wait until the read is complete or until it runs out of time.
1197 * If timeoutNanos is zero then this call will not wait.
1198 *
1199 * Note that timeoutNanoseconds is a relative duration in wall clock time.
1200 * Time will not stop if the thread is asleep.
1201 * So it will be implemented using CLOCK_BOOTTIME.
1202 *
1203 * This call is "strong non-blocking" unless it has to wait for data.
1204 *
Phil Burk8149eed2018-05-24 14:09:46 -07001205 * If the call times out then zero or a partial frame count will be returned.
1206 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001207 * Available since API level 26.
1208 *
Phil Burk5ed503c2017-02-01 09:38:15 -08001209 * @param stream A stream created using AAudioStreamBuilder_openStream().
1210 * @param buffer The address of the first sample.
1211 * @param numFrames Number of frames to read. Only complete frames will be written.
1212 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
Phil Burk3316d5e2017-02-15 11:23:01 -08001213 * @return The number of frames actually read or a negative error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001214 */
Phil Burke2155ef2017-02-24 13:50:29 -08001215AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream,
Elliott Hughes85a41532018-06-18 13:17:24 -07001216 void *buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001217
1218/**
1219 * Write data to the stream.
1220 *
1221 * The call will wait until the write is complete or until it runs out of time.
1222 * If timeoutNanos is zero then this call will not wait.
1223 *
1224 * Note that timeoutNanoseconds is a relative duration in wall clock time.
1225 * Time will not stop if the thread is asleep.
1226 * So it will be implemented using CLOCK_BOOTTIME.
1227 *
1228 * This call is "strong non-blocking" unless it has to wait for room in the buffer.
1229 *
Phil Burk8149eed2018-05-24 14:09:46 -07001230 * If the call times out then zero or a partial frame count will be returned.
1231 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001232 * Available since API level 26.
1233 *
Phil Burk5ed503c2017-02-01 09:38:15 -08001234 * @param stream A stream created using AAudioStreamBuilder_openStream().
1235 * @param buffer The address of the first sample.
1236 * @param numFrames Number of frames to write. Only complete frames will be written.
1237 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
1238 * @return The number of frames actually written or a negative error.
1239 */
Phil Burke2155ef2017-02-24 13:50:29 -08001240AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream,
Elliott Hughes85a41532018-06-18 13:17:24 -07001241 const void *buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001242
Phil Burk5ed503c2017-02-01 09:38:15 -08001243// ============================================================
1244// Stream - queries
1245// ============================================================
1246
Phil Burk5ed503c2017-02-01 09:38:15 -08001247/**
1248 * This can be used to adjust the latency of the buffer by changing
1249 * the threshold where blocking will occur.
Phil Burk3316d5e2017-02-15 11:23:01 -08001250 * By combining this with AAudioStream_getXRunCount(), the latency can be tuned
Phil Burk5ed503c2017-02-01 09:38:15 -08001251 * at run-time for each device.
1252 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001253 * This cannot be set higher than AAudioStream_getBufferCapacityInFrames().
Phil Burk5ed503c2017-02-01 09:38:15 -08001254 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001255 * Note that you will probably not get the exact size you request.
Phil Burk8149eed2018-05-24 14:09:46 -07001256 * You can check the return value or call AAudioStream_getBufferSizeInFrames()
1257 * to see what the actual final size is.
Phil Burk3316d5e2017-02-15 11:23:01 -08001258 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001259 * Available since API level 26.
1260 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001261 * @param stream reference provided by AAudioStreamBuilder_openStream()
Phil Burke057ca92017-03-28 11:31:34 -07001262 * @param numFrames requested number of frames that can be filled without blocking
Phil Burk3316d5e2017-02-15 11:23:01 -08001263 * @return actual buffer size in frames or a negative error
Phil Burk5ed503c2017-02-01 09:38:15 -08001264 */
Phil Burke2155ef2017-02-24 13:50:29 -08001265AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream,
Elliott Hughes85a41532018-06-18 13:17:24 -07001266 int32_t numFrames) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001267
1268/**
1269 * Query the maximum number of frames that can be filled without blocking.
1270 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001271 * Available since API level 26.
1272 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001273 * @param stream reference provided by AAudioStreamBuilder_openStream()
1274 * @return buffer size in frames.
Phil Burk5ed503c2017-02-01 09:38:15 -08001275 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001276AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001277
1278/**
Phil Burk3316d5e2017-02-15 11:23:01 -08001279 * Query the number of frames that the application should read or write at
1280 * one time for optimal performance. It is OK if an application writes
1281 * a different number of frames. But the buffer size may need to be larger
1282 * in order to avoid underruns or overruns.
Phil Burk5ed503c2017-02-01 09:38:15 -08001283 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001284 * Note that this may or may not match the actual device burst size.
1285 * For some endpoints, the burst size can vary dynamically.
1286 * But these tend to be devices with high latency.
1287 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001288 * Available since API level 26.
1289 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001290 * @param stream reference provided by AAudioStreamBuilder_openStream()
1291 * @return burst size
Phil Burk5ed503c2017-02-01 09:38:15 -08001292 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001293AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001294
1295/**
1296 * Query maximum buffer capacity in frames.
1297 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001298 * Available since API level 26.
1299 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001300 * @param stream reference provided by AAudioStreamBuilder_openStream()
Phil Burke057ca92017-03-28 11:31:34 -07001301 * @return buffer capacity in frames
Phil Burk5ed503c2017-02-01 09:38:15 -08001302 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001303AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001304
1305/**
Phil Burke057ca92017-03-28 11:31:34 -07001306 * Query the size of the buffer that will be passed to the dataProc callback
1307 * in the numFrames parameter.
1308 *
1309 * This call can be used if the application needs to know the value of numFrames before
1310 * the stream is started. This is not normally necessary.
1311 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001312 * If a specific size was requested by calling
1313 * AAudioStreamBuilder_setFramesPerDataCallback() then this will be the same size.
Phil Burke057ca92017-03-28 11:31:34 -07001314 *
Phil Burked0a3fe2017-12-05 14:27:43 -08001315 * If AAudioStreamBuilder_setFramesPerDataCallback() was not called then this will
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001316 * return the size chosen by AAudio, or {@link #AAUDIO_UNSPECIFIED}.
Phil Burke057ca92017-03-28 11:31:34 -07001317 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001318 * {@link #AAUDIO_UNSPECIFIED} indicates that the callback buffer size for this stream
Phil Burke057ca92017-03-28 11:31:34 -07001319 * may vary from one dataProc callback to the next.
1320 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001321 * Available since API level 26.
1322 *
Phil Burke057ca92017-03-28 11:31:34 -07001323 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001324 * @return callback buffer size in frames or {@link #AAUDIO_UNSPECIFIED}
Phil Burke057ca92017-03-28 11:31:34 -07001325 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001326AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burke057ca92017-03-28 11:31:34 -07001327
1328/**
Phil Burk5ed503c2017-02-01 09:38:15 -08001329 * An XRun is an Underrun or an Overrun.
1330 * During playing, an underrun will occur if the stream is not written in time
1331 * and the system runs out of valid data.
1332 * During recording, an overrun will occur if the stream is not read in time
1333 * and there is no place to put the incoming data so it is discarded.
1334 *
1335 * An underrun or overrun can cause an audible "pop" or "glitch".
1336 *
Phil Burk068c10f2017-05-08 16:36:41 -07001337 * Note that some INPUT devices may not support this function.
1338 * In that case a 0 will always be returned.
1339 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001340 * Available since API level 26.
1341 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001342 * @param stream reference provided by AAudioStreamBuilder_openStream()
1343 * @return the underrun or overrun count
Phil Burk5ed503c2017-02-01 09:38:15 -08001344 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001345AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001346
1347/**
Elliott Hughes64a3b062019-10-29 10:09:30 -07001348 * Available since API level 26.
1349 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001350 * @param stream reference provided by AAudioStreamBuilder_openStream()
1351 * @return actual sample rate
Phil Burk5ed503c2017-02-01 09:38:15 -08001352 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001353AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001354
1355/**
Phil Burk20523ed2017-04-24 17:04:01 -07001356 * A stream has one or more channels of data.
1357 * A frame will contain one sample for each channel.
1358 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001359 * Available since API level 26.
1360 *
Phil Burk20523ed2017-04-24 17:04:01 -07001361 * @param stream reference provided by AAudioStreamBuilder_openStream()
1362 * @return actual number of channels
1363 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001364AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk20523ed2017-04-24 17:04:01 -07001365
1366/**
Phil Burke74240d2017-08-03 15:25:43 -07001367 * Identical to AAudioStream_getChannelCount().
1368 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001369 * Available since API level 26.
1370 *
Phil Burke74240d2017-08-03 15:25:43 -07001371 * @param stream reference provided by AAudioStreamBuilder_openStream()
1372 * @return actual number of samples frame
1373 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001374AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burke74240d2017-08-03 15:25:43 -07001375
1376/**
Elliott Hughes64a3b062019-10-29 10:09:30 -07001377 * Available since API level 26.
1378 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001379 * @param stream reference provided by AAudioStreamBuilder_openStream()
Phil Burke2155ef2017-02-24 13:50:29 -08001380 * @return actual device ID
Phil Burk5ed503c2017-02-01 09:38:15 -08001381 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001382AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001383
1384/**
Elliott Hughes64a3b062019-10-29 10:09:30 -07001385 * Available since API level 26.
1386 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001387 * @param stream reference provided by AAudioStreamBuilder_openStream()
1388 * @return actual data format
Phil Burk5ed503c2017-02-01 09:38:15 -08001389 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001390AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001391
1392/**
1393 * Provide actual sharing mode.
Elliott Hughes64a3b062019-10-29 10:09:30 -07001394 *
1395 * Available since API level 26.
1396 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001397 * @param stream reference provided by AAudioStreamBuilder_openStream()
1398 * @return actual sharing mode
Phil Burk5ed503c2017-02-01 09:38:15 -08001399 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001400AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream)
1401 __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001402
1403/**
Phil Burke2fbb592017-05-01 15:05:52 -07001404 * Get the performance mode used by the stream.
1405 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001406 * Available since API level 26.
1407 *
Phil Burke2fbb592017-05-01 15:05:52 -07001408 * @param stream reference provided by AAudioStreamBuilder_openStream()
1409 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001410AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* stream)
1411 __INTRODUCED_IN(26);
Phil Burke2fbb592017-05-01 15:05:52 -07001412
1413/**
Elliott Hughes64a3b062019-10-29 10:09:30 -07001414 * Available since API level 26.
1415 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001416 * @param stream reference provided by AAudioStreamBuilder_openStream()
1417 * @return direction
Phil Burk5ed503c2017-02-01 09:38:15 -08001418 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001419AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001420
1421/**
1422 * Passes back the number of frames that have been written since the stream was created.
Phil Burk8149eed2018-05-24 14:09:46 -07001423 * For an output stream, this will be advanced by the application calling write()
1424 * or by a data callback.
Phil Burk3316d5e2017-02-15 11:23:01 -08001425 * For an input stream, this will be advanced by the endpoint.
Phil Burk5ed503c2017-02-01 09:38:15 -08001426 *
1427 * The frame position is monotonically increasing.
1428 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001429 * Available since API level 26.
1430 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001431 * @param stream reference provided by AAudioStreamBuilder_openStream()
1432 * @return frames written
Phil Burk5ed503c2017-02-01 09:38:15 -08001433 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001434AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001435
1436/**
1437 * Passes back the number of frames that have been read since the stream was created.
Phil Burk3316d5e2017-02-15 11:23:01 -08001438 * For an output stream, this will be advanced by the endpoint.
Phil Burk8149eed2018-05-24 14:09:46 -07001439 * For an input stream, this will be advanced by the application calling read()
1440 * or by a data callback.
Phil Burk5ed503c2017-02-01 09:38:15 -08001441 *
1442 * The frame position is monotonically increasing.
1443 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001444 * Available since API level 26.
1445 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001446 * @param stream reference provided by AAudioStreamBuilder_openStream()
1447 * @return frames read
Phil Burk5ed503c2017-02-01 09:38:15 -08001448 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001449AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001450
1451/**
Phil Burk7e7dcaa2018-01-03 15:16:15 -08001452 * Passes back the session ID associated with this stream.
1453 *
1454 * The session ID can be used to associate a stream with effects processors.
1455 * The effects are controlled using the Android AudioEffect Java API.
1456 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001457 * If AAudioStreamBuilder_setSessionId() was
1458 * called with {@link #AAUDIO_SESSION_ID_ALLOCATE}
Phil Burk7e7dcaa2018-01-03 15:16:15 -08001459 * then a new session ID should be allocated once when the stream is opened.
1460 *
1461 * If AAudioStreamBuilder_setSessionId() was called with a previously allocated
1462 * session ID then that value should be returned.
1463 *
1464 * If AAudioStreamBuilder_setSessionId() was not called then this function should
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001465 * return {@link #AAUDIO_SESSION_ID_NONE}.
Phil Burk7e7dcaa2018-01-03 15:16:15 -08001466 *
1467 * The sessionID for a stream should not change once the stream has been opened.
1468 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001469 * Available since API level 28.
Phil Burk42452c02018-04-10 12:43:33 -07001470 *
Phil Burk7e7dcaa2018-01-03 15:16:15 -08001471 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001472 * @return session ID or {@link #AAUDIO_SESSION_ID_NONE}
Phil Burk7e7dcaa2018-01-03 15:16:15 -08001473 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001474AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(AAudioStream* stream) __INTRODUCED_IN(28);
Phil Burk7e7dcaa2018-01-03 15:16:15 -08001475
1476/**
Phil Burk5ed503c2017-02-01 09:38:15 -08001477 * Passes back the time at which a particular frame was presented.
1478 * This can be used to synchronize audio with video or MIDI.
1479 * It can also be used to align a recorded stream with a playback stream.
1480 *
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001481 * Timestamps are only valid when the stream is in {@link #AAUDIO_STREAM_STATE_STARTED}.
1482 * {@link #AAUDIO_ERROR_INVALID_STATE} will be returned if the stream is not started.
Phil Burk5ed503c2017-02-01 09:38:15 -08001483 * Note that because requestStart() is asynchronous, timestamps will not be valid until
1484 * a short time after calling requestStart().
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001485 * So {@link #AAUDIO_ERROR_INVALID_STATE} should not be considered a fatal error.
Phil Burk5ed503c2017-02-01 09:38:15 -08001486 * Just try calling again later.
1487 *
1488 * If an error occurs, then the position and time will not be modified.
1489 *
1490 * The position and time passed back are monotonically increasing.
1491 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001492 * Available since API level 26.
1493 *
Phil Burk3316d5e2017-02-15 11:23:01 -08001494 * @param stream reference provided by AAudioStreamBuilder_openStream()
Phil Burkec159502017-07-25 17:33:47 -07001495 * @param clockid CLOCK_MONOTONIC or CLOCK_BOOTTIME
Phil Burk5ed503c2017-02-01 09:38:15 -08001496 * @param framePosition pointer to a variable to receive the position
1497 * @param timeNanoseconds pointer to a variable to receive the time
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001498 * @return {@link #AAUDIO_OK} or a negative error
Phil Burk5ed503c2017-02-01 09:38:15 -08001499 */
Phil Burke2155ef2017-02-24 13:50:29 -08001500AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream,
Elliott Hughes85a41532018-06-18 13:17:24 -07001501 clockid_t clockid, int64_t *framePosition, int64_t *timeNanoseconds) __INTRODUCED_IN(26);
Phil Burk5ed503c2017-02-01 09:38:15 -08001502
Phil Burk361b1422017-12-20 14:24:16 -08001503/**
1504 * Return the use case for the stream.
1505 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001506 * Available since API level 28.
Phil Burk42452c02018-04-10 12:43:33 -07001507 *
Phil Burk361b1422017-12-20 14:24:16 -08001508 * @param stream reference provided by AAudioStreamBuilder_openStream()
1509 * @return frames read
1510 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001511AAUDIO_API aaudio_usage_t AAudioStream_getUsage(AAudioStream* stream) __INTRODUCED_IN(28);
Phil Burk361b1422017-12-20 14:24:16 -08001512
1513/**
1514 * Return the content type for the stream.
1515 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001516 * Available since API level 28.
Phil Burk42452c02018-04-10 12:43:33 -07001517 *
Phil Burk361b1422017-12-20 14:24:16 -08001518 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001519 * @return content type, for example {@link #AAUDIO_CONTENT_TYPE_MUSIC}
Phil Burk361b1422017-12-20 14:24:16 -08001520 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001521AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(AAudioStream* stream)
1522 __INTRODUCED_IN(28);
Phil Burk361b1422017-12-20 14:24:16 -08001523
1524/**
1525 * Return the input preset for the stream.
1526 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001527 * Available since API level 28.
Phil Burk42452c02018-04-10 12:43:33 -07001528 *
Phil Burk361b1422017-12-20 14:24:16 -08001529 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001530 * @return input preset, for example {@link #AAUDIO_INPUT_PRESET_CAMCORDER}
Phil Burk361b1422017-12-20 14:24:16 -08001531 */
Elliott Hughes85a41532018-06-18 13:17:24 -07001532AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(AAudioStream* stream)
1533 __INTRODUCED_IN(28);
Phil Burk361b1422017-12-20 14:24:16 -08001534
Kevin Rocard68646ba2019-03-20 13:26:49 -07001535/**
1536 * Return the policy that determines whether the audio may or may not be captured
1537 * by other apps or the system.
1538 *
Elliott Hughes64a3b062019-10-29 10:09:30 -07001539 * Available since API level 29.
Kevin Rocard68646ba2019-03-20 13:26:49 -07001540 *
1541 * @param stream reference provided by AAudioStreamBuilder_openStream()
Kevin Rocardfb7e8462019-03-20 13:26:49 -07001542 * @return the allowed capture policy, for example {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL}
Kevin Rocard68646ba2019-03-20 13:26:49 -07001543 */
1544AAUDIO_API aaudio_allowed_capture_policy_t AAudioStream_getAllowedCapturePolicy(
1545 AAudioStream* stream) __INTRODUCED_IN(29);
1546
Eric Laurentd17c8502019-10-24 15:58:35 -07001547
1548/**
1549 * Return whether this input stream is marked as privacy sensitive or not.
1550 *
1551 * See {@link #AAudioStreamBuilder_setPrivacySensitive()}.
1552 *
1553 * Added in API level 30.
1554 *
1555 * @param stream reference provided by AAudioStreamBuilder_openStream()
1556 * @return true if privacy sensitive, false otherwise
1557 */
1558AAUDIO_API bool AAudioStream_isPrivacySensitive(AAudioStream* stream)
1559 __INTRODUCED_IN(30);
1560
Phil Burk5ed503c2017-02-01 09:38:15 -08001561#ifdef __cplusplus
1562}
1563#endif
1564
1565#endif //AAUDIO_AAUDIO_H
Phil Burka45be8b2017-04-05 14:45:48 -07001566
1567/** @} */