AAudio.h revision e2155ef0ec6742db7a3128c4ef4fb96e02828d1b
1/* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17/** 18 * This is the 'C' ABI for AAudio. 19 */ 20#ifndef AAUDIO_AAUDIO_H 21#define AAUDIO_AAUDIO_H 22 23#include <time.h> 24#include "AAudioDefinitions.h" 25 26#ifdef __cplusplus 27extern "C" { 28#endif 29 30typedef struct AAudioStreamStruct AAudioStream; 31typedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; 32 33#ifndef AAUDIO_API 34#define AAUDIO_API /* export this symbol */ 35#endif 36 37// ============================================================ 38// Audio System 39// ============================================================ 40 41/** 42 * The text is the ASCII symbol corresponding to the returnCode, 43 * or an English message saying the returnCode is unrecognized. 44 * This is intended for developers to use when debugging. 45 * It is not for display to users. 46 * 47 * @return pointer to a text representation of an AAudio result code. 48 */ 49AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode); 50 51/** 52 * The text is the ASCII symbol corresponding to the stream state, 53 * or an English message saying the state is unrecognized. 54 * This is intended for developers to use when debugging. 55 * It is not for display to users. 56 * 57 * @return pointer to a text representation of an AAudio state. 58 */ 59AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state); 60 61// ============================================================ 62// StreamBuilder 63// ============================================================ 64 65/** 66 * Create a StreamBuilder that can be used to open a Stream. 67 * 68 * The deviceId is initially unspecified, meaning that the current default device will be used. 69 * 70 * The default direction is AAUDIO_DIRECTION_OUTPUT. 71 * The default sharing mode is AAUDIO_SHARING_MODE_SHARED. 72 * The data format, samplesPerFrames and sampleRate are unspecified and will be 73 * chosen by the device when it is opened. 74 * 75 * AAudioStreamBuilder_delete() must be called when you are done using the builder. 76 */ 77AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder); 78 79/** 80 * Request an audio device identified device using an ID. 81 * On Android, for example, the ID could be obtained from the Java AudioManager. 82 * 83 * By default, the primary device will be used. 84 * 85 * @param builder reference provided by AAudio_createStreamBuilder() 86 * @param deviceId device identifier or AAUDIO_DEVICE_UNSPECIFIED 87 */ 88AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, 89 int32_t deviceId); 90 91/** 92 * Request a sample rate in Hz. 93 * The stream may be opened with a different sample rate. 94 * So the application should query for the actual rate after the stream is opened. 95 * 96 * Technically, this should be called the "frame rate" or "frames per second", 97 * because it refers to the number of complete frames transferred per second. 98 * But it is traditionally called "sample rate". Se we use that term. 99 * 100 * Default is AAUDIO_UNSPECIFIED. 101 102 */ 103AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, 104 int32_t sampleRate); 105 106/** 107 * Request a number of samples per frame. 108 * The stream may be opened with a different value. 109 * So the application should query for the actual value after the stream is opened. 110 * 111 * Default is AAUDIO_UNSPECIFIED. 112 * 113 * Note, this quantity is sometimes referred to as "channel count". 114 */ 115AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder, 116 int32_t samplesPerFrame); 117 118/** 119 * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16. 120 * The application should query for the actual format after the stream is opened. 121 */ 122AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder, 123 aaudio_audio_format_t format); 124 125/** 126 * Request a mode for sharing the device. 127 * The requested sharing mode may not be available. 128 * So the application should query for the actual mode after the stream is opened. 129 * 130 * @param builder reference provided by AAudio_createStreamBuilder() 131 * @param sharingMode AAUDIO_SHARING_MODE_LEGACY or AAUDIO_SHARING_MODE_EXCLUSIVE 132 */ 133AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder, 134 aaudio_sharing_mode_t sharingMode); 135 136/** 137 * Request the direction for a stream. The default is AAUDIO_DIRECTION_OUTPUT. 138 * 139 * @param builder reference provided by AAudio_createStreamBuilder() 140 * @param direction AAUDIO_DIRECTION_OUTPUT or AAUDIO_DIRECTION_INPUT 141 */ 142AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder, 143 aaudio_direction_t direction); 144 145/** 146 * Set the requested maximum buffer capacity in frames. 147 * The final AAudioStream capacity may differ, but will probably be at least this big. 148 * 149 * Default is AAUDIO_UNSPECIFIED. 150 * 151 * @param builder reference provided by AAudio_createStreamBuilder() 152 * @param frames the desired buffer capacity in frames or AAUDIO_UNSPECIFIED 153 */ 154AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder, 155 int32_t frames); 156 157/** 158 * Open a stream based on the options in the StreamBuilder. 159 * 160 * AAudioStream_close must be called when finished with the stream to recover 161 * the memory and to free the associated resources. 162 * 163 * @param builder reference provided by AAudio_createStreamBuilder() 164 * @param stream pointer to a variable to receive the new stream reference 165 * @return AAUDIO_OK or a negative error. 166 */ 167AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder, 168 AAudioStream** stream); 169 170/** 171 * Delete the resources associated with the StreamBuilder. 172 * 173 * @param builder reference provided by AAudio_createStreamBuilder() 174 * @return AAUDIO_OK or a negative error. 175 */ 176AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* builder); 177 178// ============================================================ 179// Stream Control 180// ============================================================ 181 182/** 183 * Free the resources associated with a stream created by AAudioStreamBuilder_openStream() 184 * 185 * @param stream reference provided by AAudioStreamBuilder_openStream() 186 * @return AAUDIO_OK or a negative error. 187 */ 188AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream); 189 190/** 191 * Asynchronously request to start playing the stream. For output streams, one should 192 * write to the stream to fill the buffer before starting. 193 * Otherwise it will underflow. 194 * After this call the state will be in AAUDIO_STREAM_STATE_STARTING or AAUDIO_STREAM_STATE_STARTED. 195 * 196 * @param stream reference provided by AAudioStreamBuilder_openStream() 197 * @return AAUDIO_OK or a negative error. 198 */ 199AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream); 200 201/** 202 * Asynchronous request for the stream to pause. 203 * Pausing a stream will freeze the data flow but not flush any buffers. 204 * Use AAudioStream_Start() to resume playback after a pause. 205 * After this call the state will be in AAUDIO_STREAM_STATE_PAUSING or AAUDIO_STREAM_STATE_PAUSED. 206 * 207 * @param stream reference provided by AAudioStreamBuilder_openStream() 208 * @return AAUDIO_OK or a negative error. 209 */ 210AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream); 211 212/** 213 * Asynchronous request for the stream to flush. 214 * Flushing will discard any pending data. 215 * This call only works if the stream is pausing or paused. TODO review 216 * Frame counters are not reset by a flush. They may be advanced. 217 * After this call the state will be in AAUDIO_STREAM_STATE_FLUSHING or AAUDIO_STREAM_STATE_FLUSHED. 218 * 219 * @param stream reference provided by AAudioStreamBuilder_openStream() 220 * @return AAUDIO_OK or a negative error. 221 */ 222AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream); 223 224/** 225 * Asynchronous request for the stream to stop. 226 * The stream will stop after all of the data currently buffered has been played. 227 * After this call the state will be in AAUDIO_STREAM_STATE_STOPPING or AAUDIO_STREAM_STATE_STOPPED. 228 * 229 * @param stream reference provided by AAudioStreamBuilder_openStream() 230 * @return AAUDIO_OK or a negative error. 231 */ 232AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream); 233 234/** 235 * Query the current state of the client, eg. AAUDIO_STREAM_STATE_PAUSING 236 * 237 * This function will immediately return the state without updating the state. 238 * If you want to update the client state based on the server state then 239 * call AAudioStream_waitForStateChange() with currentState 240 * set to AAUDIO_STREAM_STATE_UNKNOWN and a zero timeout. 241 * 242 * @param stream reference provided by AAudioStreamBuilder_openStream() 243 * @param state pointer to a variable that will be set to the current state 244 */ 245AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream); 246 247/** 248 * Wait until the current state no longer matches the input state. 249 * 250 * This will update the current client state. 251 * 252 * <pre><code> 253 * aaudio_stream_state_t currentState; 254 * aaudio_result_t result = AAudioStream_getState(stream, ¤tState); 255 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSING) { 256 * result = AAudioStream_waitForStateChange( 257 * stream, currentState, ¤tState, MY_TIMEOUT_NANOS); 258 * } 259 * </code></pre> 260 * 261 * @param stream A reference provided by AAudioStreamBuilder_openStream() 262 * @param inputState The state we want to avoid. 263 * @param nextState Pointer to a variable that will be set to the new state. 264 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 265 * @return AAUDIO_OK or a negative error. 266 */ 267AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream, 268 aaudio_stream_state_t inputState, 269 aaudio_stream_state_t *nextState, 270 int64_t timeoutNanoseconds); 271 272// ============================================================ 273// Stream I/O 274// ============================================================ 275 276/** 277 * Read data from the stream. 278 * 279 * The call will wait until the read is complete or until it runs out of time. 280 * If timeoutNanos is zero then this call will not wait. 281 * 282 * Note that timeoutNanoseconds is a relative duration in wall clock time. 283 * Time will not stop if the thread is asleep. 284 * So it will be implemented using CLOCK_BOOTTIME. 285 * 286 * This call is "strong non-blocking" unless it has to wait for data. 287 * 288 * @param stream A stream created using AAudioStreamBuilder_openStream(). 289 * @param buffer The address of the first sample. 290 * @param numFrames Number of frames to read. Only complete frames will be written. 291 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 292 * @return The number of frames actually read or a negative error. 293 */ 294AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream, 295 void *buffer, 296 int32_t numFrames, 297 int64_t timeoutNanoseconds); 298 299/** 300 * Write data to the stream. 301 * 302 * The call will wait until the write is complete or until it runs out of time. 303 * If timeoutNanos is zero then this call will not wait. 304 * 305 * Note that timeoutNanoseconds is a relative duration in wall clock time. 306 * Time will not stop if the thread is asleep. 307 * So it will be implemented using CLOCK_BOOTTIME. 308 * 309 * This call is "strong non-blocking" unless it has to wait for room in the buffer. 310 * 311 * @param stream A stream created using AAudioStreamBuilder_openStream(). 312 * @param buffer The address of the first sample. 313 * @param numFrames Number of frames to write. Only complete frames will be written. 314 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 315 * @return The number of frames actually written or a negative error. 316 */ 317AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream, 318 const void *buffer, 319 int32_t numFrames, 320 int64_t timeoutNanoseconds); 321 322 323// ============================================================ 324// High priority audio threads 325// ============================================================ 326 327typedef void *(*aaudio_audio_thread_proc_t)(void *); 328 329/** 330 * Create a thread associated with a stream. The thread has special properties for 331 * low latency audio performance. This thread can be used to implement a callback API. 332 * 333 * Only one thread may be associated with a stream. 334 * 335 * If you are using multiple streams then we recommend that you only do 336 * blocking reads or writes on one stream. You can do non-blocking I/O on the 337 * other streams by setting the timeout to zero. 338 * This thread should be created for the stream that you will block on. 339 * 340 * Note that this API is in flux. 341 * 342 * @param stream A stream created using AAudioStreamBuilder_openStream(). 343 * @param periodNanoseconds the estimated period at which the audio thread will need to wake up 344 * @param threadProc your thread entry point 345 * @param arg an argument that will be passed to your thread entry point 346 * @return AAUDIO_OK or a negative error. 347 */ 348AAUDIO_API aaudio_result_t AAudioStream_createThread(AAudioStream* stream, 349 int64_t periodNanoseconds, 350 aaudio_audio_thread_proc_t threadProc, 351 void *arg); 352 353/** 354 * Wait until the thread exits or an error occurs. 355 * 356 * @param stream A stream created using AAudioStreamBuilder_openStream(). 357 * @param returnArg a pointer to a variable to receive the return value 358 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 359 * @return AAUDIO_OK or a negative error. 360 */ 361AAUDIO_API aaudio_result_t AAudioStream_joinThread(AAudioStream* stream, 362 void **returnArg, 363 int64_t timeoutNanoseconds); 364 365// ============================================================ 366// Stream - queries 367// ============================================================ 368 369 370/** 371 * This can be used to adjust the latency of the buffer by changing 372 * the threshold where blocking will occur. 373 * By combining this with AAudioStream_getXRunCount(), the latency can be tuned 374 * at run-time for each device. 375 * 376 * This cannot be set higher than AAudioStream_getBufferCapacityInFrames(). 377 * 378 * Note that you will probably not get the exact size you request. 379 * Call AAudioStream_getBufferSizeInFrames() to see what the actual final size is. 380 * 381 * @param stream reference provided by AAudioStreamBuilder_openStream() 382 * @param requestedFrames requested number of frames that can be filled without blocking 383 * @return actual buffer size in frames or a negative error 384 */ 385AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream, 386 int32_t requestedFrames); 387 388/** 389 * Query the maximum number of frames that can be filled without blocking. 390 * 391 * @param stream reference provided by AAudioStreamBuilder_openStream() 392 * @return buffer size in frames. 393 */ 394AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream); 395 396/** 397 * Query the number of frames that the application should read or write at 398 * one time for optimal performance. It is OK if an application writes 399 * a different number of frames. But the buffer size may need to be larger 400 * in order to avoid underruns or overruns. 401 * 402 * Note that this may or may not match the actual device burst size. 403 * For some endpoints, the burst size can vary dynamically. 404 * But these tend to be devices with high latency. 405 * 406 * @param stream reference provided by AAudioStreamBuilder_openStream() 407 * @return burst size 408 */ 409AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream); 410 411/** 412 * Query maximum buffer capacity in frames. 413 * 414 * @param stream reference provided by AAudioStreamBuilder_openStream() 415 * @return the buffer capacity in frames 416 */ 417AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream); 418 419/** 420 * An XRun is an Underrun or an Overrun. 421 * During playing, an underrun will occur if the stream is not written in time 422 * and the system runs out of valid data. 423 * During recording, an overrun will occur if the stream is not read in time 424 * and there is no place to put the incoming data so it is discarded. 425 * 426 * An underrun or overrun can cause an audible "pop" or "glitch". 427 * 428 * @param stream reference provided by AAudioStreamBuilder_openStream() 429 * @return the underrun or overrun count 430 */ 431AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream); 432 433/** 434 * @param stream reference provided by AAudioStreamBuilder_openStream() 435 * @return actual sample rate 436 */ 437AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream); 438 439/** 440 * The samplesPerFrame is also known as channelCount. 441 * 442 * @param stream reference provided by AAudioStreamBuilder_openStream() 443 * @return actual samples per frame 444 */ 445AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream); 446 447/** 448 * @param stream reference provided by AAudioStreamBuilder_openStream() 449 * @return actual device ID 450 */ 451AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream); 452 453/** 454 * @param stream reference provided by AAudioStreamBuilder_openStream() 455 * @return actual data format 456 */ 457AAUDIO_API aaudio_audio_format_t AAudioStream_getFormat(AAudioStream* stream); 458 459/** 460 * Provide actual sharing mode. 461 * @param stream reference provided by AAudioStreamBuilder_openStream() 462 * @return actual sharing mode 463 */ 464AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream); 465 466/** 467 * @param stream reference provided by AAudioStreamBuilder_openStream() 468 * @return direction 469 */ 470AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream); 471 472/** 473 * Passes back the number of frames that have been written since the stream was created. 474 * For an output stream, this will be advanced by the application calling write(). 475 * For an input stream, this will be advanced by the endpoint. 476 * 477 * The frame position is monotonically increasing. 478 * 479 * @param stream reference provided by AAudioStreamBuilder_openStream() 480 * @return frames written 481 */ 482AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream); 483 484/** 485 * Passes back the number of frames that have been read since the stream was created. 486 * For an output stream, this will be advanced by the endpoint. 487 * For an input stream, this will be advanced by the application calling read(). 488 * 489 * The frame position is monotonically increasing. 490 * 491 * @param stream reference provided by AAudioStreamBuilder_openStream() 492 * @return frames read 493 */ 494AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream); 495 496/** 497 * Passes back the time at which a particular frame was presented. 498 * This can be used to synchronize audio with video or MIDI. 499 * It can also be used to align a recorded stream with a playback stream. 500 * 501 * Timestamps are only valid when the stream is in AAUDIO_STREAM_STATE_STARTED. 502 * AAUDIO_ERROR_INVALID_STATE will be returned if the stream is not started. 503 * Note that because requestStart() is asynchronous, timestamps will not be valid until 504 * a short time after calling requestStart(). 505 * So AAUDIO_ERROR_INVALID_STATE should not be considered a fatal error. 506 * Just try calling again later. 507 * 508 * If an error occurs, then the position and time will not be modified. 509 * 510 * The position and time passed back are monotonically increasing. 511 * 512 * @param stream reference provided by AAudioStreamBuilder_openStream() 513 * @param clockid AAUDIO_CLOCK_MONOTONIC or AAUDIO_CLOCK_BOOTTIME 514 * @param framePosition pointer to a variable to receive the position 515 * @param timeNanoseconds pointer to a variable to receive the time 516 * @return AAUDIO_OK or a negative error 517 */ 518AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream, 519 clockid_t clockid, 520 int64_t *framePosition, 521 int64_t *timeNanoseconds); 522 523#ifdef __cplusplus 524} 525#endif 526 527#endif //AAUDIO_AAUDIO_H 528