AAudio.h revision 068c10f03d16a7f73abf138cc751cf3bde7518df
15ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/* 25ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Copyright (C) 2016 The Android Open Source Project 35ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 45ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Licensed under the Apache License, Version 2.0 (the "License"); 55ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * you may not use this file except in compliance with the License. 65ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * You may obtain a copy of the License at 75ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 85ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * http://www.apache.org/licenses/LICENSE-2.0 95ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 105ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Unless required by applicable law or agreed to in writing, software 115ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * distributed under the License is distributed on an "AS IS" BASIS, 125ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 135ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * See the License for the specific language governing permissions and 145ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * limitations under the License. 155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 165ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 175ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 18a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk * @addtogroup Audio 19a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk * @{ 20a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk */ 21a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk 22a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk/** 23a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk * @file AAudio.h 24a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk */ 25a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk 26a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk/** 27a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk * This is the 'C' API for AAudio. 285ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 295ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#ifndef AAUDIO_AAUDIO_H 305ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#define AAUDIO_AAUDIO_H 315ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 323316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk#include <time.h> 335ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 345ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#ifdef __cplusplus 355ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burkextern "C" { 365ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#endif 375ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 38a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk/** 39a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * This is used to represent a value that has not been specified. 40a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * For example, an application could use AAUDIO_UNSPECIFIED to indicate 41a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * that is did not not care what the specific value of a parameter was 42a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * and would accept whatever it was given. 43a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk */ 44a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk#define AAUDIO_UNSPECIFIED 0 45a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk#define AAUDIO_DEVICE_UNSPECIFIED 0 46a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 47a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum { 48a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_DIRECTION_OUTPUT, 49a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_DIRECTION_INPUT 50a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 51a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_direction_t; 52a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 53a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum { 54a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_FORMAT_INVALID = -1, 55a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_FORMAT_UNSPECIFIED = 0, 56a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_FORMAT_PCM_I16, 577473345009b12576d8a768c93cc29a6b404eafd8Phil Burk AAUDIO_FORMAT_PCM_FLOAT 58a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 59a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_format_t; 60a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 61a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk/** 62a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * @deprecated use aaudio_format_t instead 63a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * TODO remove when tests and examples are updated 64a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk */ 65a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_audio_format_t; 66a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 67a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum { 68a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_OK, 69a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_BASE = -900, // TODO review 70a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_DISCONNECTED, 71a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_ILLEGAL_ARGUMENT, 72a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INCOMPATIBLE, 73a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INTERNAL, // an underlying API returned an error code 74a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INVALID_STATE, 75a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_UNEXPECTED_STATE, 76a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_UNEXPECTED_VALUE, 77a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INVALID_HANDLE, 78a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INVALID_QUERY, 79a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_UNIMPLEMENTED, 80a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_UNAVAILABLE, 81a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_NO_FREE_HANDLES, 82a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_NO_MEMORY, 83a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_NULL, 84a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_TIMEOUT, 85a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_WOULD_BLOCK, 86a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INVALID_FORMAT, 87a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_OUT_OF_RANGE, 88a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_NO_SERVICE, 89a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INVALID_RATE 90a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 91a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_result_t; 92a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 93a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum 94a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk{ 95a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_UNINITIALIZED = 0, 96a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_UNKNOWN, 97a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_OPEN, 98a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_STARTING, 99a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_STARTED, 100a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_PAUSING, 101a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_PAUSED, 102a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_FLUSHING, 103a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_FLUSHED, 104a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_STOPPING, 105a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_STOPPED, 106a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_CLOSING, 107a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_CLOSED, 108a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_DISCONNECTED 109a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 110a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_stream_state_t; 111a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 112a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 113a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum { 114a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk /** 115a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * This will be the only stream using a particular source or sink. 116a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * This mode will provide the lowest possible latency. 117a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * You should close EXCLUSIVE streams immediately when you are not using them. 118a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk */ 119a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_SHARING_MODE_EXCLUSIVE, 120a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk /** 121a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * Multiple applications will be mixed by the AAudio Server. 122a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * This will have higher latency than the EXCLUSIVE mode. 123a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk */ 124a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_SHARING_MODE_SHARED 125a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 126a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_sharing_mode_t; 127a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 128e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 129e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burkenum { 130e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk /** 131e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * No particular performance needs. Default. 132e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 133e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk AAUDIO_PERFORMANCE_MODE_NONE = 10, 134e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 135e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk /** 136e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * Extending battery life is most important. 137e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 138e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk AAUDIO_PERFORMANCE_MODE_POWER_SAVING, 139e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 140e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk /** 141e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * Reducing latency is most important. 142e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 143e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 144e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk}; 145e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burktypedef int32_t aaudio_performance_mode_t; 146e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 147e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil Burktypedef struct AAudioStreamStruct AAudioStream; 148e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil Burktypedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; 1495ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1505ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#ifndef AAUDIO_API 1513316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk#define AAUDIO_API /* export this symbol */ 1525ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#endif 1535ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1545ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 1555ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// Audio System 1565ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 1575ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1585ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 1595ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The text is the ASCII symbol corresponding to the returnCode, 1605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * or an English message saying the returnCode is unrecognized. 1615ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This is intended for developers to use when debugging. 1625ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * It is not for display to users. 1635ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1645ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return pointer to a text representation of an AAudio result code. 1655ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 1665ed503c7a66c90f93759c90237a9b432dbd93f9fPhil BurkAAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode); 1675ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1685ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 1695ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The text is the ASCII symbol corresponding to the stream state, 1705ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * or an English message saying the state is unrecognized. 1715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This is intended for developers to use when debugging. 1725ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * It is not for display to users. 1735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1745ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return pointer to a text representation of an AAudio state. 1755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 1765ed503c7a66c90f93759c90237a9b432dbd93f9fPhil BurkAAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state); 1775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 1795ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// StreamBuilder 1805ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 1815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 1835ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Create a StreamBuilder that can be used to open a Stream. 1845ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The deviceId is initially unspecified, meaning that the current default device will be used. 1865ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1875ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The default direction is AAUDIO_DIRECTION_OUTPUT. 1883316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * The default sharing mode is AAUDIO_SHARING_MODE_SHARED. 1895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The data format, samplesPerFrames and sampleRate are unspecified and will be 1905ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * chosen by the device when it is opened. 1915ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1925ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * AAudioStreamBuilder_delete() must be called when you are done using the builder. 1935ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 194e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder); 1955ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1965ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 1975ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Request an audio device identified device using an ID. 1985ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * On Android, for example, the ID could be obtained from the Java AudioManager. 1995ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 200e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_DEVICE_UNSPECIFIED, 201e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * in which case the primary device will be used. 2025ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 2033316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 2043316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param deviceId device identifier or AAUDIO_DEVICE_UNSPECIFIED 2055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 206e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, 2073316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int32_t deviceId); 2085ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2095ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 210e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Request a sample rate in Hertz. 211e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 2125ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The stream may be opened with a different sample rate. 2135ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * So the application should query for the actual rate after the stream is opened. 2145ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 2155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Technically, this should be called the "frame rate" or "frames per second", 2165ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * because it refers to the number of complete frames transferred per second. 217e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * But it is traditionally called "sample rate". So we use that term. 2185ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 219e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 220e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 221e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 222e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz. 2235ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 224e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, 2253316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int32_t sampleRate); 2265ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2275ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 22820523edbf2f597c53b90e76694331c807e559515Phil Burk * Request a number of channels for the stream. 229e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 2305ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The stream may be opened with a different value. 2315ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * So the application should query for the actual value after the stream is opened. 2325ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 233e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 2345ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 23520523edbf2f597c53b90e76694331c807e559515Phil Burk * Note, this quantity is sometimes referred to as "samples per frame". 236e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 237e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 23820523edbf2f597c53b90e76694331c807e559515Phil Burk * @param channelCount Number of channels desired. 2395ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 24020523edbf2f597c53b90e76694331c807e559515Phil BurkAAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* builder, 24120523edbf2f597c53b90e76694331c807e559515Phil Burk int32_t channelCount); 24220523edbf2f597c53b90e76694331c807e559515Phil Burk 24320523edbf2f597c53b90e76694331c807e559515Phil Burk/** 24420523edbf2f597c53b90e76694331c807e559515Phil Burk * 24520523edbf2f597c53b90e76694331c807e559515Phil Burk * @deprecated use AAudioStreamBuilder_setChannelCount() 24620523edbf2f597c53b90e76694331c807e559515Phil Burk */ 24720523edbf2f597c53b90e76694331c807e559515Phil Burk// TODO remove as soon as the NDK and OS are in sync, before RC1 248e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder, 24920523edbf2f597c53b90e76694331c807e559515Phil Burk int32_t samplesPerFrame); 2505ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2515ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 2525ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16. 253e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 254e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 255e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 256e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The stream may be opened with a different value. 257e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * So the application should query for the actual value after the stream is opened. 258e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 259e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 260e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param format Most common formats are AAUDIO_FORMAT_PCM_FLOAT and AAUDIO_FORMAT_PCM_I16. 2615ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 262e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder, 2635ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk aaudio_audio_format_t format); 2645ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2655ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 2665ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Request a mode for sharing the device. 267e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 268e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_SHARING_MODE_SHARED. 269e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 2705ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The requested sharing mode may not be available. 271e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The application can query for the actual mode after the stream is opened. 2725ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 2733316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 274e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param sharingMode AAUDIO_SHARING_MODE_SHARED or AAUDIO_SHARING_MODE_EXCLUSIVE 2755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 276e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder, 2775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk aaudio_sharing_mode_t sharingMode); 2785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2795ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 280e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Request the direction for a stream. 281e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 282e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_DIRECTION_OUTPUT. 2835ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 2843316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 2855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param direction AAUDIO_DIRECTION_OUTPUT or AAUDIO_DIRECTION_INPUT 2865ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 287e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder, 2883df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk aaudio_direction_t direction); 2895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2905ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 291e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Set the requested buffer capacity in frames. 2923df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk * The final AAudioStream capacity may differ, but will probably be at least this big. 2933df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk * 294e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 2953df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk * 2963316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 297e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param numFrames the desired buffer capacity in frames or AAUDIO_UNSPECIFIED 2983df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk */ 299e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder, 300e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk int32_t numFrames); 301e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 302e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk/** 303e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * Set the requested performance mode. 304e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * 305e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * The default, if you do not call this function, is AAUDIO_PERFORMANCE_MODE_NONE. 306e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * 307e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 308e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * @param mode the desired performance mode, eg. AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 309e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 310e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil BurkAAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* builder, 311e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk aaudio_performance_mode_t mode); 312e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 313e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 314e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Return one of these values from the data callback function. 315e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 316e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burkenum { 317e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 318e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk /** 319e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Continue calling the callback. 320e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 321e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAUDIO_CALLBACK_RESULT_CONTINUE = 0, 322e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 323e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk /** 324e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Stop calling the callback. 325e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 326e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The application will still need to call AAudioStream_requestPause() 327e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * or AAudioStream_requestStop(). 328e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 329e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAUDIO_CALLBACK_RESULT_STOP, 330e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 331e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk}; 332e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burktypedef int32_t aaudio_data_callback_result_t; 333e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 334e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 335e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback(). 336e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 337e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * For an output stream, this function should render and write numFrames of data 338e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * in the streams current data format to the audioData buffer. 339e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 340e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * For an input stream, this function should read and process numFrames of data 341e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * from the audioData buffer. 342e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 343e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Note that this callback function should be considered a "real-time" function. 344e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * It must not do anything that could cause an unbounded delay because that can cause the 345e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * audio to glitch or pop. 346e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 347e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * These are things the function should NOT do: 348e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <ul> 349e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>allocate memory using, for example, malloc() or new</li> 350e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>any file operations such as opening, closing, reading or writing</li> 351e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>any network operations such as streaming</li> 352e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>use any mutexes or other synchronization primitives</li> 353e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>sleep</li> 354e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * </ul> 355e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 356e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * If you need to move data, eg. MIDI commands, in or out of the callback function then 357e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * we recommend the use of non-blocking techniques such as an atomic FIFO. 358e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 359e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 360e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param userData the same address that was passed to AAudioStreamBuilder_setCallback() 361e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param audioData a pointer to the audio data 362e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param numFrames the number of frames to be processed 363e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @return AAUDIO_CALLBACK_RESULT_* 364e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 365e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burktypedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( 366e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAudioStream *stream, 367e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *userData, 368e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *audioData, 369e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk int32_t numFrames); 370e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 371e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 372e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Request that AAudio call this functions when the stream is running. 373e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 374e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Note that when using this callback, the audio data will be passed in or out 375e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * of the function as an argument. 376e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * So you cannot call AAudioStream_write() or AAudioStream_read() on the same stream 377e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * that has an active data callback. 378e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 379e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The callback function will start being called after AAudioStream_requestStart() is called. 380e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * It will stop being called after AAudioStream_requestPause() or 381e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * AAudioStream_requestStop() is called. 382e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 383e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * This callback function will be called on a real-time thread owned by AAudio. See 3840d804369941be2adddea3b4bdfff7f2d6d9e361cGlenn Kasten * {@link AAudioStream_dataCallback} for more information. 385e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 386e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 387e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 388e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 389e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param callback pointer to a function that will process audio data. 390e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param userData pointer to an application data structure that will be passed 391e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * to the callback functions. 392e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 393e057ca91a9b96665d430ac89f1b38a36621f83bdPhil BurkAAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder, 394e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAudioStream_dataCallback callback, 395e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *userData); 396e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 397e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 398e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Set the requested data callback buffer size in frames. 399e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * See {@link AAudioStream_dataCallback}. 400e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 401e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 402e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 403e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * For the lowest possible latency, do not call this function. AAudio will then 404e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * call the dataProc callback function with whatever size is optimal. 405e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * That size may vary from one callback to another. 406e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 407e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Only use this function if the application requires a specific number of frames for processing. 408e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The application might, for example, be using an FFT that requires 409e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * a specific power-of-two sized buffer. 410e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 411e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * AAudio may need to add additional buffering in order to adapt between the internal 412e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * buffer size and the requested buffer size. 413e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 414e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * If you do call this function then the requested size should be less than 415e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * half the buffer capacity, to allow double buffering. 416e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 417e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 418e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param numFrames the desired buffer size in frames or AAUDIO_UNSPECIFIED 419e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 420e057ca91a9b96665d430ac89f1b38a36621f83bdPhil BurkAAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* builder, 421e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk int32_t numFrames); 422e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 423e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 424e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Prototype for the callback function that is passed to 425e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * AAudioStreamBuilder_setErrorCallback(). 426e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 427e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 428e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback() 429e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param error an AAUDIO_ERROR_* value. 430e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 431e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burktypedef void (*AAudioStream_errorCallback)( 432e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAudioStream *stream, 433e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *userData, 434e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk aaudio_result_t error); 435e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 436e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 437e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Request that AAudio call this functions if any error occurs on a callback thread. 438e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 439e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * It will be called, for example, if a headset or a USB device is unplugged causing the stream's 440e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * device to be unavailable. 441e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * In response, this function could signal or launch another thread to reopen a 442e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * stream on another device. Do not reopen the stream in this callback. 443e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 444e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * This will not be called because of actions by the application, such as stopping 445e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * or closing a stream. 446e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 447e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Another possible cause of error would be a timeout or an unanticipated internal error. 448e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 449e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 450e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 451e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 452e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param callback pointer to a function that will be called if an error occurs. 453e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param userData pointer to an application data structure that will be passed 454e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * to the callback functions. 455e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 456e057ca91a9b96665d430ac89f1b38a36621f83bdPhil BurkAAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builder, 457e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAudioStream_errorCallback callback, 458e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *userData); 4595ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 4615ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Open a stream based on the options in the StreamBuilder. 4625ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4635ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * AAudioStream_close must be called when finished with the stream to recover 4645ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * the memory and to free the associated resources. 4655ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4663316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 4673316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream pointer to a variable to receive the new stream reference 4685ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 4695ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 470e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder, 471e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil Burk AAudioStream** stream); 4725ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 4745ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Delete the resources associated with the StreamBuilder. 4755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4763316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 4775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 4785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 479e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* builder); 4805ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 4825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// Stream Control 4835ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 4845ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 4865ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Free the resources associated with a stream created by AAudioStreamBuilder_openStream() 4875ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4883316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 4895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 4905ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 491e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream); 4925ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4935ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 4945ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Asynchronously request to start playing the stream. For output streams, one should 4955ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * write to the stream to fill the buffer before starting. 4965ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Otherwise it will underflow. 4975ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * After this call the state will be in AAUDIO_STREAM_STATE_STARTING or AAUDIO_STREAM_STATE_STARTED. 4985ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4993316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5005ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5015ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 502e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream); 5035ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5045ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Asynchronous request for the stream to pause. 5065ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Pausing a stream will freeze the data flow but not flush any buffers. 5075ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Use AAudioStream_Start() to resume playback after a pause. 5085ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * After this call the state will be in AAUDIO_STREAM_STATE_PAUSING or AAUDIO_STREAM_STATE_PAUSED. 5095ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 510068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams. 511068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * For input streams use AAudioStream_requestStop(). 512068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * 5133316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5145ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 516e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream); 5175ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5185ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5195ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Asynchronous request for the stream to flush. 5205ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Flushing will discard any pending data. 5215ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This call only works if the stream is pausing or paused. TODO review 5225ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Frame counters are not reset by a flush. They may be advanced. 5235ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * After this call the state will be in AAUDIO_STREAM_STATE_FLUSHING or AAUDIO_STREAM_STATE_FLUSHED. 5245ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 525068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams. 526068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * 5273316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5285ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5295ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 530e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream); 5315ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5325ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5335ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Asynchronous request for the stream to stop. 5345ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The stream will stop after all of the data currently buffered has been played. 5355ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * After this call the state will be in AAUDIO_STREAM_STATE_STOPPING or AAUDIO_STREAM_STATE_STOPPED. 5365ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5373316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5385ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5395ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 540e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream); 5415ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5425ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5433316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Query the current state of the client, eg. AAUDIO_STREAM_STATE_PAUSING 5445ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5453316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * This function will immediately return the state without updating the state. 5463316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * If you want to update the client state based on the server state then 5473316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * call AAudioStream_waitForStateChange() with currentState 5483316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * set to AAUDIO_STREAM_STATE_UNKNOWN and a zero timeout. 5493316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * 5503316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5515ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 552e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream); 5535ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5545ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5555ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Wait until the current state no longer matches the input state. 5565ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5573316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * This will update the current client state. 5583316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * 5595ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * <pre><code> 5605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * aaudio_stream_state_t currentState; 5615ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * aaudio_result_t result = AAudioStream_getState(stream, ¤tState); 5625ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSING) { 5635ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * result = AAudioStream_waitForStateChange( 5645ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * stream, currentState, ¤tState, MY_TIMEOUT_NANOS); 5655ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * } 5665ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * </code></pre> 5675ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5683316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream A reference provided by AAudioStreamBuilder_openStream() 5695ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param inputState The state we want to avoid. 5705ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param nextState Pointer to a variable that will be set to the new state. 5715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 5725ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 574e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream, 5755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk aaudio_stream_state_t inputState, 5765ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk aaudio_stream_state_t *nextState, 5773316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t timeoutNanoseconds); 5785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5795ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 5805ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// Stream I/O 5815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 5825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5835ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5845ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Read data from the stream. 5855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5865ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The call will wait until the read is complete or until it runs out of time. 5875ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * If timeoutNanos is zero then this call will not wait. 5885ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Note that timeoutNanoseconds is a relative duration in wall clock time. 5905ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Time will not stop if the thread is asleep. 5915ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * So it will be implemented using CLOCK_BOOTTIME. 5925ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5935ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This call is "strong non-blocking" unless it has to wait for data. 5945ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5955ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param stream A stream created using AAudioStreamBuilder_openStream(). 5965ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param buffer The address of the first sample. 5975ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param numFrames Number of frames to read. Only complete frames will be written. 5985ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 5993316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return The number of frames actually read or a negative error. 6005ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 601e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream, 6025ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk void *buffer, 6033316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int32_t numFrames, 6043316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t timeoutNanoseconds); 6055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6065ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6075ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Write data to the stream. 6085ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6095ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The call will wait until the write is complete or until it runs out of time. 6105ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * If timeoutNanos is zero then this call will not wait. 6115ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6125ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Note that timeoutNanoseconds is a relative duration in wall clock time. 6135ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Time will not stop if the thread is asleep. 6145ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * So it will be implemented using CLOCK_BOOTTIME. 6155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6165ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This call is "strong non-blocking" unless it has to wait for room in the buffer. 6175ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6185ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param stream A stream created using AAudioStreamBuilder_openStream(). 6195ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param buffer The address of the first sample. 6205ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param numFrames Number of frames to write. Only complete frames will be written. 6215ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 6225ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return The number of frames actually written or a negative error. 6235ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 624e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream, 6255ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk const void *buffer, 6263316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int32_t numFrames, 6273316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t timeoutNanoseconds); 6285ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6295ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 6305ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// Stream - queries 6315ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 6325ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6335ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6345ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This can be used to adjust the latency of the buffer by changing 6355ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * the threshold where blocking will occur. 6363316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * By combining this with AAudioStream_getXRunCount(), the latency can be tuned 6375ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * at run-time for each device. 6385ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6393316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * This cannot be set higher than AAudioStream_getBufferCapacityInFrames(). 6403316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * 6413316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Note that you will probably not get the exact size you request. 6423316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Call AAudioStream_getBufferSizeInFrames() to see what the actual final size is. 6435ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6443316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 645e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param numFrames requested number of frames that can be filled without blocking 6463316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual buffer size in frames or a negative error 6475ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 648e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream, 649e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk int32_t numFrames); 6505ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6515ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6525ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Query the maximum number of frames that can be filled without blocking. 6535ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6543316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 6553316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return buffer size in frames. 6565ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 657e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream); 6585ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6595ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6603316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Query the number of frames that the application should read or write at 6613316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * one time for optimal performance. It is OK if an application writes 6623316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * a different number of frames. But the buffer size may need to be larger 6633316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * in order to avoid underruns or overruns. 6645ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6653316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Note that this may or may not match the actual device burst size. 6663316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * For some endpoints, the burst size can vary dynamically. 6673316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * But these tend to be devices with high latency. 6683316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * 6693316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 6703316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return burst size 6715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 672e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream); 6735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6745ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Query maximum buffer capacity in frames. 6765ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6773316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 678e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @return buffer capacity in frames 6795ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 680e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream); 6815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 683e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Query the size of the buffer that will be passed to the dataProc callback 684e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * in the numFrames parameter. 685e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 686e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * This call can be used if the application needs to know the value of numFrames before 687e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * the stream is started. This is not normally necessary. 688e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 689e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * If a specific size was requested by calling AAudioStreamBuilder_setCallbackSizeInFrames() 690e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * then this will be the same size. 691e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 692e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * If AAudioStreamBuilder_setCallbackSizeInFrames() was not called then this will 693e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * return the size chosen by AAudio, or AAUDIO_UNSPECIFIED. 694e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 695e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * AAUDIO_UNSPECIFIED indicates that the callback buffer size for this stream 696e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * may vary from one dataProc callback to the next. 697e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 698e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 699e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @return callback buffer size in frames or AAUDIO_UNSPECIFIED 700e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 701e057ca91a9b96665d430ac89f1b38a36621f83bdPhil BurkAAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream); 702e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 703e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 7045ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * An XRun is an Underrun or an Overrun. 7055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * During playing, an underrun will occur if the stream is not written in time 7065ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * and the system runs out of valid data. 7075ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * During recording, an overrun will occur if the stream is not read in time 7085ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * and there is no place to put the incoming data so it is discarded. 7095ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7105ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * An underrun or overrun can cause an audible "pop" or "glitch". 7115ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 712068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * Note that some INPUT devices may not support this function. 713068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * In that case a 0 will always be returned. 714068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * 7153316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7163316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return the underrun or overrun count 7175ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 718e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream); 7195ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7205ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7213316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7223316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual sample rate 7235ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 724e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream); 7255ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7265ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 72720523edbf2f597c53b90e76694331c807e559515Phil Burk * A stream has one or more channels of data. 72820523edbf2f597c53b90e76694331c807e559515Phil Burk * A frame will contain one sample for each channel. 72920523edbf2f597c53b90e76694331c807e559515Phil Burk * 73020523edbf2f597c53b90e76694331c807e559515Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 73120523edbf2f597c53b90e76694331c807e559515Phil Burk * @return actual number of channels 73220523edbf2f597c53b90e76694331c807e559515Phil Burk */ 73320523edbf2f597c53b90e76694331c807e559515Phil BurkAAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* stream); 73420523edbf2f597c53b90e76694331c807e559515Phil Burk 73520523edbf2f597c53b90e76694331c807e559515Phil Burk/** 7365ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The samplesPerFrame is also known as channelCount. 7375ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 73820523edbf2f597c53b90e76694331c807e559515Phil Burk * @deprecated use AAudioStream_getChannelCount() 7393316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7403316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual samples per frame 7415ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 742e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream); 7435ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7445ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7453316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 746e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil Burk * @return actual device ID 7475ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 748e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream); 7495ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7505ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7513316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7523316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual data format 7535ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 754e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_audio_format_t AAudioStream_getFormat(AAudioStream* stream); 7555ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7565ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7575ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Provide actual sharing mode. 7583316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7593316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual sharing mode 7605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 761e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream); 7625ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7635ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 764e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * Get the performance mode used by the stream. 765e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * 766e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 767e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 768e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil BurkAAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* stream); 769e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 770e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk/** 7713316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7723316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return direction 7735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 774e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream); 7755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7765ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Passes back the number of frames that have been written since the stream was created. 7785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * For an output stream, this will be advanced by the application calling write(). 7793316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * For an input stream, this will be advanced by the endpoint. 7805ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The frame position is monotonically increasing. 7825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7833316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7843316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return frames written 7855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 786e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream); 7875ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7885ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Passes back the number of frames that have been read since the stream was created. 7903316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * For an output stream, this will be advanced by the endpoint. 7915ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * For an input stream, this will be advanced by the application calling read(). 7925ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7935ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The frame position is monotonically increasing. 7945ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7953316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7963316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return frames read 7975ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 798e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream); 7995ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 8005ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 8015ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Passes back the time at which a particular frame was presented. 8025ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This can be used to synchronize audio with video or MIDI. 8035ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * It can also be used to align a recorded stream with a playback stream. 8045ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 8055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Timestamps are only valid when the stream is in AAUDIO_STREAM_STATE_STARTED. 8065ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * AAUDIO_ERROR_INVALID_STATE will be returned if the stream is not started. 8075ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Note that because requestStart() is asynchronous, timestamps will not be valid until 8085ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * a short time after calling requestStart(). 8095ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * So AAUDIO_ERROR_INVALID_STATE should not be considered a fatal error. 8105ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Just try calling again later. 8115ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 8125ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * If an error occurs, then the position and time will not be modified. 8135ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 8145ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The position and time passed back are monotonically increasing. 8155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 8163316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 8175ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param clockid AAUDIO_CLOCK_MONOTONIC or AAUDIO_CLOCK_BOOTTIME 8185ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param framePosition pointer to a variable to receive the position 8195ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param timeNanoseconds pointer to a variable to receive the time 8205ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error 8215ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 822e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream, 8233316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk clockid_t clockid, 8243316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t *framePosition, 8253316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t *timeNanoseconds); 8265ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 8275ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#ifdef __cplusplus 8285ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk} 8295ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#endif 8305ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 8315ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#endif //AAUDIO_AAUDIO_H 832a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk 833a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk/** @} */ 834