Audio
#include <AAudio.h>
Summary
Enumerations |
|
|---|---|
Anonymous Enum 0{
|
enum |
Anonymous Enum 1{
|
enum |
Anonymous Enum 10{
|
enum Specifying if audio may or may not be captured by other apps or the system. |
Anonymous Enum 11{
|
enum These may be used with AAudioStreamBuilder_setSessionId(). |
Anonymous Enum 12{
|
enum Defines the audio channel mask. |
Anonymous Enum 13{
|
enum Return one of these values from the data callback function. |
Anonymous Enum 2{
|
enum These result codes are returned from AAudio functions to indicate success or failure. |
Anonymous Enum 3{
|
enum AAudio Stream states, for details, refer to Using an Audio Stream |
Anonymous Enum 4{
|
enum |
Anonymous Enum 5{
|
enum |
Anonymous Enum 6{
|
enum The USAGE attribute expresses "why" you are playing a sound, what is this sound used for. |
Anonymous Enum 7{
|
enum The CONTENT_TYPE attribute describes "what" you are playing. |
Anonymous Enum 8{
|
enum |
Anonymous Enum 9{
|
enum Defines the audio source. |
Typedefs |
|
|---|---|
AAudioStream
|
typedefstruct AAudioStreamStruct
|
AAudioStreamBuilder
|
typedefstruct AAudioStreamBuilderStruct
|
AAudioStream_dataCallback)(AAudioStream *_Nonnull stream, void *_Nullable userData, void *_Nonnull audioData, int32_t numFrames)
|
typedefaaudio_data_callback_result_t(*
Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback(). |
AAudioStream_errorCallback)(AAudioStream *_Nonnull stream, void *_Nullable userData, aaudio_result_t error)
|
typedefvoid(*
Prototype for the callback function that is passed to AAudioStreamBuilder_setErrorCallback(). |
aaudio_allowed_capture_policy_t
|
typedefint32_t
|
aaudio_channel_mask_t
|
typedefuint32_t
|
aaudio_content_type_t
|
typedefint32_t
|
aaudio_data_callback_result_t
|
typedefint32_t
|
aaudio_direction_t
|
typedefint32_t
|
aaudio_format_t
|
typedefint32_t
|
aaudio_input_preset_t
|
typedefint32_t
|
aaudio_performance_mode_t
|
typedefint32_t
|
aaudio_result_t
|
typedefint32_t
|
aaudio_session_id_t
|
typedefint32_t
|
aaudio_sharing_mode_t
|
typedefint32_t
|
aaudio_spatialization_behavior_t
|
typedefint32_t
|
aaudio_stream_state_t
|
typedefint32_t
|
aaudio_usage_t
|
typedefint32_t
|
Functions |
|
|---|---|
AAudioStreamBuilder_delete(AAudioStreamBuilder *_Nonnull builder)
|
AAUDIO_API aaudio_result_t
Delete the resources associated with the StreamBuilder.
|
AAudioStreamBuilder_openStream(AAudioStreamBuilder *_Nonnull builder, AAudioStream *_Nullable *_Nonnull stream)
|
AAUDIO_API aaudio_result_t
Open a stream based on the options in the StreamBuilder.
|
AAudioStreamBuilder_setAllowedCapturePolicy(AAudioStreamBuilder *_Nonnull builder, aaudio_allowed_capture_policy_t capturePolicy)
|
AAUDIO_API void
Specify whether this stream audio may or may not be captured by other apps or the system.
|
AAudioStreamBuilder_setAttributionTag(AAudioStreamBuilder *_Nonnull builder, const char *_Nonnull attributionTag)
|
AAUDIO_API void
Declare the attribution tag of the context creating the stream.
|
AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder *_Nonnull builder, int32_t numFrames)
|
AAUDIO_API void
Set the requested buffer capacity in frames.
|
AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder *_Nonnull builder, int32_t channelCount)
|
AAUDIO_API void
Request a number of channels for the stream.
|
AAudioStreamBuilder_setChannelMask(AAudioStreamBuilder *_Nonnull builder, aaudio_channel_mask_t channelMask)
|
AAUDIO_API void
Set audio channel mask for the stream.
|
AAudioStreamBuilder_setContentType(AAudioStreamBuilder *_Nonnull builder, aaudio_content_type_t contentType)
|
AAUDIO_API void
Set the type of audio data that the output stream will carry.
|
AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder *_Nonnull builder, AAudioStream_dataCallback _Nullable callback, void *_Nullable userData)
|
AAUDIO_API void
Request that AAudio call this functions when the stream is running.
|
AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder *_Nonnull builder, int32_t deviceId)
|
AAUDIO_API void
Request an audio device identified by an ID.
|
AAudioStreamBuilder_setDirection(AAudioStreamBuilder *_Nonnull builder, aaudio_direction_t direction)
|
AAUDIO_API void
Request the direction for a stream.
|
AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder *_Nonnull builder, AAudioStream_errorCallback _Nullable callback, void *_Nullable userData)
|
AAUDIO_API void
Request that AAudio call this function if any error occurs or the stream is disconnected.
|
AAudioStreamBuilder_setFormat(AAudioStreamBuilder *_Nonnull builder, aaudio_format_t format)
|
AAUDIO_API void
Request a sample data format, for example AAUDIO_FORMAT_PCM_I16.
|
AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder *_Nonnull builder, int32_t numFrames)
|
AAUDIO_API void
Set the requested data callback buffer size in frames.
|
AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder *_Nonnull builder, aaudio_input_preset_t inputPreset)
|
AAUDIO_API void
Set the input (capture) preset for the stream.
|
AAudioStreamBuilder_setIsContentSpatialized(AAudioStreamBuilder *_Nonnull builder, bool isSpatialized)
|
AAUDIO_API void
Specifies whether the audio data of this output stream has already been processed for spatialization.
|
AAudioStreamBuilder_setPackageName(AAudioStreamBuilder *_Nonnull builder, const char *_Nonnull packageName)
|
AAUDIO_API void
Declare the name of the package creating the stream.
|
AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder *_Nonnull builder, aaudio_performance_mode_t mode)
|
AAUDIO_API void
Set the requested performance mode.
|
AAudioStreamBuilder_setPrivacySensitive(AAudioStreamBuilder *_Nonnull builder, bool privacySensitive)
|
AAUDIO_API void
Indicates whether this input stream must be marked as privacy sensitive or not.
|
AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder *_Nonnull builder, int32_t sampleRate)
|
AAUDIO_API void
Request a sample rate in Hertz.
|
AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder *_Nonnull builder, int32_t samplesPerFrame)
|
AAUDIO_API void
Identical to AAudioStreamBuilder_setChannelCount(). |
AAudioStreamBuilder_setSessionId(AAudioStreamBuilder *_Nonnull builder, aaudio_session_id_t sessionId)
|
AAUDIO_API void
Set the requested session ID.
|
AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder *_Nonnull builder, aaudio_sharing_mode_t sharingMode)
|
AAUDIO_API void
Request a mode for sharing the device.
|
AAudioStreamBuilder_setSpatializationBehavior(AAudioStreamBuilder *_Nonnull builder, aaudio_spatialization_behavior_t spatializationBehavior)
|
AAUDIO_API void
Sets the behavior affecting whether spatialization will be used.
|
AAudioStreamBuilder_setUsage(AAudioStreamBuilder *_Nonnull builder, aaudio_usage_t usage)
|
AAUDIO_API void
Set the intended use case for the output stream.
|
AAudioStream_close(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_result_t
Delete the internal data structures associated with the stream created by AAudioStreamBuilder_openStream().
|
AAudioStream_getAllowedCapturePolicy(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_allowed_capture_policy_t
Return the policy that determines whether the audio may or may not be captured by other apps or the system.
|
AAudioStream_getBufferCapacityInFrames(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
Query maximum buffer capacity in frames.
|
AAudioStream_getBufferSizeInFrames(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
Query the maximum number of frames that can be filled without blocking.
|
AAudioStream_getChannelCount(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
A stream has one or more channels of data.
|
AAudioStream_getChannelMask(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_channel_mask_t
Return the channel mask for the stream.
|
AAudioStream_getContentType(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_content_type_t
Return the content type for the stream.
|
AAudioStream_getDeviceId(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
Available since API level 26.
|
AAudioStream_getDirection(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_direction_t
Available since API level 26.
|
AAudioStream_getFormat(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_format_t
Available since API level 26.
|
AAudioStream_getFramesPerBurst(AAudioStream *_Nonnull 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 *_Nonnull 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 *_Nonnull stream)
|
AAUDIO_API int64_t
Passes back the number of frames that have been read since the stream was created.
|
AAudioStream_getFramesWritten(AAudioStream *_Nonnull stream)
|
AAUDIO_API int64_t
Passes back the number of frames that have been written since the stream was created.
|
AAudioStream_getHardwareChannelCount(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
There may be channel conversions in the Audio framework.
|
AAudioStream_getHardwareFormat(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_format_t
There may be data format conversions in the Audio framework.
|
AAudioStream_getHardwareSampleRate(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
There may be sample rate conversions in the Audio framework.
|
AAudioStream_getInputPreset(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_input_preset_t
Return the input preset for the stream.
|
AAudioStream_getPerformanceMode(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_performance_mode_t
Get the performance mode used by the stream.
|
AAudioStream_getSampleRate(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
Available since API level 26.
|
AAudioStream_getSamplesPerFrame(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
Identical to AAudioStream_getChannelCount().
|
AAudioStream_getSessionId(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_session_id_t
Passes back the session ID associated with this stream.
|
AAudioStream_getSharingMode(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_sharing_mode_t
Provide actual sharing mode.
|
AAudioStream_getSpatializationBehavior(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_spatialization_behavior_t
Return the spatialization behavior for the stream.
|
AAudioStream_getState(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_stream_state_t
Query the current state of the client, eg.
|
AAudioStream_getTimestamp(AAudioStream *_Nonnull stream, clockid_t clockid, int64_t *_Nonnull framePosition, int64_t *_Nonnull timeNanoseconds)
|
AAUDIO_API aaudio_result_t
Returns the time at which a particular frame was played on a speaker or headset, or was recorded on a microphone.
|
AAudioStream_getUsage(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_usage_t
Return the use case for the stream.
|
AAudioStream_getXRunCount(AAudioStream *_Nonnull stream)
|
AAUDIO_API int32_t
An XRun is an Underrun or an Overrun.
|
AAudioStream_isContentSpatialized(AAudioStream *_Nonnull stream)
|
AAUDIO_API bool
Return whether the content of the stream is spatialized.
|
AAudioStream_isPrivacySensitive(AAudioStream *_Nonnull stream)
|
AAUDIO_API bool
Return whether this input stream is marked as privacy sensitive or not.
|
AAudioStream_read(AAudioStream *_Nonnull stream, void *_Nonnull buffer, int32_t numFrames, int64_t timeoutNanoseconds)
|
AAUDIO_API aaudio_result_t
Read data from the stream.
|
AAudioStream_release(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_result_t
Free the audio resources associated with a stream created by AAudioStreamBuilder_openStream().
|
AAudioStream_requestFlush(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_result_t
Asynchronous request for the stream to flush.
|
AAudioStream_requestPause(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_result_t
Asynchronous request for the stream to pause.
|
AAudioStream_requestStart(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_result_t
Asynchronously request to start playing the stream.
|
AAudioStream_requestStop(AAudioStream *_Nonnull stream)
|
AAUDIO_API aaudio_result_t
Asynchronous request for the stream to stop.
|
AAudioStream_setBufferSizeInFrames(AAudioStream *_Nonnull 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 *_Nonnull stream, aaudio_stream_state_t inputState, aaudio_stream_state_t *_Nullable nextState, int64_t timeoutNanoseconds)
|
AAUDIO_API aaudio_result_t
Wait until the current state no longer matches the input state.
|
AAudioStream_write(AAudioStream *_Nonnull stream, const void *_Nonnull 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 *_Nonnull
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 *_Nonnull
The text is the ASCII symbol corresponding to the stream state, or an English message saying the state is unrecognized.
|
AAudio_createStreamBuilder(AAudioStreamBuilder *_Nullable *_Nonnull builder)
|
AAUDIO_API aaudio_result_t
Create a StreamBuilder that can be used to open a Stream.
|
Enumerations
Anonymous Enum 0
Anonymous Enum 0
Anonymous Enum 1
Anonymous Enum 1
| Properties | |
|---|---|
AAUDIO_FORMAT_IEC61937
|
This format is used for compressed audio wrapped in IEC61937 for HDMI or S/PDIF passthrough. Unlike PCM playback, the Android framework is not able to do format conversion for IEC61937. In that case, when IEC61937 is requested, sampling rate and channel count or channel mask must be specified. Otherwise, it may fail when opening the stream. Apps are able to get the correct configuration for the playback by calling AudioManager::getDevices(int). Available since API level 34. |
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 the float Data in write(float[], int, int, int). |
AAUDIO_FORMAT_PCM_I16
|
This format uses the int16_t data type. The maximum range of the data is -32768 (0x8000) to 32767 (0x7FFF). |
AAUDIO_FORMAT_PCM_I24_PACKED
|
This format uses 24-bit samples packed into 3 bytes. The bytes are in little-endian order, so the least significant byte comes first in the byte array. The maximum range of the data is -8388608 (0x800000) to 8388607 (0x7FFFFF). Note that the lower precision bits may be ignored by the device. Available since API level 31. |
AAUDIO_FORMAT_PCM_I32
|
This format uses 32-bit samples stored in an int32_t data type. The maximum range of the data is -2147483648 (0x80000000) to 2147483647 (0x7FFFFFFF). Note that the lower precision bits may be ignored by the device. Available since API level 31. |
AAUDIO_FORMAT_UNSPECIFIED
|
|
Anonymous Enum 10
Anonymous Enum 10
Specifying if audio may or may not be captured by other apps or the system.
Note that these match the equivalent values in AudioAttributes in the Android Java API.
Added in API level 29.
| Properties | |
|---|---|
AAUDIO_ALLOW_CAPTURE_BY_ALL
|
Indicates that the audio may be captured by any app. For privacy, the following usages can not be recorded: AAUDIO_VOICE_COMMUNICATION*, AAUDIO_USAGE_NOTIFICATION*, AAUDIO_USAGE_ASSISTANCE* and AAUDIO_USAGE_ASSISTANT. On Q, this means only AAUDIO_USAGE_MEDIA and AAUDIO_USAGE_GAME may be captured. See ALLOW_CAPTURE_BY_ALL. |
AAUDIO_ALLOW_CAPTURE_BY_NONE
|
Indicates that the audio may not be recorded by any app, even if it is a system app. It is encouraged to use AAUDIO_ALLOW_CAPTURE_BY_SYSTEM instead of this value as system apps provide significant and useful features for the user (eg. accessibility). See ALLOW_CAPTURE_BY_NONE. |
AAUDIO_ALLOW_CAPTURE_BY_SYSTEM
|
Indicates that the audio may only be captured by system apps. System apps can capture for many purposes like accessibility, user guidance... but have strong restriction. See ALLOW_CAPTURE_BY_SYSTEM for what the system apps can do with the capture audio. |
Anonymous Enum 11
Anonymous Enum 11
These may be used with AAudioStreamBuilder_setSessionId().
Added in API level 28.
Anonymous Enum 12
Anonymous Enum 12
Defines the audio channel mask.
Channel masks are used to describe the samples and their arrangement in the audio frame. They are also used in the endpoint (e.g. a USB audio interface, a DAC connected to headphones) to specify allowable configurations of a particular device.
Channel masks are for input only, output only, or both input and output. These channel masks are different than those defined in AudioFormat.java. If an app gets a channel mask from Java API and wants to use it in AAudio, conversion should be done by the app.
Added in API level 32.
Anonymous Enum 13
Anonymous Enum 13
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.
Anonymous Enum 3
Anonymous Enum 3
AAudio Stream states, for details, refer to Using an Audio Stream
Anonymous Enum 4
Anonymous Enum 4
Anonymous Enum 5
Anonymous Enum 5
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.
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.
Anonymous Enum 8
Anonymous Enum 8
Anonymous Enum 9
Anonymous Enum 9
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.
Typedefs
AAudioStream
struct AAudioStreamStruct AAudioStream
AAudioStreamBuilder
struct AAudioStreamBuilderStruct AAudioStreamBuilder
AAudioStream_dataCallback
aaudio_data_callback_result_t(* AAudioStream_dataCallback)(AAudioStream *_Nonnull stream, void *_Nullable userData, void *_Nonnull 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 data in the audioData buffer must not be modified directly. Instead, it should be copied to another buffer before doing any modification. In many cases, writing to the audioData buffer of an input stream will result in a native exception.
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:
- AAudioStream_get*()
- AAudio_convertResultToText()
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 |
|
||||||||
| Returns |
AAUDIO_CALLBACK_RESULT_*
|
AAudioStream_errorCallback
void(* AAudioStream_errorCallback)(AAudioStream *_Nonnull stream, void *_Nullable 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:
- AAudioStream_requestStop()
- AAudioStream_requestPause()
- AAudioStream_close()
- AAudioStream_waitForStateChange()
- AAudioStream_read()
- AAudioStream_write()
The following are OK to call from the error callback:
- AAudioStream_get*()
- AAudio_convertResultToText()
| Details | |||||||
|---|---|---|---|---|---|---|---|
| Parameters |
|
aaudio_allowed_capture_policy_t
int32_t aaudio_allowed_capture_policy_t
aaudio_channel_mask_t
uint32_t aaudio_channel_mask_t
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_spatialization_behavior_t
int32_t aaudio_spatialization_behavior_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 *_Nonnull builder )
Delete the resources associated with the StreamBuilder.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStreamBuilder_openStream
AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream( AAudioStreamBuilder *_Nonnull builder, AAudioStream *_Nullable *_Nonnull 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.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
||||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStreamBuilder_setAllowedCapturePolicy
AAUDIO_API void AAudioStreamBuilder_setAllowedCapturePolicy( AAudioStreamBuilder *_Nonnull builder, aaudio_allowed_capture_policy_t capturePolicy )
Specify whether this stream audio may or may not be captured by other apps or the system.
The default is AAUDIO_ALLOW_CAPTURE_BY_ALL.
Note that an application can also set its global policy, in which case the most restrictive policy is always applied. See setAllowedCapturePolicy(int)
Available since API level 29.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setAttributionTag
AAUDIO_API void AAudioStreamBuilder_setAttributionTag( AAudioStreamBuilder *_Nonnull builder, const char *_Nonnull attributionTag )
Declare the attribution tag of the context creating the stream.
This is usually
Context#getAttributionTag().
The default, if you do not call this function, is null.
Available since API level 31.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setBufferCapacityInFrames
AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames( AAudioStreamBuilder *_Nonnull 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.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setChannelCount
AAUDIO_API void AAudioStreamBuilder_setChannelCount( AAudioStreamBuilder *_Nonnull 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.
As the channel count provided here may be different from the corresponding channel count of channel mask used in AAudioStreamBuilder_setChannelMask, the last called function will be respected if both this function and AAudioStreamBuilder_setChannelMask are called.
Note that if the channel count is two then it may get mixed to mono when the device only supports one channel. If the channel count is greater than two but the device's supported channel count is less than the requested value, the channels higher than the device channel will be dropped. If higher channels should be mixed or spatialized, use AAudioStreamBuilder_setChannelMask instead.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setChannelMask
AAUDIO_API void AAudioStreamBuilder_setChannelMask( AAudioStreamBuilder *_Nonnull builder, aaudio_channel_mask_t channelMask )
Set audio channel mask for the stream.
The default, if you do not call this function, is AAUDIO_UNSPECIFIED. If both channel mask and count are not set, then stereo 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.
As the corresponding channel count of provided channel mask here may be different from the channel count used in AAudioStreamBuilder_setChannelCount or AAudioStreamBuilder_setSamplesPerFrame, the last called function will be respected if this function and AAudioStreamBuilder_setChannelCount or AAudioStreamBuilder_setSamplesPerFrame are called.
Available since API level 32.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setContentType
AAUDIO_API void AAudioStreamBuilder_setContentType( AAudioStreamBuilder *_Nonnull builder, aaudio_content_type_t contentType )
Set the type of audio data that the output 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.
Available since API level 28.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setDataCallback
AAUDIO_API void AAudioStreamBuilder_setDataCallback( AAudioStreamBuilder *_Nonnull builder, AAudioStream_dataCallback _Nullable callback, void *_Nullable 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. The low latency streams may have callback threads with higher priority than normal streams. See AAudioStream_dataCallback for more information.
Note that the AAudio callbacks will never be called simultaneously from multiple threads.
Available since API level 26.
| Details | |||||||
|---|---|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setDeviceId
AAUDIO_API void AAudioStreamBuilder_setDeviceId( AAudioStreamBuilder *_Nonnull builder, int32_t deviceId )
Request an audio device identified by an ID.
The ID could be obtained from the Java AudioManager. AudioManager.getDevices() returns an array of AudioDeviceInfo, which contains a getId() method. That ID can be passed to this function.
It is possible that you may not get the device that you requested. So if it is important to you, you should call AAudioStream_getDeviceId() after the stream is opened to verify the actual ID.
The default, if you do not call this function, is AAUDIO_UNSPECIFIED, in which case the primary device will be used.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setDirection
AAUDIO_API void AAudioStreamBuilder_setDirection( AAudioStreamBuilder *_Nonnull builder, aaudio_direction_t direction )
Request the direction for a stream.
The default, if you do not call this function, is AAUDIO_DIRECTION_OUTPUT.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setErrorCallback
AAUDIO_API void AAudioStreamBuilder_setErrorCallback( AAudioStreamBuilder *_Nonnull builder, AAudioStream_errorCallback _Nullable callback, void *_Nullable 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.
Available since API level 26.
| Details | |||||||
|---|---|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setFormat
AAUDIO_API void AAudioStreamBuilder_setFormat( AAudioStreamBuilder *_Nonnull 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.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setFramesPerDataCallback
AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback( AAudioStreamBuilder *_Nonnull 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.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setInputPreset
AAUDIO_API void AAudioStreamBuilder_setInputPreset( AAudioStreamBuilder *_Nonnull 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.
Available since API level 28.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setIsContentSpatialized
AAUDIO_API void AAudioStreamBuilder_setIsContentSpatialized( AAudioStreamBuilder *_Nonnull builder, bool isSpatialized )
Specifies whether the audio data of this output stream has already been processed for spatialization.
If the stream has been processed for spatialization, setting this to true will prevent issues such as double-processing on platforms that will spatialize audio data.
Available since API level 32.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setPackageName
AAUDIO_API void AAudioStreamBuilder_setPackageName( AAudioStreamBuilder *_Nonnull builder, const char *_Nonnull packageName )
Declare the name of the package creating the stream.
This is usually
Context#getPackageName().
The default, if you do not call this function, is a random package in the calling uid. The vast majority of apps have only one package per calling UID. If an invalid package name is set, input streams may not be given permission to record when started.
The package name is usually the applicationId in your app's build.gradle file.
Available since API level 31.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setPerformanceMode
AAUDIO_API void AAudioStreamBuilder_setPerformanceMode( AAudioStreamBuilder *_Nonnull 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.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setPrivacySensitive
AAUDIO_API void AAudioStreamBuilder_setPrivacySensitive( AAudioStreamBuilder *_Nonnull builder, bool privacySensitive )
Indicates whether this input stream must be marked as privacy sensitive or not.
When true, this input stream is privacy sensitive and any concurrent capture is not permitted.
This is off (false) by default except when the input preset is AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION or AAUDIO_INPUT_PRESET_CAMCORDER.
Always takes precedence over default from input preset when set explicitly.
Only relevant if the stream direction is AAUDIO_DIRECTION_INPUT.
Added in API level 30.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setSampleRate
AAUDIO_API void AAudioStreamBuilder_setSampleRate( AAudioStreamBuilder *_Nonnull 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.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setSamplesPerFrame
AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame( AAudioStreamBuilder *_Nonnull builder, int32_t samplesPerFrame )
Identical to AAudioStreamBuilder_setChannelCount().
Available since API level 26.
Deprecated. use AAudioStreamBuilder_setChannelCount
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setSessionId
AAUDIO_API void AAudioStreamBuilder_setSessionId( AAudioStreamBuilder *_Nonnull 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.
Available since API level 28.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setSharingMode
AAUDIO_API void AAudioStreamBuilder_setSharingMode( AAudioStreamBuilder *_Nonnull 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.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setSpatializationBehavior
AAUDIO_API void AAudioStreamBuilder_setSpatializationBehavior( AAudioStreamBuilder *_Nonnull builder, aaudio_spatialization_behavior_t spatializationBehavior )
Sets the behavior affecting whether spatialization will be used.
The AAudio system will use this information to select whether the stream will go through a spatializer effect or not when the effect is supported and enabled.
Available since API level 32.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStreamBuilder_setUsage
AAUDIO_API void AAudioStreamBuilder_setUsage( AAudioStreamBuilder *_Nonnull builder, aaudio_usage_t usage )
Set the intended use case for the output 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.
Available since API level 28.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
AAudioStream_close
AAUDIO_API aaudio_result_t AAudioStream_close( AAudioStream *_Nonnull stream )
Delete the internal data structures associated with the stream created by AAudioStreamBuilder_openStream().
If AAudioStream_release() has not been called then it will be called automatically.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStream_getAllowedCapturePolicy
AAUDIO_API aaudio_allowed_capture_policy_t AAudioStream_getAllowedCapturePolicy( AAudioStream *_Nonnull stream )
Return the policy that determines whether the audio may or may not be captured by other apps or the system.
Available since API level 29.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
the allowed capture policy, for example AAUDIO_ALLOW_CAPTURE_BY_ALL
|
AAudioStream_getBufferCapacityInFrames
AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames( AAudioStream *_Nonnull stream )
Query maximum buffer capacity in frames.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
buffer capacity in frames
|
AAudioStream_getBufferSizeInFrames
AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames( AAudioStream *_Nonnull stream )
Query the maximum number of frames that can be filled without blocking.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
buffer size in frames.
|
AAudioStream_getChannelCount
AAUDIO_API int32_t AAudioStream_getChannelCount( AAudioStream *_Nonnull stream )
A stream has one or more channels of data.
A frame will contain one sample for each channel.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual number of channels of the stream
|
AAudioStream_getChannelMask
AAUDIO_API aaudio_channel_mask_t AAudioStream_getChannelMask( AAudioStream *_Nonnull stream )
Return the channel mask for the stream.
This will be the mask set using AAudioStreamBuilder_setChannelMask, or AAUDIO_UNSPECIFIED otherwise.
Available since API level 32.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual channel mask
|
AAudioStream_getContentType
AAUDIO_API aaudio_content_type_t AAudioStream_getContentType( AAudioStream *_Nonnull stream )
Return the content type for the stream.
Available since API level 28.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
content type, for example AAUDIO_CONTENT_TYPE_MUSIC
|
AAudioStream_getDeviceId
AAUDIO_API int32_t AAudioStream_getDeviceId( AAudioStream *_Nonnull stream )
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual device ID
|
AAudioStream_getDirection
AAUDIO_API aaudio_direction_t AAudioStream_getDirection( AAudioStream *_Nonnull stream )
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
direction
|
AAudioStream_getFormat
AAUDIO_API aaudio_format_t AAudioStream_getFormat( AAudioStream *_Nonnull stream )
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual data format of the stream
|
AAudioStream_getFramesPerBurst
AAUDIO_API int32_t AAudioStream_getFramesPerBurst( AAudioStream *_Nonnull 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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
burst size
|
AAudioStream_getFramesPerDataCallback
AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback( AAudioStream *_Nonnull 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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
callback buffer size in frames or AAUDIO_UNSPECIFIED
|
AAudioStream_getFramesRead
AAUDIO_API int64_t AAudioStream_getFramesRead( AAudioStream *_Nonnull 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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
frames read
|
AAudioStream_getFramesWritten
AAUDIO_API int64_t AAudioStream_getFramesWritten( AAudioStream *_Nonnull 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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
frames written
|
AAudioStream_getHardwareChannelCount
AAUDIO_API int32_t AAudioStream_getHardwareChannelCount( AAudioStream *_Nonnull stream )
There may be channel conversions in the Audio framework.
The channel count or channel mask set in the stream builder may not be actual number of channels used in the hardware.
This returns the channel count used by the hardware.
If AAudioStreamBuilder_openStream() returned AAUDIO_OK, the result should always be valid.
Available since API level 34.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual number of channels of the underlying hardware
|
AAudioStream_getHardwareFormat
AAUDIO_API aaudio_format_t AAudioStream_getHardwareFormat( AAudioStream *_Nonnull stream )
There may be data format conversions in the Audio framework.
The data format set in the stream builder may not be actual format used in the hardware.
This returns the audio format used by the hardware.
If AAudioStreamBuilder_openStream() returned AAUDIO_OK, this should always return an aaudio_format_t.
AUDIO_FORMAT_PCM_8_24_BIT is currently not supported in AAudio, but the hardware may use it. If AUDIO_FORMAT_PCM_8_24_BIT is used by the hardware, return AAUDIO_FORMAT_PCM_I24_PACKED.
If any other format used by the hardware is not supported by AAudio, this will return AAUDIO_FORMAT_INVALID.
Available since API level 34.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual data format of the underlying hardware.
|
AAudioStream_getHardwareSampleRate
AAUDIO_API int32_t AAudioStream_getHardwareSampleRate( AAudioStream *_Nonnull stream )
There may be sample rate conversions in the Audio framework.
The sample rate set in the stream builder may not be actual sample rate used in the hardware.
This returns the sample rate used by the hardware in Hertz.
If AAudioStreamBuilder_openStream() returned AAUDIO_OK, the result should always be valid.
Available since API level 34.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual sample rate of the underlying hardware
|
AAudioStream_getInputPreset
AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset( AAudioStream *_Nonnull stream )
Return the input preset for the stream.
Available since API level 28.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
input preset, for example AAUDIO_INPUT_PRESET_CAMCORDER
|
AAudioStream_getPerformanceMode
AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode( AAudioStream *_Nonnull stream )
Get the performance mode used by the stream.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
AAudioStream_getSampleRate
AAUDIO_API int32_t AAudioStream_getSampleRate( AAudioStream *_Nonnull stream )
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual sample rate of the stream
|
AAudioStream_getSamplesPerFrame
AAUDIO_API int32_t AAudioStream_getSamplesPerFrame( AAudioStream *_Nonnull stream )
Identical to AAudioStream_getChannelCount().
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual number of samples frame
|
AAudioStream_getSessionId
AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId( AAudioStream *_Nonnull 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.
Available since API level 28.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
session ID or AAUDIO_SESSION_ID_NONE
|
AAudioStream_getSharingMode
AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode( AAudioStream *_Nonnull stream )
Provide actual sharing mode.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
actual sharing mode
|
AAudioStream_getSpatializationBehavior
AAUDIO_API aaudio_spatialization_behavior_t AAudioStream_getSpatializationBehavior( AAudioStream *_Nonnull stream )
Return the spatialization behavior for the stream.
If none was explicitly set, it will return the default AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO behavior.
Available since API level 32.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
spatialization behavior, for example AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO
|
AAudioStream_getState
AAUDIO_API aaudio_stream_state_t AAudioStream_getState( AAudioStream *_Nonnull stream )
Query the current state of the client, eg.
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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
AAudioStream_getTimestamp
AAUDIO_API aaudio_result_t AAudioStream_getTimestamp( AAudioStream *_Nonnull stream, clockid_t clockid, int64_t *_Nonnull framePosition, int64_t *_Nonnull timeNanoseconds )
Returns the time at which a particular frame was played on a speaker or headset, or was recorded on a microphone.
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.
The framePosition is an index into the stream of audio data. The first frame played or recorded is at framePosition 0.
These framePositions are the same units that you get from AAudioStream_getFramesRead() or AAudioStream_getFramesWritten(). A "frame" is a set of audio sample values that are played simultaneously. For example, a stereo stream has two samples in a frame, left and right.
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.
Available since API level 26.
| Details | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| Parameters |
|
||||||||
| Returns |
AAUDIO_OK or a negative error
|
AAudioStream_getUsage
AAUDIO_API aaudio_usage_t AAudioStream_getUsage( AAudioStream *_Nonnull stream )
Return the use case for the stream.
Available since API level 28.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
frames read
|
AAudioStream_getXRunCount
AAUDIO_API int32_t AAudioStream_getXRunCount( AAudioStream *_Nonnull 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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
the underrun or overrun count
|
AAudioStream_isContentSpatialized
AAUDIO_API bool AAudioStream_isContentSpatialized( AAudioStream *_Nonnull stream )
Return whether the content of the stream is spatialized.
Available since API level 32.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
true if the content is spatialized
|
AAudioStream_isPrivacySensitive
AAUDIO_API bool AAudioStream_isPrivacySensitive( AAudioStream *_Nonnull stream )
Return whether this input stream is marked as privacy sensitive or not.
See AAudioStreamBuilder_setPrivacySensitive().
Added in API level 30.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
true if privacy sensitive, false otherwise
|
AAudioStream_read
AAUDIO_API aaudio_result_t AAudioStream_read( AAudioStream *_Nonnull stream, void *_Nonnull 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.
Available since API level 26.
| Details | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| Parameters |
|
||||||||
| Returns |
The number of frames actually read or a negative error.
|
AAudioStream_release
AAUDIO_API aaudio_result_t AAudioStream_release( AAudioStream *_Nonnull stream )
Free the audio resources associated with a stream created by AAudioStreamBuilder_openStream().
AAudioStream_close() should be called at some point after calling this function.
After this call, the stream will be in AAUDIO_STREAM_STATE_CLOSING
This function is useful if you want to release the audio resources immediately, but still allow queries to the stream to occur from other threads. This often happens if you are monitoring stream progress from a UI thread.
NOTE: This function is only fully implemented for MMAP streams, which are low latency streams supported by some devices. On other "Legacy" streams some audio resources will still be in use and some callbacks may still be in process after this call.
Available since API level 30.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStream_requestFlush
AAUDIO_API aaudio_result_t AAudioStream_requestFlush( AAudioStream *_Nonnull stream )
Asynchronous request for the stream to flush.
Flushing will discard any pending data. This call only works if the stream is OPEN, PAUSED, STOPPED, or FLUSHED. Calling this function when in other states, or calling from an AAudio callback function, will have no effect and an error will be returned. 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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStream_requestPause
AAUDIO_API aaudio_result_t AAudioStream_requestPause( AAudioStream *_Nonnull stream )
Asynchronous request for the stream to pause.
Pausing a stream will freeze the data flow but not flush any buffers. Use AAudioStream_requestStart() 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().
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStream_requestStart
AAUDIO_API aaudio_result_t AAudioStream_requestStart( AAudioStream *_Nonnull 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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStream_requestStop
AAUDIO_API aaudio_result_t AAudioStream_requestStop( AAudioStream *_Nonnull 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.
Available since API level 26.
| Details | |||
|---|---|---|---|
| Parameters |
|
||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStream_setBufferSizeInFrames
AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames( AAudioStream *_Nonnull 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.
Available since API level 26.
| Details | |||||
|---|---|---|---|---|---|
| Parameters |
|
||||
| Returns |
actual buffer size in frames or a negative error
|
AAudioStream_waitForStateChange
AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange( AAudioStream *_Nonnull stream, aaudio_stream_state_t inputState, aaudio_stream_state_t *_Nullable 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;
}
Available since API level 26.
| Details | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| Parameters |
|
||||||||
| Returns |
AAUDIO_OK or a negative error.
|
AAudioStream_write
AAUDIO_API aaudio_result_t AAudioStream_write( AAudioStream *_Nonnull stream, const void *_Nonnull 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.
Available since API level 26.
| Details | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| Parameters |
|
||||||||
| Returns |
The number of frames actually written or a negative error.
|
AAudio_convertResultToText
AAUDIO_API const char *_Nonnull 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.
Available since API level 26.
| Details | |
|---|---|
| Returns |
pointer to a text representation of an AAudio result code.
|
AAudio_convertStreamStateToText
AAUDIO_API const char *_Nonnull 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.
Available since API level 26.
| Details | |
|---|---|
| Returns |
pointer to a text representation of an AAudio state.
|
AAudio_createStreamBuilder
AAUDIO_API aaudio_result_t AAudio_createStreamBuilder( AAudioStreamBuilder *_Nullable *_Nonnull 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.
Available since API level 26.