Struct ndk::audio::AudioStreamBuilder

pub struct AudioStreamBuilder { /* private fields */ }

Available on crate feature audio only.

A native AAudioStreamBuilder *

Implementations

impl AudioStreamBuilder

pub fn new() -> Result<Self>

pub fn allowed_capture_policy( self, capture_policy: AudioAllowedCapturePolicy ) -> Self

Available on crate feature api-level-29 only.

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

The default is AudioAllowedCapturePolicy::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).

Parameters

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

pub fn 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.

Parameters

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

pub fn 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.

Parameters

• channel_count: Number of channels desired.

pub fn content_type(self, content_type: AudioContentType) -> Self

Available on crate feature api-level-28 only.

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

Parameters

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

pub fn data_callback(self, callback: AudioStreamDataCallback) -> Self

Request that AAudio call the data_callback when the stream is running.

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 AudioStream::write() or AudioStream::read() on the same stream that has an active data callback.

The data callback function will start being called after AudioStream::request_start() is called. It will stop being called after AudioStream::request_pause() or AudioStream::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 AudioStreamBuilder::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
• AudioStream::read()
• AudioStream::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.

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

pub fn 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.

Parameters

• device_id: device identifier or 0 for unspecified

pub fn direction(self, direction: AudioDirection) -> Self

Request the direction for a stream.

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

Parameters

• direction: Output or Input

pub fn error_callback(self, callback: AudioStreamErrorCallback) -> Self

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.

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.

pub fn format(self, format: AudioFormat) -> 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.

Parameters

• format: the sample data format.

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

Set the requested data callback buffer size in frames.

See AudioStreamDataCallback.

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

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

pub fn input_preset(self, input_preset: AudioInputPreset) -> Self

Available on crate feature api-level-28 only.

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 VoiceRecognition which is the preset with the lowest latency on many platforms.

Parameters

• input_preset: the desired configuration for recording

pub fn performance_mode(self, mode: AudioPerformanceMode) -> 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 AudioStream::performance_mode() to find out the final mode for the stream.

Parameters

• mode: the desired performance mode, eg. AudioPerformanceMode::LowLatency

pub fn 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.

Parameters

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

pub fn samples_per_frame(self, samples_per_frame: i32) -> Self

pub fn session_id(self, session_id_or_allocate: Option<SessionId>) -> Self

Available on crate feature api-level-28 only.

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 Option::None then a session ID will be allocated when the stream is opened.

The allocated session ID can be obtained by calling AudioStream::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.

Parameters

• session_id: an allocated sessionID or Option::None to allocate a new sessionID

pub fn sharing_mode(self, sharing_mode: AudioSharingMode) -> Self

Request a mode for sharing the device.

The default, if you do not call this function, is AudioSharingMode::Shared.

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

Parameters

• sharing_mode: AudioSharingMode::Shared or AudioSharingMode::Exclusive

pub fn usage(self, usage: AudioUsage) -> Self

Available on crate feature api-level-28 only.

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

• usage: the desired usage, eg. AudioUsage::Game

pub fn open_stream(self) -> Result<AudioStream>

Open a stream based on the options in the AAudioStreamBuilder.

Trait Implementations

impl Debug for AudioStreamBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for AudioStreamBuilder

fn drop(&mut self)

Executes the destructor for this type.