Struct aaudio::AAudioStreamBuilder

pub struct AAudioStreamBuilder { /* fields omitted */ }

Implementations

impl AAudioStreamBuilder

pub fn new() -> Result<Self, Error>

pub fn set_callbacks<D, E>(self, data_callback: D, error_callback: E) -> Self where
    D: FnMut(&AAudioStreamInfo, &mut [u8], i32) -> CallbackResult + Send + 'static,
    E: FnMut(&AAudioStreamInfo, Error) + Send + 'static, 

Request that AAudio call the data_callback when the stream is running and the error_callback if any error occurs or the stream is disconnected.

Note that when using data 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 data callback function will start being called after AAudioStream::request_start() is called. It will stop being called after AAudioStream::request_pause() or AAudioStream::request_stop() is called.

The data_callback function will be called on a real-time thread owned by AAudio. Note that numFrames can vary unless AAudioStreamBuilder::set_frames_per_data_callback() 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()

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.

The error_callback 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.

The error_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.

pub fn set_device_id(self, device_id: i32) -> Self

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 0, in which case the primary device will be used.

Available since API level 26.

Arguments

• device_id - device identifier or 0 for unspecified

pub fn set_sample_rate(self, sample_rate: i32) -> Self

Request a sample rate in Hertz.

The default, if you do not call this function, is 0 (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.

Arguments

• sample_rate - frames per second. Common rates include 44100 and 48000 Hz.

pub fn set_channel_count(self, channel_count: i32) -> Self

Request a number of channels for the stream.

The default, if you do not call this function, is 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.

Arguments

• channel_count - Number of channels desired.

pub fn set_format(self, format: Format) -> Self

Request a sample data format, for example Format::I16.

The default, if you do not call this function, is 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.

Arguments

• format - the sample data format.

pub fn set_sharing_mode(self, sharing_mode: SharingMode) -> Self

Request a mode for sharing the device.

The default, if you do not call this function, is SharingMode::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.

Arguments

• sharing_mode - SharingMode::Shared or SharingMode::Exclusive

pub fn set_direction(self, direction: Direction) -> Self

Request the direction for a stream.

The default, if you do not call this function, is Direction::Output.

Available since API level 26.

Arguments

• direction - Direction::Output or Direction::Input

pub fn set_buffer_capacity_in_frames(self, num_frames: i32) -> Self

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 unspecified.

Available since API level 26.

Arguments

• num_frames - the desired buffer capacity in frames or 0 for unspecified

pub fn set_performance_mode(self, mode: PerformanceMode) -> Self

Set the requested performance mode.

Supported modes are None, PowerSaving and LowLatency.

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

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

Available since API level 26.

Arguments

• mode - the desired performance mode, eg. LowLatency

pub fn set_usage(self, usage: Usage) -> Self

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 Usage::Media.

Available since API level 28.

• usage - the desired usage, eg. Usage::Game

pub fn set_content_type(self, content_type: ContentType) -> Self

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 ContentType::Music.

Available since API level 28.

Arguments

• content_type - the type of audio data, eg. ContentType::Speech

pub fn set_input_preset(self, input_preset: InputPreset) -> Self

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 InputPreset::VoiceRecognition. That is because InputPreset::VoiceRecognition is the preset with the lowest latency on many platforms.

Available since API level 28.

Arguments

• input_preset - the desired configuration for recording

pub fn set_allowed_capture_policy(self, policy: AllowedCapturePolicy) -> Self

Specify whether this stream audio may or may not be captured by other apps or the system.

The default is AllowedCapturePolicy::AllowCaptureByAll.

Note that an application can also set its global policy, in which case the most restrictive policy is always applied. See android.media.AudioAttributes#setAllowedCapturePolicy(int)

Available since API level 29.

Arguments

• policy - the desired level of opt-out from being captured.

pub fn allocate_session_id(self) -> Self

Equivalent to invoking AAudioStreamBuilder::set_session_id with 0 argument.

pub fn remove_session_id(self) -> Self

Equivalent to invoking AAudioStreamBuilder::set_session_id with -1 argument.

pub fn set_session_id(self, session_id: i32) -> Self

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 -1 (none).

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

The allocated session ID can be obtained by calling AAudioStream::get_session_id() 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.

Arguments

• session_id - an allocated sessionID or 0 to allocate a new sessionID

pub fn set_privacy_sensitive(self, privacy_sensitive: bool) -> Self

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 InputPreset::VoiceCommunication or InputPreset::Camcorder.

Always takes precedence over default from input preset when set explicitly.

Only relevant if the stream direction is Direction::Input.

Added in API level 30.

Arguments

• privacy_sensitive - true if capture from this stream must be marked as privacy sensitive, false otherwise.

pub fn set_frames_per_data_callback(self, num_frames: i32) -> Self

Set the requested data callback buffer size in frames. See set_callbacks.

The default, if you do not call this function, is 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.

• num_frames - the desired buffer size in frames or 0 for unspecified

pub fn open_stream(self) -> Result<AAudioStream, Error>

Open a stream based on the options in the AAudioStreamBuilder.

Trait Implementations

impl Drop for AAudioStreamBuilder

fn drop(&mut self)

Executes the destructor for this type.