Audio

#include <AAudio.h>

Summary

Enumerations

Anonymous Enum 0{
  AAUDIO_DIRECTION_OUTPUT,
  AAUDIO_DIRECTION_INPUT
}
enum
Anonymous Enum 1{
  AAUDIO_FORMAT_INVALID = -1,
  AAUDIO_FORMAT_UNSPECIFIED = 0,
  AAUDIO_FORMAT_PCM_I16,
  AAUDIO_FORMAT_PCM_FLOAT
}
enum
Anonymous Enum 10{
  AAUDIO_CALLBACK_RESULT_CONTINUE = 0,
  AAUDIO_CALLBACK_RESULT_STOP
}
enum
Return one of these values from the data callback function.
Anonymous Enum 2{
  AAUDIO_OK,
  AAUDIO_ERROR_BASE = -900,
  AAUDIO_ERROR_DISCONNECTED,
  AAUDIO_ERROR_ILLEGAL_ARGUMENT,
  AAUDIO_ERROR_INTERNAL = AAUDIO_ERROR_ILLEGAL_ARGUMENT + 2,
  AAUDIO_ERROR_INVALID_STATE,
  AAUDIO_ERROR_INVALID_HANDLE = AAUDIO_ERROR_INVALID_STATE + 3,
  AAUDIO_ERROR_UNIMPLEMENTED = AAUDIO_ERROR_INVALID_HANDLE + 2,
  AAUDIO_ERROR_UNAVAILABLE,
  AAUDIO_ERROR_NO_FREE_HANDLES,
  AAUDIO_ERROR_NO_MEMORY,
  AAUDIO_ERROR_NULL,
  AAUDIO_ERROR_TIMEOUT,
  AAUDIO_ERROR_WOULD_BLOCK,
  AAUDIO_ERROR_INVALID_FORMAT,
  AAUDIO_ERROR_OUT_OF_RANGE,
  AAUDIO_ERROR_NO_SERVICE,
  AAUDIO_ERROR_INVALID_RATE
}
enum
These result codes are returned from AAudio functions to indicate success or failure.
Anonymous Enum 3{
  AAUDIO_STREAM_STATE_UNINITIALIZED = 0,
  AAUDIO_STREAM_STATE_UNKNOWN,
  AAUDIO_STREAM_STATE_OPEN,
  AAUDIO_STREAM_STATE_STARTING,
  AAUDIO_STREAM_STATE_STARTED,
  AAUDIO_STREAM_STATE_PAUSING,
  AAUDIO_STREAM_STATE_PAUSED,
  AAUDIO_STREAM_STATE_FLUSHING,
  AAUDIO_STREAM_STATE_FLUSHED,
  AAUDIO_STREAM_STATE_STOPPING,
  AAUDIO_STREAM_STATE_STOPPED,
  AAUDIO_STREAM_STATE_CLOSING,
  AAUDIO_STREAM_STATE_CLOSED,
  AAUDIO_STREAM_STATE_DISCONNECTED
}
enum
Anonymous Enum 4{
  AAUDIO_SHARING_MODE_EXCLUSIVE,
  AAUDIO_SHARING_MODE_SHARED
}
enum
Anonymous Enum 5{
  AAUDIO_PERFORMANCE_MODE_NONE = 10,
  AAUDIO_PERFORMANCE_MODE_POWER_SAVING,
  AAUDIO_PERFORMANCE_MODE_LOW_LATENCY
}
enum
Anonymous Enum 6{
  AAUDIO_USAGE_MEDIA = 1,
  AAUDIO_USAGE_VOICE_COMMUNICATION = 2,
  AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING = 3,
  AAUDIO_USAGE_ALARM = 4,
  AAUDIO_USAGE_NOTIFICATION = 5,
  AAUDIO_USAGE_NOTIFICATION_RINGTONE = 6,
  AAUDIO_USAGE_NOTIFICATION_EVENT = 10,
  AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY = 11,
  AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE = 12,
  AAUDIO_USAGE_ASSISTANCE_SONIFICATION = 13,
  AAUDIO_USAGE_GAME = 14,
  AAUDIO_USAGE_ASSISTANT = 16
}
enum
The USAGE attribute expresses "why" you are playing a sound, what is this sound used for.
Anonymous Enum 7{
  AAUDIO_CONTENT_TYPE_SPEECH = 1,
  AAUDIO_CONTENT_TYPE_MUSIC = 2,
  AAUDIO_CONTENT_TYPE_MOVIE = 3,
  AAUDIO_CONTENT_TYPE_SONIFICATION = 4
}
enum
The CONTENT_TYPE attribute describes "what" you are playing.
Anonymous Enum 8{
  AAUDIO_INPUT_PRESET_GENERIC = 1,
  AAUDIO_INPUT_PRESET_CAMCORDER = 5,
  AAUDIO_INPUT_PRESET_VOICE_RECOGNITION = 6,
  AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION = 7,
  AAUDIO_INPUT_PRESET_UNPROCESSED = 9
}
enum
Defines the audio source.
Anonymous Enum 9{
  AAUDIO_SESSION_ID_NONE = -1,
  AAUDIO_SESSION_ID_ALLOCATE = 0
}
enum
These may be used with AAudioStreamBuilder_setSessionId().

Typedefs

AAudioStream typedef
struct AAudioStreamStruct
AAudioStreamBuilder typedef
struct AAudioStreamBuilderStruct
AAudioStream_dataCallback)(AAudioStream *stream, void *userData, void *audioData, int32_t numFrames) typedef
aaudio_data_callback_result_t(*
Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback().
AAudioStream_errorCallback)(AAudioStream *stream, void *userData, aaudio_result_t error) typedef
void(*
Prototype for the callback function that is passed to AAudioStreamBuilder_setErrorCallback().
aaudio_content_type_t typedef
int32_t
aaudio_data_callback_result_t typedef
int32_t
aaudio_direction_t typedef
int32_t
aaudio_format_t typedef
int32_t
aaudio_input_preset_t typedef
int32_t
aaudio_performance_mode_t typedef
int32_t
aaudio_result_t typedef
int32_t
aaudio_session_id_t typedef
int32_t
aaudio_sharing_mode_t typedef
int32_t
aaudio_stream_state_t typedef
int32_t
aaudio_usage_t typedef
int32_t

Functions

AAudioStreamBuilder_delete(AAudioStreamBuilder *builder)
AAUDIO_API aaudio_result_t
Delete the resources associated with the StreamBuilder.
AAudioStreamBuilder_openStream(AAudioStreamBuilder *builder, AAudioStream **stream)
AAUDIO_API aaudio_result_t
Open a stream based on the options in the StreamBuilder.
AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder *builder, int32_t numFrames)
AAUDIO_API void
Set the requested buffer capacity in frames.
AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder *builder, int32_t channelCount)
AAUDIO_API void
Request a number of channels for the stream.
AAudioStreamBuilder_setContentType(AAudioStreamBuilder *builder, aaudio_content_type_t contentType)
AAUDIO_API void
Set the type of audio data that the stream will carry.
AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder *builder, AAudioStream_dataCallback callback, void *userData)
AAUDIO_API void
Request that AAudio call this functions when the stream is running.
AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder *builder, int32_t deviceId)
AAUDIO_API void
Request an audio device identified device using an ID.
AAudioStreamBuilder_setDirection(AAudioStreamBuilder *builder, aaudio_direction_t direction)
AAUDIO_API void
Request the direction for a stream.
AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder *builder, AAudioStream_errorCallback callback, void *userData)
AAUDIO_API void
Request that AAudio call this function if any error occurs or the stream is disconnected.
AAudioStreamBuilder_setFormat(AAudioStreamBuilder *builder, aaudio_format_t format)
AAUDIO_API void
Request a sample data format, for example AAUDIO_FORMAT_PCM_I16.
AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder *builder, int32_t numFrames)
AAUDIO_API void
Set the requested data callback buffer size in frames.
AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder *builder, aaudio_input_preset_t inputPreset)
AAUDIO_API void
Set the input (capture) preset for the stream.
AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder *builder, aaudio_performance_mode_t mode)
AAUDIO_API void
Set the requested performance mode.
AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder *builder, int32_t sampleRate)
AAUDIO_API void
Request a sample rate in Hertz.
AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder *builder, int32_t samplesPerFrame)
AAUDIO_API void
AAudioStreamBuilder_setSessionId(AAudioStreamBuilder *builder, aaudio_session_id_t sessionId)
AAUDIO_API void
Set the requested session ID.
AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder *builder, aaudio_sharing_mode_t sharingMode)
AAUDIO_API void
Request a mode for sharing the device.
AAudioStreamBuilder_setUsage(AAudioStreamBuilder *builder, aaudio_usage_t usage)
AAUDIO_API void
Set the intended use case for the stream.
AAudioStream_close(AAudioStream *stream)
AAUDIO_API aaudio_result_t
Free the resources associated with a stream created by AAudioStreamBuilder_openStream()
AAudioStream_getBufferCapacityInFrames(AAudioStream *stream)
AAUDIO_API int32_t
Query maximum buffer capacity in frames.
AAudioStream_getBufferSizeInFrames(AAudioStream *stream)
AAUDIO_API int32_t
Query the maximum number of frames that can be filled without blocking.
AAudioStream_getChannelCount(AAudioStream *stream)
AAUDIO_API int32_t
A stream has one or more channels of data.
AAudioStream_getContentType(AAudioStream *stream)
AAUDIO_API aaudio_content_type_t
Return the content type for the stream.
AAudioStream_getDeviceId(AAudioStream *stream)
AAUDIO_API int32_t
AAudioStream_getDirection(AAudioStream *stream)
AAUDIO_API aaudio_direction_t
AAudioStream_getFormat(AAudioStream *stream)
AAUDIO_API aaudio_format_t
AAudioStream_getFramesPerBurst(AAudioStream *stream)
AAUDIO_API int32_t
Query the number of frames that the application should read or write at one time for optimal performance.
AAudioStream_getFramesPerDataCallback(AAudioStream *stream)
AAUDIO_API int32_t
Query the size of the buffer that will be passed to the dataProc callback in the numFrames parameter.
AAudioStream_getFramesRead(AAudioStream *stream)
AAUDIO_API int64_t
Passes back the number of frames that have been read since the stream was created.
AAudioStream_getFramesWritten(AAudioStream *stream)
AAUDIO_API int64_t
Passes back the number of frames that have been written since the stream was created.
AAudioStream_getInputPreset(AAudioStream *stream)
AAUDIO_API aaudio_input_preset_t
Return the input preset for the stream.
AAudioStream_getPerformanceMode(AAudioStream *stream)
AAUDIO_API aaudio_performance_mode_t
Get the performance mode used by the stream.
AAudioStream_getSampleRate(AAudioStream *stream)
AAUDIO_API int32_t
AAudioStream_getSamplesPerFrame(AAudioStream *stream)
AAUDIO_API int32_t
AAudioStream_getSessionId(AAudioStream *stream)
AAUDIO_API aaudio_session_id_t
Passes back the session ID associated with this stream.
AAudioStream_getSharingMode(AAudioStream *stream)
AAUDIO_API aaudio_sharing_mode_t
Provide actual sharing mode.
AAudioStream_getState(AAudioStream *stream)
AAUDIO_API aaudio_stream_state_t
Query the current state of the client, eg.
AAudioStream_getTimestamp(AAudioStream *stream, clockid_t clockid, int64_t *framePosition, int64_t *timeNanoseconds)
AAUDIO_API aaudio_result_t
Passes back the time at which a particular frame was presented.
AAudioStream_getUsage(AAudioStream *stream)
AAUDIO_API aaudio_usage_t
Return the use case for the stream.
AAudioStream_getXRunCount(AAudioStream *stream)
AAUDIO_API int32_t
An XRun is an Underrun or an Overrun.
AAudioStream_read(AAudioStream *stream, void *buffer, int32_t numFrames, int64_t timeoutNanoseconds)
AAUDIO_API aaudio_result_t
Read data from the stream.
AAudioStream_requestFlush(AAudioStream *stream)
AAUDIO_API aaudio_result_t
Asynchronous request for the stream to flush.
AAudioStream_requestPause(AAudioStream *stream)
AAUDIO_API aaudio_result_t
Asynchronous request for the stream to pause.
AAudioStream_requestStart(AAudioStream *stream)
AAUDIO_API aaudio_result_t
Asynchronously request to start playing the stream.
AAudioStream_requestStop(AAudioStream *stream)
AAUDIO_API aaudio_result_t
Asynchronous request for the stream to stop.
AAudioStream_setBufferSizeInFrames(AAudioStream *stream, int32_t numFrames)
AAUDIO_API aaudio_result_t
This can be used to adjust the latency of the buffer by changing the threshold where blocking will occur.
AAudioStream_waitForStateChange(AAudioStream *stream, aaudio_stream_state_t inputState, aaudio_stream_state_t *nextState, int64_t timeoutNanoseconds)
AAUDIO_API aaudio_result_t
Wait until the current state no longer matches the input state.
AAudioStream_write(AAudioStream *stream, const void *buffer, int32_t numFrames, int64_t timeoutNanoseconds)
AAUDIO_API aaudio_result_t
Write data to the stream.
AAudio_convertResultToText(aaudio_result_t returnCode)
AAUDIO_API const char *
The text is the ASCII symbol corresponding to the returnCode, or an English message saying the returnCode is unrecognized.
AAudio_convertStreamStateToText(aaudio_stream_state_t state)
AAUDIO_API const char *
The text is the ASCII symbol corresponding to the stream state, or an English message saying the state is unrecognized.
AAudio_createStreamBuilder(AAudioStreamBuilder **builder)
AAUDIO_API aaudio_result_t
Create a StreamBuilder that can be used to open a Stream.

Enumerations

Anonymous Enum 0

 Anonymous Enum 0
Properties
AAUDIO_DIRECTION_INPUT

Audio data will travel into the device, for example from a microphone.

AAUDIO_DIRECTION_OUTPUT

Audio data will travel out of the device, for example through a speaker.

Anonymous Enum 1

 Anonymous Enum 1
Properties
AAUDIO_FORMAT_INVALID
AAUDIO_FORMAT_PCM_FLOAT

This format uses the float data type.

The nominal range of the data is [-1.0f, 1.0f). Values outside that range may be clipped.

See also 'floatData' at https://developer.android.com/reference/android/media/AudioTrack#write(float[],%20int,%20int,%20int)

AAUDIO_FORMAT_PCM_I16

This format uses the int16_t data type.

The maximum range of the data is -32768 to 32767.

AAUDIO_FORMAT_UNSPECIFIED

Anonymous Enum 10

 Anonymous Enum 10

Return one of these values from the data callback function.

Properties
AAUDIO_CALLBACK_RESULT_CONTINUE

Continue calling the callback.

AAUDIO_CALLBACK_RESULT_STOP

Stop calling the callback.

The application will still need to call AAudioStream_requestPause() or AAudioStream_requestStop().

Anonymous Enum 2

 Anonymous Enum 2

These result codes are returned from AAudio functions to indicate success or failure.

Note that error return codes may change in the future so applications should generally not rely on specific return codes.

Properties
AAUDIO_ERROR_BASE
AAUDIO_ERROR_DISCONNECTED

The audio device was disconnected.

This could occur, for example, when headphones are plugged in or unplugged. The stream cannot be used after the device is disconnected. Applications should stop and close the stream. If this error is received in an error callback then another thread should be used to stop and close the stream.

AAUDIO_ERROR_ILLEGAL_ARGUMENT

An invalid parameter was passed to AAudio.

AAUDIO_ERROR_INTERNAL
AAUDIO_ERROR_INVALID_FORMAT

The requested data format is not supported.

AAUDIO_ERROR_INVALID_HANDLE
AAUDIO_ERROR_INVALID_RATE

The requested sample rate was not supported.

AAUDIO_ERROR_INVALID_STATE

The requested operation is not appropriate for the current state of AAudio.

AAUDIO_ERROR_NO_FREE_HANDLES
AAUDIO_ERROR_NO_MEMORY

Memory could not be allocated.

AAUDIO_ERROR_NO_SERVICE

The audio service was not available.

AAUDIO_ERROR_NULL

A NULL pointer was passed to AAudio.

Or a NULL pointer was detected internally.

AAUDIO_ERROR_OUT_OF_RANGE

A requested was out of range.

AAUDIO_ERROR_TIMEOUT

An operation took longer than expected.

AAUDIO_ERROR_UNAVAILABLE

A resource or information is unavailable.

This could occur when an application tries to open too many streams, or a timestamp is not available.

AAUDIO_ERROR_UNIMPLEMENTED

The function is not implemented for this stream.

AAUDIO_ERROR_WOULD_BLOCK
AAUDIO_OK

The call was successful.

Anonymous Enum 4

 Anonymous Enum 4
Properties
AAUDIO_SHARING_MODE_EXCLUSIVE

This will be the only stream using a particular source or sink.

This mode will provide the lowest possible latency. You should close EXCLUSIVE streams immediately when you are not using them.

AAUDIO_SHARING_MODE_SHARED

Multiple applications will be mixed by the AAudio Server.

This will have higher latency than the EXCLUSIVE mode.

Anonymous Enum 5

 Anonymous Enum 5
Properties
AAUDIO_PERFORMANCE_MODE_LOW_LATENCY

Reducing latency is more important than battery life.

AAUDIO_PERFORMANCE_MODE_NONE

No particular performance needs.

Default.

AAUDIO_PERFORMANCE_MODE_POWER_SAVING

Extending battery life is more important than low latency.

This mode is not supported in input streams. For input, mode NONE will be used if this is requested.

Anonymous Enum 6

 Anonymous Enum 6

The USAGE attribute expresses "why" you are playing a sound, what is this sound used for.

This information is used by certain platforms or routing policies to make more refined volume or routing decisions.

Note that these match the equivalent values in AudioAttributes in the Android Java API.

Added in API level 28.

Properties
AAUDIO_USAGE_ALARM

Use this to demand the users attention.

AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY

Use this for screen readers, etcetera.

AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE

Use this for driving or navigation directions.

AAUDIO_USAGE_ASSISTANCE_SONIFICATION

Use this for user interface sounds, beeps, etcetera.

AAUDIO_USAGE_ASSISTANT

Use this for audio responses to user queries, audio instructions or help utterances.

AAUDIO_USAGE_GAME

Use this for game audio and sound effects.

AAUDIO_USAGE_MEDIA

Use this for streaming media, music performance, video, podcasts, etcetera.

AAUDIO_USAGE_NOTIFICATION

Use this for notifying the user when a message has arrived or some other background event has occured.

AAUDIO_USAGE_NOTIFICATION_EVENT

Use this to attract the users attention when, for example, the battery is low.

AAUDIO_USAGE_NOTIFICATION_RINGTONE

Use this when the phone rings.

AAUDIO_USAGE_VOICE_COMMUNICATION

Use this for voice over IP, telephony, etcetera.

AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING

Use this for sounds associated with telephony such as busy tones, DTMF, etcetera.

Anonymous Enum 7

 Anonymous Enum 7

The CONTENT_TYPE attribute describes "what" you are playing.

It expresses the general category of the content. This information is optional. But in case it is known (for instance AAUDIO_CONTENT_TYPE_MOVIE for a movie streaming service or AAUDIO_CONTENT_TYPE_SPEECH for an audio book application) this information might be used by the audio framework to enforce audio focus.

Note that these match the equivalent values in AudioAttributes in the Android Java API.

Added in API level 28.

Properties
AAUDIO_CONTENT_TYPE_MOVIE

Use this for a movie or video soundtrack.

AAUDIO_CONTENT_TYPE_MUSIC

Use this for pre-recorded or live music.

AAUDIO_CONTENT_TYPE_SONIFICATION

Use this for sound is designed to accompany a user action, such as a click or beep sound made when the user presses a button.

AAUDIO_CONTENT_TYPE_SPEECH

Use this for spoken voice, audio books, etcetera.

Anonymous Enum 8

 Anonymous Enum 8

Defines the audio source.

An audio source defines both a default physical source of audio signal, and a recording configuration.

Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API.

Added in API level 28.

Properties
AAUDIO_INPUT_PRESET_CAMCORDER

Use this preset when recording video.

AAUDIO_INPUT_PRESET_GENERIC

Use this preset when other presets do not apply.

AAUDIO_INPUT_PRESET_UNPROCESSED

Use this preset to obtain an input with no effects.

Note that this input will not have automatic gain control so the recorded volume may be very low.

AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION

Use this preset when doing telephony or voice messaging.

AAUDIO_INPUT_PRESET_VOICE_RECOGNITION

Use this preset when doing speech recognition.

Anonymous Enum 9

 Anonymous Enum 9

These may be used with AAudioStreamBuilder_setSessionId().

Added in API level 28.

Properties
AAUDIO_SESSION_ID_ALLOCATE

Allocate a session ID that can be used to attach and control effects using the Java AudioEffects API.

Note that using this may result in higher latency.

Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE.

Added in API level 28.

AAUDIO_SESSION_ID_NONE

Do not allocate a session ID.

Effects cannot be used with this stream. Default.

Added in API level 28.

Typedefs

AAudioStream

struct AAudioStreamStruct AAudioStream

AAudioStreamBuilder

struct AAudioStreamBuilderStruct AAudioStreamBuilder

AAudioStream_dataCallback

aaudio_data_callback_result_t(* AAudioStream_dataCallback)(AAudioStream *stream, void *userData, void *audioData, int32_t numFrames)

Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback().

For an output stream, this function should render and write numFrames of data in the streams current data format to the audioData buffer.

For an input stream, this function should read and process numFrames of data from the audioData buffer.

The audio data is passed through the buffer. So do NOT call AAudioStream_read() or AAudioStream_write() on the stream that is making the callback.

Note that numFrames can vary unless AAudioStreamBuilder_setFramesPerDataCallback() is called.

Also note that this callback function should be considered a "real-time" function. It must not do anything that could cause an unbounded delay because that can cause the audio to glitch or pop.

These are things the function should NOT do:

  • allocate memory using, for example, malloc() or new
  • any file operations such as opening, closing, reading or writing
  • any network operations such as streaming
  • use any mutexes or other synchronization primitives
  • sleep
  • stop or close the stream
  • AAudioStream_read()
  • AAudioStream_write()

The following are OK to call from the data callback:

If you need to move data, eg. MIDI commands, in or out of the callback function then we recommend the use of non-blocking techniques such as an atomic FIFO.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
userData
the same address that was passed to AAudioStreamBuilder_setCallback()
audioData
a pointer to the audio data
numFrames
the number of frames to be processed, which can vary
Returns
AAUDIO_CALLBACK_RESULT_*

AAudioStream_errorCallback

void(* AAudioStream_errorCallback)(AAudioStream *stream, void *userData, aaudio_result_t error)

Prototype for the callback function that is passed to AAudioStreamBuilder_setErrorCallback().

The following may NOT be called from the error callback:

The following are OK to call from the error callback:

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
userData
the same address that was passed to AAudioStreamBuilder_setErrorCallback()
error
an AAUDIO_ERROR_* value.

aaudio_content_type_t

int32_t aaudio_content_type_t

aaudio_data_callback_result_t

int32_t aaudio_data_callback_result_t

aaudio_direction_t

int32_t aaudio_direction_t

aaudio_format_t

int32_t aaudio_format_t

aaudio_input_preset_t

int32_t aaudio_input_preset_t

aaudio_performance_mode_t

int32_t aaudio_performance_mode_t

aaudio_result_t

int32_t aaudio_result_t

aaudio_session_id_t

int32_t aaudio_session_id_t

aaudio_sharing_mode_t

int32_t aaudio_sharing_mode_t

aaudio_stream_state_t

int32_t aaudio_stream_state_t

aaudio_usage_t

int32_t aaudio_usage_t

Functions

AAudioStreamBuilder_delete

AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(
  AAudioStreamBuilder *builder
)

Delete the resources associated with the StreamBuilder.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
Returns
AAUDIO_OK or a negative error.

AAudioStreamBuilder_openStream

AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(
  AAudioStreamBuilder *builder,
  AAudioStream **stream
)

Open a stream based on the options in the StreamBuilder.

AAudioStream_close must be called when finished with the stream to recover the memory and to free the associated resources.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
stream
pointer to a variable to receive the new stream reference
Returns
AAUDIO_OK or a negative error.

AAudioStreamBuilder_setBufferCapacityInFrames

AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(
  AAudioStreamBuilder *builder,
  int32_t numFrames
)

Set the requested buffer capacity in frames.

The final AAudioStream capacity may differ, but will probably be at least this big.

The default, if you do not call this function, is AAUDIO_UNSPECIFIED.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
numFrames
the desired buffer capacity in frames or AAUDIO_UNSPECIFIED

AAudioStreamBuilder_setChannelCount

AAUDIO_API void AAudioStreamBuilder_setChannelCount(
  AAudioStreamBuilder *builder,
  int32_t channelCount
)

Request a number of channels for the stream.

The default, if you do not call this function, is AAUDIO_UNSPECIFIED. An optimal value will then be chosen when the stream is opened. After opening a stream with an unspecified value, the application must query for the actual value, which may vary by device.

If an exact value is specified then an opened stream will use that value. If a stream cannot be opened with the specified value then the open will fail.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
channelCount
Number of channels desired.

AAudioStreamBuilder_setContentType

AAUDIO_API void AAudioStreamBuilder_setContentType(
  AAudioStreamBuilder *builder,
  aaudio_content_type_t contentType
)

Set the type of audio data that the stream will carry.

The AAudio system will use this information to optimize the behavior of the stream. This could, for example, affect whether a stream is paused when a notification occurs.

The default, if you do not call this function, is AAUDIO_CONTENT_TYPE_MUSIC.

Added in API level 28.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
contentType
the type of audio data, eg. AAUDIO_CONTENT_TYPE_SPEECH

AAudioStreamBuilder_setDataCallback

AAUDIO_API void AAudioStreamBuilder_setDataCallback(
  AAudioStreamBuilder *builder,
  AAudioStream_dataCallback callback,
  void *userData
)

Request that AAudio call this functions when the stream is running.

Note that when using this callback, the audio data will be passed in or out of the function as an argument. So you cannot call AAudioStream_write() or AAudioStream_read() on the same stream that has an active data callback.

The callback function will start being called after AAudioStream_requestStart() is called. It will stop being called after AAudioStream_requestPause() or AAudioStream_requestStop() is called.

This callback function will be called on a real-time thread owned by AAudio. See AAudioStream_dataCallback for more information.

Note that the AAudio callbacks will never be called simultaneously from multiple threads.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
callback
pointer to a function that will process audio data.
userData
pointer to an application data structure that will be passed to the callback functions.

AAudioStreamBuilder_setDeviceId

AAUDIO_API void AAudioStreamBuilder_setDeviceId(
  AAudioStreamBuilder *builder,
  int32_t deviceId
)

Request an audio device identified device using an ID.

On Android, for example, the ID could be obtained from the Java AudioManager.

The default, if you do not call this function, is AAUDIO_UNSPECIFIED, in which case the primary device will be used.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
deviceId
device identifier or AAUDIO_UNSPECIFIED

AAudioStreamBuilder_setDirection

AAUDIO_API void AAudioStreamBuilder_setDirection(
  AAudioStreamBuilder *builder,
  aaudio_direction_t direction
)

Request the direction for a stream.

The default, if you do not call this function, is AAUDIO_DIRECTION_OUTPUT.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
direction
AAUDIO_DIRECTION_OUTPUT or AAUDIO_DIRECTION_INPUT

AAudioStreamBuilder_setErrorCallback

AAUDIO_API void AAudioStreamBuilder_setErrorCallback(
  AAudioStreamBuilder *builder,
  AAudioStream_errorCallback callback,
  void *userData
)

Request that AAudio call this function if any error occurs or the stream is disconnected.

It will be called, for example, if a headset or a USB device is unplugged causing the stream's device to be unavailable or "disconnected". Another possible cause of error would be a timeout or an unanticipated internal error.

In response, this function should signal or create another thread to stop and close this stream. The other thread could then reopen a stream on another device. Do not stop or close the stream, or reopen the new stream, directly from this callback.

This callback will not be called because of actions by the application, such as stopping or closing a stream.

Note that the AAudio callbacks will never be called simultaneously from multiple threads.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
callback
pointer to a function that will be called if an error occurs.
userData
pointer to an application data structure that will be passed to the callback functions.

AAudioStreamBuilder_setFormat

AAUDIO_API void AAudioStreamBuilder_setFormat(
  AAudioStreamBuilder *builder,
  aaudio_format_t format
)

Request a sample data format, for example AAUDIO_FORMAT_PCM_I16.

The default, if you do not call this function, is AAUDIO_UNSPECIFIED. An optimal value will then be chosen when the stream is opened. After opening a stream with an unspecified value, the application must query for the actual value, which may vary by device.

If an exact value is specified then an opened stream will use that value. If a stream cannot be opened with the specified value then the open will fail.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
format
common formats are AAUDIO_FORMAT_PCM_FLOAT and AAUDIO_FORMAT_PCM_I16.

AAudioStreamBuilder_setFramesPerDataCallback

AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(
  AAudioStreamBuilder *builder,
  int32_t numFrames
)

Set the requested data callback buffer size in frames.

See AAudioStream_dataCallback.

The default, if you do not call this function, is AAUDIO_UNSPECIFIED.

For the lowest possible latency, do not call this function. AAudio will then call the dataProc callback function with whatever size is optimal. That size may vary from one callback to another.

Only use this function if the application requires a specific number of frames for processing. The application might, for example, be using an FFT that requires a specific power-of-two sized buffer.

AAudio may need to add additional buffering in order to adapt between the internal buffer size and the requested buffer size.

If you do call this function then the requested size should be less than half the buffer capacity, to allow double buffering.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
numFrames
the desired buffer size in frames or AAUDIO_UNSPECIFIED

AAudioStreamBuilder_setInputPreset

AAUDIO_API void AAudioStreamBuilder_setInputPreset(
  AAudioStreamBuilder *builder,
  aaudio_input_preset_t inputPreset
)

Set the input (capture) preset for the stream.

The AAudio system will use this information to optimize the behavior of the stream. This could, for example, affect which microphones are used and how the recorded data is processed.

The default, if you do not call this function, is AAUDIO_INPUT_PRESET_VOICE_RECOGNITION. That is because VOICE_RECOGNITION is the preset with the lowest latency on many platforms.

Added in API level 28.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
inputPreset
the desired configuration for recording

AAudioStreamBuilder_setPerformanceMode

AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(
  AAudioStreamBuilder *builder,
  aaudio_performance_mode_t mode
)

Set the requested performance mode.

Supported modes are AAUDIO_PERFORMANCE_MODE_NONE, AAUDIO_PERFORMANCE_MODE_POWER_SAVING and AAUDIO_PERFORMANCE_MODE_LOW_LATENCY.

The default, if you do not call this function, is AAUDIO_PERFORMANCE_MODE_NONE.

You may not get the mode you requested. You can call AAudioStream_getPerformanceMode() to find out the final mode for the stream.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
mode
the desired performance mode, eg. AAUDIO_PERFORMANCE_MODE_LOW_LATENCY

AAudioStreamBuilder_setSampleRate

AAUDIO_API void AAudioStreamBuilder_setSampleRate(
  AAudioStreamBuilder *builder,
  int32_t sampleRate
)

Request a sample rate in Hertz.

The default, if you do not call this function, is AAUDIO_UNSPECIFIED. An optimal value will then be chosen when the stream is opened. After opening a stream with an unspecified value, the application must query for the actual value, which may vary by device.

If an exact value is specified then an opened stream will use that value. If a stream cannot be opened with the specified value then the open will fail.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
sampleRate
frames per second. Common rates include 44100 and 48000 Hz.

AAudioStreamBuilder_setSamplesPerFrame

AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(
  AAudioStreamBuilder *builder,
  int32_t samplesPerFrame
)

Identical to AAudioStreamBuilder_setChannelCount().

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
samplesPerFrame
Number of samples in a frame.

AAudioStreamBuilder_setSessionId

AAUDIO_API void AAudioStreamBuilder_setSessionId(
  AAudioStreamBuilder *builder,
  aaudio_session_id_t sessionId
)

Set the requested session ID.

The session ID can be used to associate a stream with effects processors. The effects are controlled using the Android AudioEffect Java API.

The default, if you do not call this function, is AAUDIO_SESSION_ID_NONE.

If set to AAUDIO_SESSION_ID_ALLOCATE then a session ID will be allocated when the stream is opened.

The allocated session ID can be obtained by calling AAudioStream_getSessionId() and then used with this function when opening another stream. This allows effects to be shared between streams.

Session IDs from AAudio can be used with the Android Java APIs and vice versa. So a session ID from an AAudio stream can be passed to Java and effects applied using the Java AudioEffect API.

Note that allocating or setting a session ID may result in a stream with higher latency.

Allocated session IDs will always be positive and nonzero.

Added in API level 28.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
sessionId
an allocated sessionID or AAUDIO_SESSION_ID_ALLOCATE

AAudioStreamBuilder_setSharingMode

AAUDIO_API void AAudioStreamBuilder_setSharingMode(
  AAudioStreamBuilder *builder,
  aaudio_sharing_mode_t sharingMode
)

Request a mode for sharing the device.

The default, if you do not call this function, is AAUDIO_SHARING_MODE_SHARED.

The requested sharing mode may not be available. The application can query for the actual mode after the stream is opened.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
sharingMode
AAUDIO_SHARING_MODE_SHARED or AAUDIO_SHARING_MODE_EXCLUSIVE

AAudioStreamBuilder_setUsage

AAUDIO_API void AAudioStreamBuilder_setUsage(
  AAudioStreamBuilder *builder,
  aaudio_usage_t usage
)

Set the intended use case for the stream.

The AAudio system will use this information to optimize the behavior of the stream. This could, for example, affect how volume and focus is handled for the stream.

The default, if you do not call this function, is AAUDIO_USAGE_MEDIA.

Added in API level 28.

Details
Parameters
builder
reference provided by AAudio_createStreamBuilder()
usage
the desired usage, eg. AAUDIO_USAGE_GAME

AAudioStream_close

AAUDIO_API aaudio_result_t AAudioStream_close(
  AAudioStream *stream
)

Free the resources associated with a stream created by AAudioStreamBuilder_openStream()

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
AAUDIO_OK or a negative error.

AAudioStream_getBufferCapacityInFrames

AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(
  AAudioStream *stream
)

Query maximum buffer capacity in frames.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
buffer capacity in frames

AAudioStream_getBufferSizeInFrames

AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(
  AAudioStream *stream
)

Query the maximum number of frames that can be filled without blocking.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
buffer size in frames.

AAudioStream_getChannelCount

AAUDIO_API int32_t AAudioStream_getChannelCount(
  AAudioStream *stream
)

A stream has one or more channels of data.

A frame will contain one sample for each channel.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
actual number of channels

AAudioStream_getContentType

AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(
  AAudioStream *stream
)

Return the content type for the stream.

Added in API level 28.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
content type, for example AAUDIO_CONTENT_TYPE_MUSIC

AAudioStream_getDeviceId

AAUDIO_API int32_t AAudioStream_getDeviceId(
  AAudioStream *stream
)

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
actual device ID

AAudioStream_getDirection

AAUDIO_API aaudio_direction_t AAudioStream_getDirection(
  AAudioStream *stream
)

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
direction

AAudioStream_getFormat

AAUDIO_API aaudio_format_t AAudioStream_getFormat(
  AAudioStream *stream
)

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
actual data format

AAudioStream_getFramesPerBurst

AAUDIO_API int32_t AAudioStream_getFramesPerBurst(
  AAudioStream *stream
)

Query the number of frames that the application should read or write at one time for optimal performance.

It is OK if an application writes a different number of frames. But the buffer size may need to be larger in order to avoid underruns or overruns.

Note that this may or may not match the actual device burst size. For some endpoints, the burst size can vary dynamically. But these tend to be devices with high latency.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
burst size

AAudioStream_getFramesPerDataCallback

AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(
  AAudioStream *stream
)

Query the size of the buffer that will be passed to the dataProc callback in the numFrames parameter.

This call can be used if the application needs to know the value of numFrames before the stream is started. This is not normally necessary.

If a specific size was requested by calling AAudioStreamBuilder_setFramesPerDataCallback() then this will be the same size.

If AAudioStreamBuilder_setFramesPerDataCallback() was not called then this will return the size chosen by AAudio, or AAUDIO_UNSPECIFIED.

AAUDIO_UNSPECIFIED indicates that the callback buffer size for this stream may vary from one dataProc callback to the next.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
callback buffer size in frames or AAUDIO_UNSPECIFIED

AAudioStream_getFramesRead

AAUDIO_API int64_t AAudioStream_getFramesRead(
  AAudioStream *stream
)

Passes back the number of frames that have been read since the stream was created.

For an output stream, this will be advanced by the endpoint. For an input stream, this will be advanced by the application calling read() or by a data callback.

The frame position is monotonically increasing.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
frames read

AAudioStream_getFramesWritten

AAUDIO_API int64_t AAudioStream_getFramesWritten(
  AAudioStream *stream
)

Passes back the number of frames that have been written since the stream was created.

For an output stream, this will be advanced by the application calling write() or by a data callback. For an input stream, this will be advanced by the endpoint.

The frame position is monotonically increasing.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
frames written

AAudioStream_getInputPreset

AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(
  AAudioStream *stream
)

Return the input preset for the stream.

Added in API level 28.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
input preset, for example AAUDIO_INPUT_PRESET_CAMCORDER

AAudioStream_getPerformanceMode

AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(
  AAudioStream *stream
)

Get the performance mode used by the stream.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()

AAudioStream_getSampleRate

AAUDIO_API int32_t AAudioStream_getSampleRate(
  AAudioStream *stream
)

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
actual sample rate

AAudioStream_getSamplesPerFrame

AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(
  AAudioStream *stream
)

Identical to AAudioStream_getChannelCount().

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
actual number of samples frame

AAudioStream_getSessionId

AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(
  AAudioStream *stream
)

Passes back the session ID associated with this stream.

The session ID can be used to associate a stream with effects processors. The effects are controlled using the Android AudioEffect Java API.

If AAudioStreamBuilder_setSessionId() was called with AAUDIO_SESSION_ID_ALLOCATE then a new session ID should be allocated once when the stream is opened.

If AAudioStreamBuilder_setSessionId() was called with a previously allocated session ID then that value should be returned.

If AAudioStreamBuilder_setSessionId() was not called then this function should return AAUDIO_SESSION_ID_NONE.

The sessionID for a stream should not change once the stream has been opened.

Added in API level 28.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
session ID or AAUDIO_SESSION_ID_NONE

AAudioStream_getSharingMode

AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(
  AAudioStream *stream
)

Provide actual sharing mode.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
actual sharing mode

AAudioStream_getState

AAUDIO_API aaudio_stream_state_t AAudioStream_getState(
  AAudioStream *stream
)

Query the current state of the client, eg.

AAUDIO_STREAM_STATE_PAUSING

This function will immediately return the state without updating the state. If you want to update the client state based on the server state then call AAudioStream_waitForStateChange() with currentState set to AAUDIO_STREAM_STATE_UNKNOWN and a zero timeout.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()

AAudioStream_getTimestamp

AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(
  AAudioStream *stream,
  clockid_t clockid,
  int64_t *framePosition,
  int64_t *timeNanoseconds
)

Passes back the time at which a particular frame was presented.

This can be used to synchronize audio with video or MIDI. It can also be used to align a recorded stream with a playback stream.

Timestamps are only valid when the stream is in AAUDIO_STREAM_STATE_STARTED. AAUDIO_ERROR_INVALID_STATE will be returned if the stream is not started. Note that because requestStart() is asynchronous, timestamps will not be valid until a short time after calling requestStart(). So AAUDIO_ERROR_INVALID_STATE should not be considered a fatal error. Just try calling again later.

If an error occurs, then the position and time will not be modified.

The position and time passed back are monotonically increasing.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
clockid
CLOCK_MONOTONIC or CLOCK_BOOTTIME
framePosition
pointer to a variable to receive the position
timeNanoseconds
pointer to a variable to receive the time
Returns
AAUDIO_OK or a negative error

AAudioStream_getUsage

AAUDIO_API aaudio_usage_t AAudioStream_getUsage(
  AAudioStream *stream
)

Return the use case for the stream.

Added in API level 28.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
frames read

AAudioStream_getXRunCount

AAUDIO_API int32_t AAudioStream_getXRunCount(
  AAudioStream *stream
)

An XRun is an Underrun or an Overrun.

During playing, an underrun will occur if the stream is not written in time and the system runs out of valid data. During recording, an overrun will occur if the stream is not read in time and there is no place to put the incoming data so it is discarded.

An underrun or overrun can cause an audible "pop" or "glitch".

Note that some INPUT devices may not support this function. In that case a 0 will always be returned.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
the underrun or overrun count

AAudioStream_read

AAUDIO_API aaudio_result_t AAudioStream_read(
  AAudioStream *stream,
  void *buffer,
  int32_t numFrames,
  int64_t timeoutNanoseconds
)

Read data from the stream.

The call will wait until the read is complete or until it runs out of time. If timeoutNanos is zero then this call will not wait.

Note that timeoutNanoseconds is a relative duration in wall clock time. Time will not stop if the thread is asleep. So it will be implemented using CLOCK_BOOTTIME.

This call is "strong non-blocking" unless it has to wait for data.

If the call times out then zero or a partial frame count will be returned.

Details
Parameters
stream
A stream created using AAudioStreamBuilder_openStream().
buffer
The address of the first sample.
numFrames
Number of frames to read. Only complete frames will be written.
timeoutNanoseconds
Maximum number of nanoseconds to wait for completion.
Returns
The number of frames actually read or a negative error.

AAudioStream_requestFlush

AAUDIO_API aaudio_result_t AAudioStream_requestFlush(
  AAudioStream *stream
)

Asynchronous request for the stream to flush.

Flushing will discard any pending data. This call only works if the stream is pausing or paused. TODO review Frame counters are not reset by a flush. They may be advanced. After this call the state will be in AAUDIO_STREAM_STATE_FLUSHING or AAUDIO_STREAM_STATE_FLUSHED.

This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
AAUDIO_OK or a negative error.

AAudioStream_requestPause

AAUDIO_API aaudio_result_t AAudioStream_requestPause(
  AAudioStream *stream
)

Asynchronous request for the stream to pause.

Pausing a stream will freeze the data flow but not flush any buffers. Use AAudioStream_Start() to resume playback after a pause. After this call the state will be in AAUDIO_STREAM_STATE_PAUSING or AAUDIO_STREAM_STATE_PAUSED.

This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams. For input streams use AAudioStream_requestStop().

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
AAUDIO_OK or a negative error.

AAudioStream_requestStart

AAUDIO_API aaudio_result_t AAudioStream_requestStart(
  AAudioStream *stream
)

Asynchronously request to start playing the stream.

For output streams, one should write to the stream to fill the buffer before starting. Otherwise it will underflow. After this call the state will be in AAUDIO_STREAM_STATE_STARTING or AAUDIO_STREAM_STATE_STARTED.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
AAUDIO_OK or a negative error.

AAudioStream_requestStop

AAUDIO_API aaudio_result_t AAudioStream_requestStop(
  AAudioStream *stream
)

Asynchronous request for the stream to stop.

The stream will stop after all of the data currently buffered has been played. After this call the state will be in AAUDIO_STREAM_STATE_STOPPING or AAUDIO_STREAM_STATE_STOPPED.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
Returns
AAUDIO_OK or a negative error.

AAudioStream_setBufferSizeInFrames

AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(
  AAudioStream *stream,
  int32_t numFrames
)

This can be used to adjust the latency of the buffer by changing the threshold where blocking will occur.

By combining this with AAudioStream_getXRunCount(), the latency can be tuned at run-time for each device.

This cannot be set higher than AAudioStream_getBufferCapacityInFrames().

Note that you will probably not get the exact size you request. You can check the return value or call AAudioStream_getBufferSizeInFrames() to see what the actual final size is.

Details
Parameters
stream
reference provided by AAudioStreamBuilder_openStream()
numFrames
requested number of frames that can be filled without blocking
Returns
actual buffer size in frames or a negative error

AAudioStream_waitForStateChange

AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(
  AAudioStream *stream,
  aaudio_stream_state_t inputState,
  aaudio_stream_state_t *nextState,
  int64_t timeoutNanoseconds
)

Wait until the current state no longer matches the input state.

This will update the current client state.


aaudio_result_t result = AAUDIO_OK;
aaudio_stream_state_t currentState = AAudioStream_getState(stream);
aaudio_stream_state_t inputState = currentState;
while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSED) {
    result = AAudioStream_waitForStateChange(
                                  stream, inputState, ¤tState, MY_TIMEOUT_NANOS);
    inputState = currentState;
}

Details
Parameters
stream
A reference provided by AAudioStreamBuilder_openStream()
inputState
The state we want to avoid.
nextState
Pointer to a variable that will be set to the new state.
timeoutNanoseconds
Maximum number of nanoseconds to wait for completion.
Returns
AAUDIO_OK or a negative error.

AAudioStream_write

AAUDIO_API aaudio_result_t AAudioStream_write(
  AAudioStream *stream,
  const void *buffer,
  int32_t numFrames,
  int64_t timeoutNanoseconds
)

Write data to the stream.

The call will wait until the write is complete or until it runs out of time. If timeoutNanos is zero then this call will not wait.

Note that timeoutNanoseconds is a relative duration in wall clock time. Time will not stop if the thread is asleep. So it will be implemented using CLOCK_BOOTTIME.

This call is "strong non-blocking" unless it has to wait for room in the buffer.

If the call times out then zero or a partial frame count will be returned.

Details
Parameters
stream
A stream created using AAudioStreamBuilder_openStream().
buffer
The address of the first sample.
numFrames
Number of frames to write. Only complete frames will be written.
timeoutNanoseconds
Maximum number of nanoseconds to wait for completion.
Returns
The number of frames actually written or a negative error.

AAudio_convertResultToText

AAUDIO_API const char * AAudio_convertResultToText(
  aaudio_result_t returnCode
)

The text is the ASCII symbol corresponding to the returnCode, or an English message saying the returnCode is unrecognized.

This is intended for developers to use when debugging. It is not for display to users.

Details
Returns
pointer to a text representation of an AAudio result code.

AAudio_convertStreamStateToText

AAUDIO_API const char * AAudio_convertStreamStateToText(
  aaudio_stream_state_t state
)

The text is the ASCII symbol corresponding to the stream state, or an English message saying the state is unrecognized.

This is intended for developers to use when debugging. It is not for display to users.

Details
Returns
pointer to a text representation of an AAudio state.

AAudio_createStreamBuilder

AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(
  AAudioStreamBuilder **builder
)

Create a StreamBuilder that can be used to open a Stream.

The deviceId is initially unspecified, meaning that the current default device will be used.

The default direction is AAUDIO_DIRECTION_OUTPUT. The default sharing mode is AAUDIO_SHARING_MODE_SHARED. The data format, samplesPerFrames and sampleRate are unspecified and will be chosen by the device when it is opened.

AAudioStreamBuilder_delete() must be called when you are done using the builder.