Struct aaudio::AAudioStream

pub struct AAudioStream { /* fields omitted */ }

Implementations

impl AAudioStream

pub fn get_sample_rate(&self) -> i32

Returns the actual sample rate.

Available since API level 26.

pub fn get_channel_count(&self) -> i32

A stream has one or more channels of data. A frame will contain one sample for each channel.

Available since API level 26.

pub fn get_buffer_size_in_frames(&self) -> i32

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

Available since API level 26.

pub fn get_frames_per_burst(&self) -> i32

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.

pub fn get_buffer_capacity_in_frames(&self) -> i32

Query maximum buffer capacity in frames.

Available since API level 26.

pub fn get_frames_per_data_callback(&self) -> i32

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::set_frames_per_data_callback() then this will be the same size.

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

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

Available since API level 26.

pub fn get_x_run_count(&self) -> i32

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.

pub fn get_device_id(&self) -> i32

Returns the actual device ID.

Available since API level 26.

pub fn get_format(&self) -> Format

Returns the actual data format.

Available since API level 26.

pub fn get_sharing_mode(&self) -> SharingMode

Provide actual sharing mode.

Available since API level 26.

pub fn get_performance_mode(&self) -> PerformanceMode

Get the performance mode used by the stream.

Available since API level 26.

pub fn get_direction(&self) -> Direction

Available since API level 26.

pub fn get_frames_written(&self) -> i64

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

pub fn get_frames_read(&self) -> i64

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

pub fn get_session_id(&self) -> i32

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::set_session_id() was called with 0 then a new session ID should be allocated once when the stream is opened.

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

If AAudioStreamBuilder::set_session_id() was not called then this function should return -1.

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

Available since API level 28.

pub fn get_timestamp_monotonic(&self) -> Result<Timestamp, Error>

Returns the time at which a particular frame was presented. This can be used to synchronize audio with video or MIDI. It can also be used to align a recorded stream with a playback stream.

Timestamps are only valid when the stream is in Started state. InvalidState will be returned if the stream is not started. Note that because request_start() is asynchronous, timestamps will not be valid until a short time after calling request_start(). So InvalidState 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.

pub fn get_state(&self) -> StreamState

Query the current state of the client, eg. 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::wait_for_state_change() with currentState set to Unknown and a zero timeout.

Available since API level 26.

pub fn release(&mut self) -> Result<(), Error>

Free the audio resources associated with the stream.

After this call, the stream will be in Closing state.

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.

Available since API level 30.

pub fn request_start(&mut self) -> Result<(), Error>

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 Starting or Started.

Returns 0 for OK or a negative error.

Available since API level 26.

pub fn request_pause(&mut self) -> Result<(), Error>

Asynchronous request for the stream to pause. Pausing a stream will freeze the data flow but not flush any buffers. Use AAudioStream::request_start() to resume playback after a pause. After this call the state will be in Pausing or Paused.

This will return Unimplemented for input streams. For input streams use AAudioStream::request_stop().

Available since API level 26.

pub fn request_flush(&mut self) -> Result<(), Error>

Asynchronous request for the stream to flush. Flushing will discard any pending data. This call only works if the stream is pausing or paused. Frame counters are not reset by a flush. They may be advanced. After this call the state will be in Flushing or Flushed.

This will return Unimplemented for input streams.

Available since API level 26.

pub fn request_stop(&mut self) -> Result<(), Error>

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 Stopping or Stopped.

Available since API level 26.

pub fn wait_for_state_change(
    &mut self,
    input_state: StreamState,
    timeout_nanos: i64
) -> Result<StreamState, Error>

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

This will update the current client state.

Returns the new state.

Available since API level 26.

pub fn read(
    &mut self,
    buffer: &mut [u8],
    num_frames: i32,
    timeout_nanoseconds: i64
) -> Result<u32, Error>

Read data from the stream. Returns the number of frames actually read or a negative error.

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.

Arguments

• buffer - The slice with the samples.
• num_frames - Number of frames to read. Only complete frames will be written.
• timeout_nanoseconds - Maximum number of nanoseconds to wait for completion.

pub fn write(
    &mut self,
    buffer: &[u8],
    num_frames: i32,
    timeout_nanoseconds: i64
) -> Result<u32, Error>

Write data to the stream. Returns the number of frames actually written or a negative error.

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.

Arguments

• buffer - The address of the first sample.
• num_frames - Number of frames to write. Only complete frames will be written.
• timeout_nanoseconds - Maximum number of nanoseconds to wait for completion.

pub fn set_buffer_size_in_frames(
    &mut self,
    num_frames: i32
) -> Result<(), Error>

This can be used to adjust the latency of the buffer by changing the threshold where blocking will occur. By combining this with AAudioStream::get_x_run_count(), the latency can be tuned at run-time for each device. Returns actual buffer size in frames or a negative error.

This cannot be set higher than AAudioStream::get_buffer_capacity_in_frames().

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

Available since API level 26.

Arguments

• num_frames - requested number of frames that can be filled without blocking

Trait Implementations

impl Drop for AAudioStream

fn drop(&mut self)

Executes the destructor for this type.

impl Send for AAudioStream