1/*
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/**
18 * @addtogroup Audio
19 * @{
20 */
21
22/**
23 * @file AAudio.h
24 */
25
26/**
27 * This is the 'C' API for AAudio.
28 */
29#ifndef AAUDIO_AAUDIO_H
30#define AAUDIO_AAUDIO_H
31
32#include <time.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/**
39 * This is used to represent a value that has not been specified.
40 * For example, an application could use AAUDIO_UNSPECIFIED to indicate
41 * that is did not not care what the specific value of a parameter was
42 * and would accept whatever it was given.
43 */
44#define AAUDIO_UNSPECIFIED           0
45
46enum {
47    AAUDIO_DIRECTION_OUTPUT,
48    AAUDIO_DIRECTION_INPUT
49};
50typedef int32_t aaudio_direction_t;
51
52enum {
53    AAUDIO_FORMAT_INVALID = -1,
54    AAUDIO_FORMAT_UNSPECIFIED = 0,
55    AAUDIO_FORMAT_PCM_I16,
56    AAUDIO_FORMAT_PCM_FLOAT
57};
58typedef int32_t aaudio_format_t;
59
60enum {
61    AAUDIO_OK,
62    AAUDIO_ERROR_BASE = -900, // TODO review
63    AAUDIO_ERROR_DISCONNECTED,
64    AAUDIO_ERROR_ILLEGAL_ARGUMENT,
65    // reserved
66    AAUDIO_ERROR_INTERNAL = AAUDIO_ERROR_ILLEGAL_ARGUMENT + 2,
67    AAUDIO_ERROR_INVALID_STATE,
68    // reserved
69    // reserved
70    AAUDIO_ERROR_INVALID_HANDLE = AAUDIO_ERROR_INVALID_STATE + 3,
71    // reserved
72    AAUDIO_ERROR_UNIMPLEMENTED = AAUDIO_ERROR_INVALID_HANDLE + 2,
73    AAUDIO_ERROR_UNAVAILABLE,
74    AAUDIO_ERROR_NO_FREE_HANDLES,
75    AAUDIO_ERROR_NO_MEMORY,
76    AAUDIO_ERROR_NULL,
77    AAUDIO_ERROR_TIMEOUT,
78    AAUDIO_ERROR_WOULD_BLOCK,
79    AAUDIO_ERROR_INVALID_FORMAT,
80    AAUDIO_ERROR_OUT_OF_RANGE,
81    AAUDIO_ERROR_NO_SERVICE,
82    AAUDIO_ERROR_INVALID_RATE
83};
84typedef int32_t  aaudio_result_t;
85
86enum
87{
88    AAUDIO_STREAM_STATE_UNINITIALIZED = 0,
89    AAUDIO_STREAM_STATE_UNKNOWN,
90    AAUDIO_STREAM_STATE_OPEN,
91    AAUDIO_STREAM_STATE_STARTING,
92    AAUDIO_STREAM_STATE_STARTED,
93    AAUDIO_STREAM_STATE_PAUSING,
94    AAUDIO_STREAM_STATE_PAUSED,
95    AAUDIO_STREAM_STATE_FLUSHING,
96    AAUDIO_STREAM_STATE_FLUSHED,
97    AAUDIO_STREAM_STATE_STOPPING,
98    AAUDIO_STREAM_STATE_STOPPED,
99    AAUDIO_STREAM_STATE_CLOSING,
100    AAUDIO_STREAM_STATE_CLOSED,
101    AAUDIO_STREAM_STATE_DISCONNECTED
102};
103typedef int32_t aaudio_stream_state_t;
104
105
106enum {
107    /**
108     * This will be the only stream using a particular source or sink.
109     * This mode will provide the lowest possible latency.
110     * You should close EXCLUSIVE streams immediately when you are not using them.
111     */
112            AAUDIO_SHARING_MODE_EXCLUSIVE,
113    /**
114     * Multiple applications will be mixed by the AAudio Server.
115     * This will have higher latency than the EXCLUSIVE mode.
116     */
117            AAUDIO_SHARING_MODE_SHARED
118};
119typedef int32_t aaudio_sharing_mode_t;
120
121
122enum {
123    /**
124     * No particular performance needs. Default.
125     */
126            AAUDIO_PERFORMANCE_MODE_NONE = 10,
127
128    /**
129     * Extending battery life is most important.
130     */
131            AAUDIO_PERFORMANCE_MODE_POWER_SAVING,
132
133    /**
134     * Reducing latency is most important.
135     */
136            AAUDIO_PERFORMANCE_MODE_LOW_LATENCY
137};
138typedef int32_t aaudio_performance_mode_t;
139
140typedef struct AAudioStreamStruct         AAudioStream;
141typedef struct AAudioStreamBuilderStruct  AAudioStreamBuilder;
142
143#ifndef AAUDIO_API
144#define AAUDIO_API /* export this symbol */
145#endif
146
147// ============================================================
148// Audio System
149// ============================================================
150
151/**
152 * The text is the ASCII symbol corresponding to the returnCode,
153 * or an English message saying the returnCode is unrecognized.
154 * This is intended for developers to use when debugging.
155 * It is not for display to users.
156 *
157 * @return pointer to a text representation of an AAudio result code.
158 */
159AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode);
160
161/**
162 * The text is the ASCII symbol corresponding to the stream state,
163 * or an English message saying the state is unrecognized.
164 * This is intended for developers to use when debugging.
165 * It is not for display to users.
166 *
167 * @return pointer to a text representation of an AAudio state.
168 */
169AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state);
170
171// ============================================================
172// StreamBuilder
173// ============================================================
174
175/**
176 * Create a StreamBuilder that can be used to open a Stream.
177 *
178 * The deviceId is initially unspecified, meaning that the current default device will be used.
179 *
180 * The default direction is AAUDIO_DIRECTION_OUTPUT.
181 * The default sharing mode is AAUDIO_SHARING_MODE_SHARED.
182 * The data format, samplesPerFrames and sampleRate are unspecified and will be
183 * chosen by the device when it is opened.
184 *
185 * AAudioStreamBuilder_delete() must be called when you are done using the builder.
186 */
187AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder);
188
189/**
190 * Request an audio device identified device using an ID.
191 * On Android, for example, the ID could be obtained from the Java AudioManager.
192 *
193 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED,
194 * in which case the primary device will be used.
195 *
196 * @param builder reference provided by AAudio_createStreamBuilder()
197 * @param deviceId device identifier or AAUDIO_UNSPECIFIED
198 */
199AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder,
200                                                     int32_t deviceId);
201
202/**
203 * Request a sample rate in Hertz.
204 *
205 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.
206 * An optimal value will then be chosen when the stream is opened.
207 * After opening a stream with an unspecified value, the application must
208 * query for the actual value, which may vary by device.
209 *
210 * If an exact value is specified then an opened stream will use that value.
211 * If a stream cannot be opened with the specified value then the open will fail.
212 *
213 * @param builder reference provided by AAudio_createStreamBuilder()
214 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz.
215 */
216AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder,
217                                                       int32_t sampleRate);
218
219/**
220 * Request a number of channels for the stream.
221 *
222 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.
223 * An optimal value will then be chosen when the stream is opened.
224 * After opening a stream with an unspecified value, the application must
225 * query for the actual value, which may vary by device.
226 *
227 * If an exact value is specified then an opened stream will use that value.
228 * If a stream cannot be opened with the specified value then the open will fail.
229 *
230 * @param builder reference provided by AAudio_createStreamBuilder()
231 * @param channelCount Number of channels desired.
232 */
233AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* builder,
234                                                   int32_t channelCount);
235
236/**
237 *
238 * @deprecated use AAudioStreamBuilder_setChannelCount()
239 */
240// TODO remove as soon as the NDK and OS are in sync, before RC1
241AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder,
242                                                       int32_t samplesPerFrame);
243
244/**
245 * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16.
246 *
247 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.
248 * An optimal value will then be chosen when the stream is opened.
249 * After opening a stream with an unspecified value, the application must
250 * query for the actual value, which may vary by device.
251 *
252 * If an exact value is specified then an opened stream will use that value.
253 * If a stream cannot be opened with the specified value then the open will fail.
254 *
255 * @param builder reference provided by AAudio_createStreamBuilder()
256 * @param format common formats are AAUDIO_FORMAT_PCM_FLOAT and AAUDIO_FORMAT_PCM_I16.
257 */
258AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder,
259                                                   aaudio_format_t format);
260
261/**
262 * Request a mode for sharing the device.
263 *
264 * The default, if you do not call this function, is AAUDIO_SHARING_MODE_SHARED.
265 *
266 * The requested sharing mode may not be available.
267 * The application can query for the actual mode after the stream is opened.
268 *
269 * @param builder reference provided by AAudio_createStreamBuilder()
270 * @param sharingMode AAUDIO_SHARING_MODE_SHARED or AAUDIO_SHARING_MODE_EXCLUSIVE
271 */
272AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder,
273                                                        aaudio_sharing_mode_t sharingMode);
274
275/**
276 * Request the direction for a stream.
277 *
278 * The default, if you do not call this function, is AAUDIO_DIRECTION_OUTPUT.
279 *
280 * @param builder reference provided by AAudio_createStreamBuilder()
281 * @param direction AAUDIO_DIRECTION_OUTPUT or AAUDIO_DIRECTION_INPUT
282 */
283AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder,
284                                                            aaudio_direction_t direction);
285
286/**
287 * Set the requested buffer capacity in frames.
288 * The final AAudioStream capacity may differ, but will probably be at least this big.
289 *
290 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.
291 *
292 * @param builder reference provided by AAudio_createStreamBuilder()
293 * @param numFrames the desired buffer capacity in frames or AAUDIO_UNSPECIFIED
294 */
295AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder,
296                                                                 int32_t numFrames);
297
298/**
299 * Set the requested performance mode.
300 *
301 * The default, if you do not call this function, is AAUDIO_PERFORMANCE_MODE_NONE.
302 *
303 * @param builder reference provided by AAudio_createStreamBuilder()
304 * @param mode the desired performance mode, eg. AAUDIO_PERFORMANCE_MODE_LOW_LATENCY
305 */
306AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* builder,
307                                                aaudio_performance_mode_t mode);
308
309/**
310 * Return one of these values from the data callback function.
311 */
312enum {
313
314    /**
315     * Continue calling the callback.
316     */
317    AAUDIO_CALLBACK_RESULT_CONTINUE = 0,
318
319    /**
320     * Stop calling the callback.
321     *
322     * The application will still need to call AAudioStream_requestPause()
323     * or AAudioStream_requestStop().
324     */
325    AAUDIO_CALLBACK_RESULT_STOP,
326
327};
328typedef int32_t aaudio_data_callback_result_t;
329
330/**
331 * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback().
332 *
333 * For an output stream, this function should render and write numFrames of data
334 * in the streams current data format to the audioData buffer.
335 *
336 * For an input stream, this function should read and process numFrames of data
337 * from the audioData buffer.
338 *
339 * Note that this callback function should be considered a "real-time" function.
340 * It must not do anything that could cause an unbounded delay because that can cause the
341 * audio to glitch or pop.
342 *
343 * These are things the function should NOT do:
344 * <ul>
345 * <li>allocate memory using, for example, malloc() or new</li>
346 * <li>any file operations such as opening, closing, reading or writing</li>
347 * <li>any network operations such as streaming</li>
348 * <li>use any mutexes or other synchronization primitives</li>
349 * <li>sleep</li>
350 * </ul>
351 *
352 * If you need to move data, eg. MIDI commands, in or out of the callback function then
353 * we recommend the use of non-blocking techniques such as an atomic FIFO.
354 *
355 * @param stream reference provided by AAudioStreamBuilder_openStream()
356 * @param userData the same address that was passed to AAudioStreamBuilder_setCallback()
357 * @param audioData a pointer to the audio data
358 * @param numFrames the number of frames to be processed
359 * @return AAUDIO_CALLBACK_RESULT_*
360 */
361typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)(
362        AAudioStream *stream,
363        void *userData,
364        void *audioData,
365        int32_t numFrames);
366
367/**
368 * Request that AAudio call this functions when the stream is running.
369 *
370 * Note that when using this callback, the audio data will be passed in or out
371 * of the function as an argument.
372 * So you cannot call AAudioStream_write() or AAudioStream_read() on the same stream
373 * that has an active data callback.
374 *
375 * The callback function will start being called after AAudioStream_requestStart() is called.
376 * It will stop being called after AAudioStream_requestPause() or
377 * AAudioStream_requestStop() is called.
378 *
379 * This callback function will be called on a real-time thread owned by AAudio. See
380 * {@link AAudioStream_dataCallback} for more information.
381 *
382 * Note that the AAudio callbacks will never be called simultaneously from multiple threads.
383 *
384 * @param builder reference provided by AAudio_createStreamBuilder()
385 * @param callback pointer to a function that will process audio data.
386 * @param userData pointer to an application data structure that will be passed
387 *          to the callback functions.
388 */
389AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder,
390                                                 AAudioStream_dataCallback callback,
391                                                 void *userData);
392
393/**
394 * Set the requested data callback buffer size in frames.
395 * See {@link AAudioStream_dataCallback}.
396 *
397 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED.
398 *
399 * For the lowest possible latency, do not call this function. AAudio will then
400 * call the dataProc callback function with whatever size is optimal.
401 * That size may vary from one callback to another.
402 *
403 * Only use this function if the application requires a specific number of frames for processing.
404 * The application might, for example, be using an FFT that requires
405 * a specific power-of-two sized buffer.
406 *
407 * AAudio may need to add additional buffering in order to adapt between the internal
408 * buffer size and the requested buffer size.
409 *
410 * If you do call this function then the requested size should be less than
411 * half the buffer capacity, to allow double buffering.
412 *
413 * @param builder reference provided by AAudio_createStreamBuilder()
414 * @param numFrames the desired buffer size in frames or AAUDIO_UNSPECIFIED
415 */
416AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* builder,
417                                                             int32_t numFrames);
418
419/**
420 * Prototype for the callback function that is passed to
421 * AAudioStreamBuilder_setErrorCallback().
422 *
423 * @param stream reference provided by AAudioStreamBuilder_openStream()
424 * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback()
425 * @param error an AAUDIO_ERROR_* value.
426 */
427typedef void (*AAudioStream_errorCallback)(
428        AAudioStream *stream,
429        void *userData,
430        aaudio_result_t error);
431
432/**
433 * Request that AAudio call this functions if any error occurs on a callback thread.
434 *
435 * It will be called, for example, if a headset or a USB device is unplugged causing the stream's
436 * device to be unavailable.
437 * In response, this function could signal or launch another thread to reopen a
438 * stream on another device. Do not reopen the stream in this callback.
439 *
440 * This will not be called because of actions by the application, such as stopping
441 * or closing a stream.
442 *
443 * Another possible cause of error would be a timeout or an unanticipated internal error.
444 *
445 * Note that the AAudio callbacks will never be called simultaneously from multiple threads.
446 *
447 * @param builder reference provided by AAudio_createStreamBuilder()
448 * @param callback pointer to a function that will be called if an error occurs.
449 * @param userData pointer to an application data structure that will be passed
450 *          to the callback functions.
451 */
452AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builder,
453                                                AAudioStream_errorCallback callback,
454                                                void *userData);
455
456/**
457 * Open a stream based on the options in the StreamBuilder.
458 *
459 * AAudioStream_close must be called when finished with the stream to recover
460 * the memory and to free the associated resources.
461 *
462 * @param builder reference provided by AAudio_createStreamBuilder()
463 * @param stream pointer to a variable to receive the new stream reference
464 * @return AAUDIO_OK or a negative error.
465 */
466AAUDIO_API aaudio_result_t  AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder,
467                                                     AAudioStream** stream);
468
469/**
470 * Delete the resources associated with the StreamBuilder.
471 *
472 * @param builder reference provided by AAudio_createStreamBuilder()
473 * @return AAUDIO_OK or a negative error.
474 */
475AAUDIO_API aaudio_result_t  AAudioStreamBuilder_delete(AAudioStreamBuilder* builder);
476
477// ============================================================
478// Stream Control
479// ============================================================
480
481/**
482 * Free the resources associated with a stream created by AAudioStreamBuilder_openStream()
483 *
484 * @param stream reference provided by AAudioStreamBuilder_openStream()
485 * @return AAUDIO_OK or a negative error.
486 */
487AAUDIO_API aaudio_result_t  AAudioStream_close(AAudioStream* stream);
488
489/**
490 * Asynchronously request to start playing the stream. For output streams, one should
491 * write to the stream to fill the buffer before starting.
492 * Otherwise it will underflow.
493 * After this call the state will be in AAUDIO_STREAM_STATE_STARTING or AAUDIO_STREAM_STATE_STARTED.
494 *
495 * @param stream reference provided by AAudioStreamBuilder_openStream()
496 * @return AAUDIO_OK or a negative error.
497 */
498AAUDIO_API aaudio_result_t  AAudioStream_requestStart(AAudioStream* stream);
499
500/**
501 * Asynchronous request for the stream to pause.
502 * Pausing a stream will freeze the data flow but not flush any buffers.
503 * Use AAudioStream_Start() to resume playback after a pause.
504 * After this call the state will be in AAUDIO_STREAM_STATE_PAUSING or AAUDIO_STREAM_STATE_PAUSED.
505 *
506 * This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams.
507 * For input streams use AAudioStream_requestStop().
508 *
509 * @param stream reference provided by AAudioStreamBuilder_openStream()
510 * @return AAUDIO_OK or a negative error.
511 */
512AAUDIO_API aaudio_result_t  AAudioStream_requestPause(AAudioStream* stream);
513
514/**
515 * Asynchronous request for the stream to flush.
516 * Flushing will discard any pending data.
517 * This call only works if the stream is pausing or paused. TODO review
518 * Frame counters are not reset by a flush. They may be advanced.
519 * After this call the state will be in AAUDIO_STREAM_STATE_FLUSHING or AAUDIO_STREAM_STATE_FLUSHED.
520 *
521 * This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams.
522 *
523 * @param stream reference provided by AAudioStreamBuilder_openStream()
524 * @return AAUDIO_OK or a negative error.
525 */
526AAUDIO_API aaudio_result_t  AAudioStream_requestFlush(AAudioStream* stream);
527
528/**
529 * Asynchronous request for the stream to stop.
530 * The stream will stop after all of the data currently buffered has been played.
531 * After this call the state will be in AAUDIO_STREAM_STATE_STOPPING or AAUDIO_STREAM_STATE_STOPPED.
532 *
533 * @param stream reference provided by AAudioStreamBuilder_openStream()
534 * @return AAUDIO_OK or a negative error.
535 */
536AAUDIO_API aaudio_result_t  AAudioStream_requestStop(AAudioStream* stream);
537
538/**
539 * Query the current state of the client, eg. AAUDIO_STREAM_STATE_PAUSING
540 *
541 * This function will immediately return the state without updating the state.
542 * If you want to update the client state based on the server state then
543 * call AAudioStream_waitForStateChange() with currentState
544 * set to AAUDIO_STREAM_STATE_UNKNOWN and a zero timeout.
545 *
546 * @param stream reference provided by AAudioStreamBuilder_openStream()
547 */
548AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream);
549
550/**
551 * Wait until the current state no longer matches the input state.
552 *
553 * This will update the current client state.
554 *
555 * <pre><code>
556 * aaudio_stream_state_t currentState;
557 * aaudio_result_t result = AAudioStream_getState(stream, &currentState);
558 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSING) {
559 *     result = AAudioStream_waitForStateChange(
560 *                                   stream, currentState, &currentState, MY_TIMEOUT_NANOS);
561 * }
562 * </code></pre>
563 *
564 * @param stream A reference provided by AAudioStreamBuilder_openStream()
565 * @param inputState The state we want to avoid.
566 * @param nextState Pointer to a variable that will be set to the new state.
567 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
568 * @return AAUDIO_OK or a negative error.
569 */
570AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream,
571                                            aaudio_stream_state_t inputState,
572                                            aaudio_stream_state_t *nextState,
573                                            int64_t timeoutNanoseconds);
574
575// ============================================================
576// Stream I/O
577// ============================================================
578
579/**
580 * Read data from the stream.
581 *
582 * The call will wait until the read is complete or until it runs out of time.
583 * If timeoutNanos is zero then this call will not wait.
584 *
585 * Note that timeoutNanoseconds is a relative duration in wall clock time.
586 * Time will not stop if the thread is asleep.
587 * So it will be implemented using CLOCK_BOOTTIME.
588 *
589 * This call is "strong non-blocking" unless it has to wait for data.
590 *
591 * @param stream A stream created using AAudioStreamBuilder_openStream().
592 * @param buffer The address of the first sample.
593 * @param numFrames Number of frames to read. Only complete frames will be written.
594 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
595 * @return The number of frames actually read or a negative error.
596 */
597AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream,
598                               void *buffer,
599                               int32_t numFrames,
600                               int64_t timeoutNanoseconds);
601
602/**
603 * Write data to the stream.
604 *
605 * The call will wait until the write is complete or until it runs out of time.
606 * If timeoutNanos is zero then this call will not wait.
607 *
608 * Note that timeoutNanoseconds is a relative duration in wall clock time.
609 * Time will not stop if the thread is asleep.
610 * So it will be implemented using CLOCK_BOOTTIME.
611 *
612 * This call is "strong non-blocking" unless it has to wait for room in the buffer.
613 *
614 * @param stream A stream created using AAudioStreamBuilder_openStream().
615 * @param buffer The address of the first sample.
616 * @param numFrames Number of frames to write. Only complete frames will be written.
617 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion.
618 * @return The number of frames actually written or a negative error.
619 */
620AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream,
621                               const void *buffer,
622                               int32_t numFrames,
623                               int64_t timeoutNanoseconds);
624
625// ============================================================
626// Stream - queries
627// ============================================================
628
629/**
630 * This can be used to adjust the latency of the buffer by changing
631 * the threshold where blocking will occur.
632 * By combining this with AAudioStream_getXRunCount(), the latency can be tuned
633 * at run-time for each device.
634 *
635 * This cannot be set higher than AAudioStream_getBufferCapacityInFrames().
636 *
637 * Note that you will probably not get the exact size you request.
638 * Call AAudioStream_getBufferSizeInFrames() to see what the actual final size is.
639 *
640 * @param stream reference provided by AAudioStreamBuilder_openStream()
641 * @param numFrames requested number of frames that can be filled without blocking
642 * @return actual buffer size in frames or a negative error
643 */
644AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream,
645                                                      int32_t numFrames);
646
647/**
648 * Query the maximum number of frames that can be filled without blocking.
649 *
650 * @param stream reference provided by AAudioStreamBuilder_openStream()
651 * @return buffer size in frames.
652 */
653AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream);
654
655/**
656 * Query the number of frames that the application should read or write at
657 * one time for optimal performance. It is OK if an application writes
658 * a different number of frames. But the buffer size may need to be larger
659 * in order to avoid underruns or overruns.
660 *
661 * Note that this may or may not match the actual device burst size.
662 * For some endpoints, the burst size can vary dynamically.
663 * But these tend to be devices with high latency.
664 *
665 * @param stream reference provided by AAudioStreamBuilder_openStream()
666 * @return burst size
667 */
668AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream);
669
670/**
671 * Query maximum buffer capacity in frames.
672 *
673 * @param stream reference provided by AAudioStreamBuilder_openStream()
674 * @return  buffer capacity in frames
675 */
676AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream);
677
678/**
679 * Query the size of the buffer that will be passed to the dataProc callback
680 * in the numFrames parameter.
681 *
682 * This call can be used if the application needs to know the value of numFrames before
683 * the stream is started. This is not normally necessary.
684 *
685 * If a specific size was requested by calling AAudioStreamBuilder_setCallbackSizeInFrames()
686 * then this will be the same size.
687 *
688 * If AAudioStreamBuilder_setCallbackSizeInFrames() was not called then this will
689 * return the size chosen by AAudio, or AAUDIO_UNSPECIFIED.
690 *
691 * AAUDIO_UNSPECIFIED indicates that the callback buffer size for this stream
692 * may vary from one dataProc callback to the next.
693 *
694 * @param stream reference provided by AAudioStreamBuilder_openStream()
695 * @return callback buffer size in frames or AAUDIO_UNSPECIFIED
696 */
697AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream);
698
699/**
700 * An XRun is an Underrun or an Overrun.
701 * During playing, an underrun will occur if the stream is not written in time
702 * and the system runs out of valid data.
703 * During recording, an overrun will occur if the stream is not read in time
704 * and there is no place to put the incoming data so it is discarded.
705 *
706 * An underrun or overrun can cause an audible "pop" or "glitch".
707 *
708 * Note that some INPUT devices may not support this function.
709 * In that case a 0 will always be returned.
710 *
711 * @param stream reference provided by AAudioStreamBuilder_openStream()
712 * @return the underrun or overrun count
713 */
714AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream);
715
716/**
717 * @param stream reference provided by AAudioStreamBuilder_openStream()
718 * @return actual sample rate
719 */
720AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream);
721
722/**
723 * A stream has one or more channels of data.
724 * A frame will contain one sample for each channel.
725 *
726 * @param stream reference provided by AAudioStreamBuilder_openStream()
727 * @return actual number of channels
728 */
729AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* stream);
730
731/**
732 * The samplesPerFrame is also known as channelCount.
733 *
734 * @deprecated use AAudioStream_getChannelCount()
735 * @param stream reference provided by AAudioStreamBuilder_openStream()
736 * @return actual samples per frame
737 */
738AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream);
739
740/**
741 * @param stream reference provided by AAudioStreamBuilder_openStream()
742 * @return actual device ID
743 */
744AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream);
745
746/**
747 * @param stream reference provided by AAudioStreamBuilder_openStream()
748 * @return actual data format
749 */
750AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* stream);
751
752/**
753 * Provide actual sharing mode.
754 * @param stream reference provided by AAudioStreamBuilder_openStream()
755 * @return  actual sharing mode
756 */
757AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream);
758
759/**
760 * Get the performance mode used by the stream.
761 *
762 * @param stream reference provided by AAudioStreamBuilder_openStream()
763 */
764AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* stream);
765
766/**
767 * @param stream reference provided by AAudioStreamBuilder_openStream()
768 * @return direction
769 */
770AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream);
771
772/**
773 * Passes back the number of frames that have been written since the stream was created.
774 * For an output stream, this will be advanced by the application calling write().
775 * For an input stream, this will be advanced by the endpoint.
776 *
777 * The frame position is monotonically increasing.
778 *
779 * @param stream reference provided by AAudioStreamBuilder_openStream()
780 * @return frames written
781 */
782AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream);
783
784/**
785 * Passes back the number of frames that have been read since the stream was created.
786 * For an output stream, this will be advanced by the endpoint.
787 * For an input stream, this will be advanced by the application calling read().
788 *
789 * The frame position is monotonically increasing.
790 *
791 * @param stream reference provided by AAudioStreamBuilder_openStream()
792 * @return frames read
793 */
794AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream);
795
796/**
797 * Passes back the time at which a particular frame was presented.
798 * This can be used to synchronize audio with video or MIDI.
799 * It can also be used to align a recorded stream with a playback stream.
800 *
801 * Timestamps are only valid when the stream is in AAUDIO_STREAM_STATE_STARTED.
802 * AAUDIO_ERROR_INVALID_STATE will be returned if the stream is not started.
803 * Note that because requestStart() is asynchronous, timestamps will not be valid until
804 * a short time after calling requestStart().
805 * So AAUDIO_ERROR_INVALID_STATE should not be considered a fatal error.
806 * Just try calling again later.
807 *
808 * If an error occurs, then the position and time will not be modified.
809 *
810 * The position and time passed back are monotonically increasing.
811 *
812 * @param stream reference provided by AAudioStreamBuilder_openStream()
813 * @param clockid AAUDIO_CLOCK_MONOTONIC or AAUDIO_CLOCK_BOOTTIME
814 * @param framePosition pointer to a variable to receive the position
815 * @param timeNanoseconds pointer to a variable to receive the time
816 * @return AAUDIO_OK or a negative error
817 */
818AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream,
819                                      clockid_t clockid,
820                                      int64_t *framePosition,
821                                      int64_t *timeNanoseconds);
822
823#ifdef __cplusplus
824}
825#endif
826
827#endif //AAUDIO_AAUDIO_H
828
829/** @} */
830