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 46a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum { 47a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_DIRECTION_OUTPUT, 48a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_DIRECTION_INPUT 49a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 50a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_direction_t; 51a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 52a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum { 53a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_FORMAT_INVALID = -1, 54a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_FORMAT_UNSPECIFIED = 0, 55a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_FORMAT_PCM_I16, 567473345009b12576d8a768c93cc29a6b404eafd8Phil Burk AAUDIO_FORMAT_PCM_FLOAT 57a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 58a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_format_t; 59a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 60a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum { 61a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_OK, 62a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_BASE = -900, // TODO review 63a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_DISCONNECTED, 64a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_ILLEGAL_ARGUMENT, 6517fff38dd9d467bc5fb6cd5b9a6b183951c7750dPhil Burk // reserved 6617fff38dd9d467bc5fb6cd5b9a6b183951c7750dPhil Burk AAUDIO_ERROR_INTERNAL = AAUDIO_ERROR_ILLEGAL_ARGUMENT + 2, 67a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INVALID_STATE, 6817fff38dd9d467bc5fb6cd5b9a6b183951c7750dPhil Burk // reserved 6917fff38dd9d467bc5fb6cd5b9a6b183951c7750dPhil Burk // reserved 7017fff38dd9d467bc5fb6cd5b9a6b183951c7750dPhil Burk AAUDIO_ERROR_INVALID_HANDLE = AAUDIO_ERROR_INVALID_STATE + 3, 7117fff38dd9d467bc5fb6cd5b9a6b183951c7750dPhil Burk // reserved 7217fff38dd9d467bc5fb6cd5b9a6b183951c7750dPhil Burk AAUDIO_ERROR_UNIMPLEMENTED = AAUDIO_ERROR_INVALID_HANDLE + 2, 73a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_UNAVAILABLE, 74a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_NO_FREE_HANDLES, 75a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_NO_MEMORY, 76a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_NULL, 77a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_TIMEOUT, 78a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_WOULD_BLOCK, 79a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INVALID_FORMAT, 80a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_OUT_OF_RANGE, 81a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_NO_SERVICE, 82a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_ERROR_INVALID_RATE 83a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 84a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_result_t; 85a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 86a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum 87a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk{ 88a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_UNINITIALIZED = 0, 89a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_UNKNOWN, 90a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_OPEN, 91a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_STARTING, 92a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_STARTED, 93a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_PAUSING, 94a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_PAUSED, 95a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_FLUSHING, 96a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_FLUSHED, 97a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_STOPPING, 98a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_STOPPED, 99a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_CLOSING, 100a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_CLOSED, 101a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_STREAM_STATE_DISCONNECTED 102a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 103a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_stream_state_t; 104a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 105a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 106a4eb0d86a29be2763be5fac51727858d5095794bPhil Burkenum { 107a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk /** 108a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * This will be the only stream using a particular source or sink. 109a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * This mode will provide the lowest possible latency. 110a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * You should close EXCLUSIVE streams immediately when you are not using them. 111a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk */ 112a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_SHARING_MODE_EXCLUSIVE, 113a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk /** 114a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * Multiple applications will be mixed by the AAudio Server. 115a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk * This will have higher latency than the EXCLUSIVE mode. 116a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk */ 117a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk AAUDIO_SHARING_MODE_SHARED 118a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk}; 119a4eb0d86a29be2763be5fac51727858d5095794bPhil Burktypedef int32_t aaudio_sharing_mode_t; 120a4eb0d86a29be2763be5fac51727858d5095794bPhil Burk 121e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 122e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burkenum { 123e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk /** 124e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * No particular performance needs. Default. 125e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 126e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk AAUDIO_PERFORMANCE_MODE_NONE = 10, 127e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 128e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk /** 129e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * Extending battery life is most important. 130e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 131e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk AAUDIO_PERFORMANCE_MODE_POWER_SAVING, 132e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 133e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk /** 134e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * Reducing latency is most important. 135e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 136e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 137e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk}; 138e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burktypedef int32_t aaudio_performance_mode_t; 139e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 140e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil Burktypedef struct AAudioStreamStruct AAudioStream; 141e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil Burktypedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; 1425ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1435ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#ifndef AAUDIO_API 1443316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk#define AAUDIO_API /* export this symbol */ 1455ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#endif 1465ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1475ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 1485ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// Audio System 1495ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 1505ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1515ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 1525ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The text is the ASCII symbol corresponding to the returnCode, 1535ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * or an English message saying the returnCode is unrecognized. 1545ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This is intended for developers to use when debugging. 1555ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * It is not for display to users. 1565ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1575ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return pointer to a text representation of an AAudio result code. 1585ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 1595ed503c7a66c90f93759c90237a9b432dbd93f9fPhil BurkAAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode); 1605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1615ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 1625ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The text is the ASCII symbol corresponding to the stream state, 1635ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * or an English message saying the state is unrecognized. 1645ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This is intended for developers to use when debugging. 1655ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * It is not for display to users. 1665ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1675ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return pointer to a text representation of an AAudio state. 1685ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 1695ed503c7a66c90f93759c90237a9b432dbd93f9fPhil BurkAAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state); 1705ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 1725ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// StreamBuilder 1735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 1745ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 1765ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Create a StreamBuilder that can be used to open a Stream. 1775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The deviceId is initially unspecified, meaning that the current default device will be used. 1795ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1805ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The default direction is AAUDIO_DIRECTION_OUTPUT. 1813316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * The default sharing mode is AAUDIO_SHARING_MODE_SHARED. 1825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The data format, samplesPerFrames and sampleRate are unspecified and will be 1835ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * chosen by the device when it is opened. 1845ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * AAudioStreamBuilder_delete() must be called when you are done using the builder. 1865ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 187e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder); 1885ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 1895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 1905ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Request an audio device identified device using an ID. 1915ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * On Android, for example, the ID could be obtained from the Java AudioManager. 1925ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1935f510d2e1d9976f45d1d1733f20ec32e56bd2239Glenn Kasten * The default, if you do not call this function, is AAUDIO_UNSPECIFIED, 194e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * in which case the primary device will be used. 1955ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 1963316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 1975f510d2e1d9976f45d1d1733f20ec32e56bd2239Glenn Kasten * @param deviceId device identifier or AAUDIO_UNSPECIFIED 1985ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 199e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, 2003316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int32_t deviceId); 2015ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2025ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 203e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Request a sample rate in Hertz. 204e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 205e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 2068f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * An optimal value will then be chosen when the stream is opened. 2078f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * After opening a stream with an unspecified value, the application must 2088f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * query for the actual value, which may vary by device. 2098f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * 2108f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * If an exact value is specified then an opened stream will use that value. 2118f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * If a stream cannot be opened with the specified value then the open will fail. 212e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 213e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 214e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz. 2155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 216e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, 2173316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int32_t sampleRate); 2185ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2195ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 22020523edbf2f597c53b90e76694331c807e559515Phil Burk * Request a number of channels for the stream. 221e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 222e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 2238f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * An optimal value will then be chosen when the stream is opened. 2248f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * After opening a stream with an unspecified value, the application must 2258f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * query for the actual value, which may vary by device. 2265ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 2278f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * If an exact value is specified then an opened stream will use that value. 2288f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * If a stream cannot be opened with the specified value then the open will fail. 229e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 230e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 23120523edbf2f597c53b90e76694331c807e559515Phil Burk * @param channelCount Number of channels desired. 2325ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 23320523edbf2f597c53b90e76694331c807e559515Phil BurkAAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* builder, 23420523edbf2f597c53b90e76694331c807e559515Phil Burk int32_t channelCount); 23520523edbf2f597c53b90e76694331c807e559515Phil Burk 23620523edbf2f597c53b90e76694331c807e559515Phil Burk/** 23720523edbf2f597c53b90e76694331c807e559515Phil Burk * 23820523edbf2f597c53b90e76694331c807e559515Phil Burk * @deprecated use AAudioStreamBuilder_setChannelCount() 23920523edbf2f597c53b90e76694331c807e559515Phil Burk */ 24020523edbf2f597c53b90e76694331c807e559515Phil Burk// TODO remove as soon as the NDK and OS are in sync, before RC1 241e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder, 24220523edbf2f597c53b90e76694331c807e559515Phil Burk int32_t samplesPerFrame); 2435ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2445ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 2455ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16. 246e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 247e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 2488f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * An optimal value will then be chosen when the stream is opened. 2498f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * After opening a stream with an unspecified value, the application must 2508f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * query for the actual value, which may vary by device. 251e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 2528f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * If an exact value is specified then an opened stream will use that value. 2538f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * If a stream cannot be opened with the specified value then the open will fail. 254e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 255e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 2568f62489dfdfc1e0303fb1ffa8c6eeb44b611ac51Phil Burk * @param format common formats are AAUDIO_FORMAT_PCM_FLOAT and AAUDIO_FORMAT_PCM_I16. 2575ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 258e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder, 2599dca9824da74d50be02bc81f539cc77b7bde678aPhil Burk aaudio_format_t format); 2605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2615ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 2625ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Request a mode for sharing the device. 263e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 264e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_SHARING_MODE_SHARED. 265e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 2665ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The requested sharing mode may not be available. 267e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The application can query for the actual mode after the stream is opened. 2685ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 2693316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 270e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param sharingMode AAUDIO_SHARING_MODE_SHARED or AAUDIO_SHARING_MODE_EXCLUSIVE 2715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 272e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder, 2735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk aaudio_sharing_mode_t sharingMode); 2745ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 276e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Request the direction for a stream. 277e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 278e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_DIRECTION_OUTPUT. 2795ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 2803316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 2815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param direction AAUDIO_DIRECTION_OUTPUT or AAUDIO_DIRECTION_INPUT 2825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 283e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder, 2843df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk aaudio_direction_t direction); 2855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 2865ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 287e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Set the requested buffer capacity in frames. 2883df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk * The final AAudioStream capacity may differ, but will probably be at least this big. 2893df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk * 290e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 2913df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk * 2923316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 293e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param numFrames the desired buffer capacity in frames or AAUDIO_UNSPECIFIED 2943df348fbaca567ca891503213ff8c344a1ea2e05Phil Burk */ 295e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder, 296e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk int32_t numFrames); 297e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 298e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk/** 299e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * Set the requested performance mode. 300e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * 301e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * The default, if you do not call this function, is AAUDIO_PERFORMANCE_MODE_NONE. 302e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * 303e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 304e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * @param mode the desired performance mode, eg. AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 305e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 306e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil BurkAAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* builder, 307e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk aaudio_performance_mode_t mode); 308e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 309e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 310e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Return one of these values from the data callback function. 311e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 312e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burkenum { 313e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 314e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk /** 315e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Continue calling the callback. 316e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 317e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAUDIO_CALLBACK_RESULT_CONTINUE = 0, 318e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 319e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk /** 320e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Stop calling the callback. 321e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 322e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The application will still need to call AAudioStream_requestPause() 323e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * or AAudioStream_requestStop(). 324e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 325e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAUDIO_CALLBACK_RESULT_STOP, 326e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 327e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk}; 328e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burktypedef int32_t aaudio_data_callback_result_t; 329e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 330e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 331e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback(). 332e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 333e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * For an output stream, this function should render and write numFrames of data 334e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * in the streams current data format to the audioData buffer. 335e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 336e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * For an input stream, this function should read and process numFrames of data 337e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * from the audioData buffer. 338e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 339e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Note that this callback function should be considered a "real-time" function. 340e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * It must not do anything that could cause an unbounded delay because that can cause the 341e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * audio to glitch or pop. 342e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 343e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * These are things the function should NOT do: 344e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <ul> 345e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>allocate memory using, for example, malloc() or new</li> 346e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>any file operations such as opening, closing, reading or writing</li> 347e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>any network operations such as streaming</li> 348e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>use any mutexes or other synchronization primitives</li> 349e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * <li>sleep</li> 350e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * </ul> 351e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 352e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * If you need to move data, eg. MIDI commands, in or out of the callback function then 353e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * we recommend the use of non-blocking techniques such as an atomic FIFO. 354e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 355e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 356e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param userData the same address that was passed to AAudioStreamBuilder_setCallback() 357e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param audioData a pointer to the audio data 358e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param numFrames the number of frames to be processed 359e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @return AAUDIO_CALLBACK_RESULT_* 360e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 361e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burktypedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( 362e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAudioStream *stream, 363e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *userData, 364e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *audioData, 365e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk int32_t numFrames); 366e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 367e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 368e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Request that AAudio call this functions when the stream is running. 369e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 370e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Note that when using this callback, the audio data will be passed in or out 371e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * of the function as an argument. 372e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * So you cannot call AAudioStream_write() or AAudioStream_read() on the same stream 373e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * that has an active data callback. 374e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 375e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The callback function will start being called after AAudioStream_requestStart() is called. 376e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * It will stop being called after AAudioStream_requestPause() or 377e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * AAudioStream_requestStop() is called. 378e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 379e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * This callback function will be called on a real-time thread owned by AAudio. See 3800d804369941be2adddea3b4bdfff7f2d6d9e361cGlenn Kasten * {@link AAudioStream_dataCallback} for more information. 381e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 382e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 383e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 384e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 385e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param callback pointer to a function that will process audio data. 386e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param userData pointer to an application data structure that will be passed 387e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * to the callback functions. 388e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 389e057ca91a9b96665d430ac89f1b38a36621f83bdPhil BurkAAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder, 390e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAudioStream_dataCallback callback, 391e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *userData); 392e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 393e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 394e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Set the requested data callback buffer size in frames. 395e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * See {@link AAudioStream_dataCallback}. 396e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 397e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 398e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 399e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * For the lowest possible latency, do not call this function. AAudio will then 400e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * call the dataProc callback function with whatever size is optimal. 401e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * That size may vary from one callback to another. 402e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 403e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Only use this function if the application requires a specific number of frames for processing. 404e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * The application might, for example, be using an FFT that requires 405e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * a specific power-of-two sized buffer. 406e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 407e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * AAudio may need to add additional buffering in order to adapt between the internal 408e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * buffer size and the requested buffer size. 409e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 410e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * If you do call this function then the requested size should be less than 411e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * half the buffer capacity, to allow double buffering. 412e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 413e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 414e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param numFrames the desired buffer size in frames or AAUDIO_UNSPECIFIED 415e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 416e057ca91a9b96665d430ac89f1b38a36621f83bdPhil BurkAAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* builder, 417e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk int32_t numFrames); 418e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 419e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 420e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Prototype for the callback function that is passed to 421e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * AAudioStreamBuilder_setErrorCallback(). 422e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 423e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 424e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback() 425e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param error an AAUDIO_ERROR_* value. 426e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 427e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burktypedef void (*AAudioStream_errorCallback)( 428e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAudioStream *stream, 429e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *userData, 430e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk aaudio_result_t error); 431e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 432e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 433e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Request that AAudio call this functions if any error occurs on a callback thread. 434e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 435e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * It will be called, for example, if a headset or a USB device is unplugged causing the stream's 436e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * device to be unavailable. 437e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * In response, this function could signal or launch another thread to reopen a 438e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * stream on another device. Do not reopen the stream in this callback. 439e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 440e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * This will not be called because of actions by the application, such as stopping 441e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * or closing a stream. 442e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 443e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Another possible cause of error would be a timeout or an unanticipated internal error. 444e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 445e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 446e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 447e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param builder reference provided by AAudio_createStreamBuilder() 448e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param callback pointer to a function that will be called if an error occurs. 449e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param userData pointer to an application data structure that will be passed 450e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * to the callback functions. 451e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 452e057ca91a9b96665d430ac89f1b38a36621f83bdPhil BurkAAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builder, 453e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk AAudioStream_errorCallback callback, 454e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk void *userData); 4555ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4565ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 4575ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Open a stream based on the options in the StreamBuilder. 4585ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4595ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * AAudioStream_close must be called when finished with the stream to recover 4605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * the memory and to free the associated resources. 4615ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4623316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 4633316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream pointer to a variable to receive the new stream reference 4645ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 4655ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 466e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder, 467e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil Burk AAudioStream** stream); 4685ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4695ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 4705ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Delete the resources associated with the StreamBuilder. 4715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4723316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param builder reference provided by AAudio_createStreamBuilder() 4735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 4745ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 475e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* builder); 4765ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 4785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// Stream Control 4795ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 4805ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 4825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Free the resources associated with a stream created by AAudioStreamBuilder_openStream() 4835ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4843316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 4855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 4865ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 487e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream); 4885ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 4895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 4905ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Asynchronously request to start playing the stream. For output streams, one should 4915ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * write to the stream to fill the buffer before starting. 4925ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Otherwise it will underflow. 4935ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * After this call the state will be in AAUDIO_STREAM_STATE_STARTING or AAUDIO_STREAM_STATE_STARTED. 4945ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 4953316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 4965ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 4975ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 498e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream); 4995ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5005ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5015ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Asynchronous request for the stream to pause. 5025ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Pausing a stream will freeze the data flow but not flush any buffers. 5035ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Use AAudioStream_Start() to resume playback after a pause. 5045ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * After this call the state will be in AAUDIO_STREAM_STATE_PAUSING or AAUDIO_STREAM_STATE_PAUSED. 5055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 506068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams. 507068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * For input streams use AAudioStream_requestStop(). 508068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * 5093316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5105ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5115ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 512e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream); 5135ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5145ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Asynchronous request for the stream to flush. 5165ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Flushing will discard any pending data. 5175ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This call only works if the stream is pausing or paused. TODO review 5185ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Frame counters are not reset by a flush. They may be advanced. 5195ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * After this call the state will be in AAUDIO_STREAM_STATE_FLUSHING or AAUDIO_STREAM_STATE_FLUSHED. 5205ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 521068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams. 522068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * 5233316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5245ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5255ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 526e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream); 5275ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5285ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5295ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Asynchronous request for the stream to stop. 5305ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The stream will stop after all of the data currently buffered has been played. 5315ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * After this call the state will be in AAUDIO_STREAM_STATE_STOPPING or AAUDIO_STREAM_STATE_STOPPED. 5325ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5333316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5345ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5355ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 536e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream); 5375ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5385ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5393316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Query the current state of the client, eg. AAUDIO_STREAM_STATE_PAUSING 5405ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5413316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * This function will immediately return the state without updating the state. 5423316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * If you want to update the client state based on the server state then 5433316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * call AAudioStream_waitForStateChange() with currentState 5443316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * set to AAUDIO_STREAM_STATE_UNKNOWN and a zero timeout. 5453316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * 5463316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 5475ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 548e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream); 5495ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5505ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5515ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Wait until the current state no longer matches the input state. 5525ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5533316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * This will update the current client state. 5543316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * 5555ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * <pre><code> 5565ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * aaudio_stream_state_t currentState; 5575ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * aaudio_result_t result = AAudioStream_getState(stream, ¤tState); 5585ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSING) { 5595ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * result = AAudioStream_waitForStateChange( 5605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * stream, currentState, ¤tState, MY_TIMEOUT_NANOS); 5615ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * } 5625ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * </code></pre> 5635ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5643316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream A reference provided by AAudioStreamBuilder_openStream() 5655ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param inputState The state we want to avoid. 5665ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param nextState Pointer to a variable that will be set to the new state. 5675ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 5685ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error. 5695ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 570e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream, 5715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk aaudio_stream_state_t inputState, 5725ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk aaudio_stream_state_t *nextState, 5733316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t timeoutNanoseconds); 5745ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 5765ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// Stream I/O 5775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 5785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 5795ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 5805ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Read data from the stream. 5815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5825ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The call will wait until the read is complete or until it runs out of time. 5835ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * If timeoutNanos is zero then this call will not wait. 5845ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Note that timeoutNanoseconds is a relative duration in wall clock time. 5865ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Time will not stop if the thread is asleep. 5875ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * So it will be implemented using CLOCK_BOOTTIME. 5885ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This call is "strong non-blocking" unless it has to wait for data. 5905ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 5915ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param stream A stream created using AAudioStreamBuilder_openStream(). 5925ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param buffer The address of the first sample. 5935ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param numFrames Number of frames to read. Only complete frames will be written. 5945ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 5953316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return The number of frames actually read or a negative error. 5965ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 597e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream, 5985ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk void *buffer, 5993316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int32_t numFrames, 6003316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t timeoutNanoseconds); 6015ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6025ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6035ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Write data to the stream. 6045ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The call will wait until the write is complete or until it runs out of time. 6065ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * If timeoutNanos is zero then this call will not wait. 6075ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6085ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Note that timeoutNanoseconds is a relative duration in wall clock time. 6095ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Time will not stop if the thread is asleep. 6105ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * So it will be implemented using CLOCK_BOOTTIME. 6115ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6125ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This call is "strong non-blocking" unless it has to wait for room in the buffer. 6135ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6145ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param stream A stream created using AAudioStreamBuilder_openStream(). 6155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param buffer The address of the first sample. 6165ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param numFrames Number of frames to write. Only complete frames will be written. 6175ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 6185ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return The number of frames actually written or a negative error. 6195ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 620e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream, 6215ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk const void *buffer, 6223316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int32_t numFrames, 6233316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t timeoutNanoseconds); 6245ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6255ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 6265ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// Stream - queries 6275ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk// ============================================================ 6285ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6295ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6305ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This can be used to adjust the latency of the buffer by changing 6315ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * the threshold where blocking will occur. 6323316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * By combining this with AAudioStream_getXRunCount(), the latency can be tuned 6335ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * at run-time for each device. 6345ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6353316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * This cannot be set higher than AAudioStream_getBufferCapacityInFrames(). 6363316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * 6373316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Note that you will probably not get the exact size you request. 6383316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Call AAudioStream_getBufferSizeInFrames() to see what the actual final size is. 6395ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6403316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 641e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param numFrames requested number of frames that can be filled without blocking 6423316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual buffer size in frames or a negative error 6435ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 644e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream, 645e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk int32_t numFrames); 6465ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6475ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6485ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Query the maximum number of frames that can be filled without blocking. 6495ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6503316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 6513316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return buffer size in frames. 6525ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 653e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream); 6545ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6555ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6563316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Query the number of frames that the application should read or write at 6573316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * one time for optimal performance. It is OK if an application writes 6583316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * a different number of frames. But the buffer size may need to be larger 6593316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * in order to avoid underruns or overruns. 6605ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6613316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * Note that this may or may not match the actual device burst size. 6623316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * For some endpoints, the burst size can vary dynamically. 6633316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * But these tend to be devices with high latency. 6643316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * 6653316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 6663316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return burst size 6675ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 668e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream); 6695ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6705ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 6715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Query maximum buffer capacity in frames. 6725ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 6733316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 674e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @return buffer capacity in frames 6755ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 676e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream); 6775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 6785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 679e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * Query the size of the buffer that will be passed to the dataProc callback 680e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * in the numFrames parameter. 681e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 682e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * This call can be used if the application needs to know the value of numFrames before 683e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * the stream is started. This is not normally necessary. 684e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 685e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * If a specific size was requested by calling AAudioStreamBuilder_setCallbackSizeInFrames() 686e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * then this will be the same size. 687e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 688e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * If AAudioStreamBuilder_setCallbackSizeInFrames() was not called then this will 689e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * return the size chosen by AAudio, or AAUDIO_UNSPECIFIED. 690e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 691e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * AAUDIO_UNSPECIFIED indicates that the callback buffer size for this stream 692e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * may vary from one dataProc callback to the next. 693e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * 694e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 695e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk * @return callback buffer size in frames or AAUDIO_UNSPECIFIED 696e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk */ 697e057ca91a9b96665d430ac89f1b38a36621f83bdPhil BurkAAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream); 698e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk 699e057ca91a9b96665d430ac89f1b38a36621f83bdPhil Burk/** 7005ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * An XRun is an Underrun or an Overrun. 7015ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * During playing, an underrun will occur if the stream is not written in time 7025ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * and the system runs out of valid data. 7035ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * During recording, an overrun will occur if the stream is not read in time 7045ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * and there is no place to put the incoming data so it is discarded. 7055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7065ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * An underrun or overrun can cause an audible "pop" or "glitch". 7075ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 708068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * Note that some INPUT devices may not support this function. 709068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * In that case a 0 will always be returned. 710068c10f03d16a7f73abf138cc751cf3bde7518dfPhil Burk * 7113316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7123316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return the underrun or overrun count 7135ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 714e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream); 7155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7165ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7173316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7183316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual sample rate 7195ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 720e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream); 7215ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7225ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 72320523edbf2f597c53b90e76694331c807e559515Phil Burk * A stream has one or more channels of data. 72420523edbf2f597c53b90e76694331c807e559515Phil Burk * A frame will contain one sample for each channel. 72520523edbf2f597c53b90e76694331c807e559515Phil Burk * 72620523edbf2f597c53b90e76694331c807e559515Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 72720523edbf2f597c53b90e76694331c807e559515Phil Burk * @return actual number of channels 72820523edbf2f597c53b90e76694331c807e559515Phil Burk */ 72920523edbf2f597c53b90e76694331c807e559515Phil BurkAAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* stream); 73020523edbf2f597c53b90e76694331c807e559515Phil Burk 73120523edbf2f597c53b90e76694331c807e559515Phil Burk/** 7325ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The samplesPerFrame is also known as channelCount. 7335ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 73420523edbf2f597c53b90e76694331c807e559515Phil Burk * @deprecated use AAudioStream_getChannelCount() 7353316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7363316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual samples per frame 7375ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 738e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream); 7395ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7405ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7413316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 742e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil Burk * @return actual device ID 7435ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 744e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream); 7455ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7465ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7473316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7483316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual data format 7495ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 7509dca9824da74d50be02bc81f539cc77b7bde678aPhil BurkAAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* stream); 7515ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7525ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7535ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Provide actual sharing mode. 7543316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7553316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return actual sharing mode 7565ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 757e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream); 7585ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7595ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 760e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * Get the performance mode used by the stream. 761e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * 762e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 763e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk */ 764e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil BurkAAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* stream); 765e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk 766e2fbb59e729f6c3cade3b531f6f6411417ccbf40Phil Burk/** 7673316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7683316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return direction 7695ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 770e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream); 7715ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7725ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7735ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Passes back the number of frames that have been written since the stream was created. 7745ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * For an output stream, this will be advanced by the application calling write(). 7753316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * For an input stream, this will be advanced by the endpoint. 7765ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7775ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The frame position is monotonically increasing. 7785ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7793316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7803316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return frames written 7815ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 782e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream); 7835ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7845ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7855ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Passes back the number of frames that have been read since the stream was created. 7863316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * For an output stream, this will be advanced by the endpoint. 7875ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * For an input stream, this will be advanced by the application calling read(). 7885ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7895ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The frame position is monotonically increasing. 7905ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 7913316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 7923316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @return frames read 7935ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 794e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream); 7955ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 7965ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk/** 7975ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Passes back the time at which a particular frame was presented. 7985ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * This can be used to synchronize audio with video or MIDI. 7995ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * It can also be used to align a recorded stream with a playback stream. 8005ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 8015ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Timestamps are only valid when the stream is in AAUDIO_STREAM_STATE_STARTED. 8025ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * AAUDIO_ERROR_INVALID_STATE will be returned if the stream is not started. 8035ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Note that because requestStart() is asynchronous, timestamps will not be valid until 8045ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * a short time after calling requestStart(). 8055ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * So AAUDIO_ERROR_INVALID_STATE should not be considered a fatal error. 8065ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * Just try calling again later. 8075ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 8085ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * If an error occurs, then the position and time will not be modified. 8095ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 8105ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * The position and time passed back are monotonically increasing. 8115ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * 8123316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk * @param stream reference provided by AAudioStreamBuilder_openStream() 8135ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param clockid AAUDIO_CLOCK_MONOTONIC or AAUDIO_CLOCK_BOOTTIME 8145ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param framePosition pointer to a variable to receive the position 8155ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @param timeNanoseconds pointer to a variable to receive the time 8165ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk * @return AAUDIO_OK or a negative error 8175ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk */ 818e2155ef0ec6742db7a3128c4ef4fb96e02828d1bPhil BurkAAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream, 8193316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk clockid_t clockid, 8203316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t *framePosition, 8213316d5e6d375a4f09c681205e9094d30a0bfc4a2Phil Burk int64_t *timeNanoseconds); 8225ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 8235ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#ifdef __cplusplus 8245ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk} 8255ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#endif 8265ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk 8275ed503c7a66c90f93759c90237a9b432dbd93f9fPhil Burk#endif //AAUDIO_AAUDIO_H 828a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk 829a45be8b660292777f8c6e1b3896b0a291efa93f7Phil Burk/** @} */ 830