Struct ndk::audio::AudioStreamBuilder
source · [−]pub struct AudioStreamBuilder { /* private fields */ }
audio
only.Expand description
A native AAudioStreamBuilder *
Implementations
sourceimpl AudioStreamBuilder
impl AudioStreamBuilder
pub fn new() -> Result<Self>
sourcepub fn allowed_capture_policy(
self,
capture_policy: AudioAllowedCapturePolicy
) -> Self
Available on crate feature api-level-29
only.
pub fn allowed_capture_policy(
self,
capture_policy: AudioAllowedCapturePolicy
) -> Self
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)
.
Available since API level 29.
Arguments
policy
- the desired level of opt-out from being captured.
sourcepub fn buffer_capacity_in_frames(self, num_frames: i32) -> Self
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.
Available since API level 26.
Arguments
num_frames
- the desired buffer capacity in frames or 0 for unspecified
sourcepub fn channel_count(self, channel_count: i32) -> Self
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.
Available since API level 26.
Arguments
channel_count
- Number of channels desired.
sourcepub fn content_type(self, content_type: AudioContentType) -> Self
Available on crate feature api-level-28
only.
pub fn content_type(self, content_type: AudioContentType) -> Self
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
.
Available since API level 28.
Arguments
content_type
- the type of audio data, eg.AudioContentType::Speech
sourcepub fn data_callback(self, callback: AudioStreamDataCallback) -> Self
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.
Available since API level 26.
sourcepub fn device_id(self, device_id: i32) -> Self
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.
Available since API level 26.
Arguments
device_id
- device identifier or 0 for unspecified
sourcepub fn direction(self, direction: AudioDirection) -> Self
pub fn direction(self, direction: AudioDirection) -> Self
sourcepub fn error_callback(self, callback: AudioStreamErrorCallback) -> Self
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.
Available since API level 26.
sourcepub fn format(self, format: AudioFormat) -> Self
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.
Available since API level 26.
Arguments
format
- the sample data format.
sourcepub fn frames_per_data_callback(self, num_frames: i32) -> Self
pub fn frames_per_data_callback(self, num_frames: i32) -> Self
Set the requested data callback buffer size in frames.
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.
Available since API level 26.
num_frames
- the desired buffer size in frames or 0 for unspecified
sourcepub fn input_preset(self, input_preset: AudioInputPreset) -> Self
Available on crate feature api-level-28
only.
pub fn input_preset(self, input_preset: AudioInputPreset) -> Self
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.
Available since API level 28.
Arguments
input_preset
- the desired configuration for recording
sourcepub fn performance_mode(self, mode: AudioPerformanceMode) -> Self
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::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
sourcepub fn sample_rate(self, sample_rate: i32) -> Self
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.
Available since API level 26.
Arguments
sample_rate
- frames per second. Common rates include 44100 and 48000 Hz.
pub fn samples_per_frame(self, samples_per_frame: i32) -> Self
sourcepub fn session_id(self, session_id_or_allocate: Option<SessionId>) -> Self
Available on crate feature api-level-28
only.
pub fn session_id(self, session_id_or_allocate: Option<SessionId>) -> Self
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::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 orOption::None
to allocate a new sessionID
sourcepub fn sharing_mode(self, sharing_mode: AudioSharingMode) -> Self
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.
Available since API level 26.
Arguments
sharing_mode
-AudioSharingMode::Shared
orAudioSharingMode::Exclusive
sourcepub fn usage(self, usage: AudioUsage) -> Self
Available on crate feature api-level-28
only.
pub fn usage(self, usage: AudioUsage) -> Self
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
.
Available since API level 28.
usage
- the desired usage, eg.AudioUsage::Game
sourcepub fn open_stream(self) -> Result<AudioStream>
pub fn open_stream(self) -> Result<AudioStream>
Open a stream based on the options in the AAudioStreamBuilder.
Trait Implementations
sourceimpl Debug for AudioStreamBuilder
impl Debug for AudioStreamBuilder
Auto Trait Implementations
impl !RefUnwindSafe for AudioStreamBuilder
impl !Send for AudioStreamBuilder
impl !Sync for AudioStreamBuilder
impl Unpin for AudioStreamBuilder
impl !UnwindSafe for AudioStreamBuilder
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more