Audio

Delete the resources associated with the StreamBuilder.

Available since API level 26.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Request the direction for a stream.

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

Available since API level 26.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Identical to AAudioStreamBuilder_setChannelCount().

Available since API level 26.

Deprecated. use AAudioStreamBuilder_setChannelCount

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.

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.

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.

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.

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.

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.

Query maximum buffer capacity in frames.

Available since API level 26.

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

Available since API level 26.

A stream has one or more channels of data.

A frame will contain one sample for each channel.

Available since API level 26.

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.

Return the content type for the stream.

Available since API level 28.

Available since API level 26.

Available since API level 26.

Available since API level 26.

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.

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.

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.

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.

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.

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.

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.

Return the input preset for the stream.

Available since API level 28.

Get the performance mode used by the stream.

Available since API level 26.

Available since API level 26.

Identical to AAudioStream_getChannelCount().

Available since API level 26.

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.

Provide actual sharing mode.

Available since API level 26.

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.

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.

Available since API level 26.

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.

Return the use case for the stream.

Available since API level 28.

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.

Return whether the content of the stream is spatialized.

Available since API level 32.

Return whether this input stream is marked as privacy sensitive or not.

See AAudioStreamBuilder_setPrivacySensitive().

Added in API level 30.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.