Struct oboe::AudioStreamBuilder
source · pub struct AudioStreamBuilder<D, C, T> { /* private fields */ }
Expand description
Factory for an audio stream.
Implementations§
source§impl<D, C, T> AudioStreamBuilder<D, C, T>
impl<D, C, T> AudioStreamBuilder<D, C, T>
sourcepub fn set_channel_count<X: IsChannelCount>(self) -> AudioStreamBuilder<D, X, T>
pub fn set_channel_count<X: IsChannelCount>(self) -> AudioStreamBuilder<D, X, T>
Request a specific number of channels
Default is Unspecified
. If the value is unspecified then
the application should query for the actual value after the stream is opened.
sourcepub fn set_mono(self) -> AudioStreamBuilder<D, Mono, T>
pub fn set_mono(self) -> AudioStreamBuilder<D, Mono, T>
Request mono mode for a stream
sourcepub fn set_stereo(self) -> AudioStreamBuilder<D, Stereo, T>
pub fn set_stereo(self) -> AudioStreamBuilder<D, Stereo, T>
Request stereo mode for a stream
sourcepub fn set_direction<X: IsDirection>(self) -> AudioStreamBuilder<X, C, T>
pub fn set_direction<X: IsDirection>(self) -> AudioStreamBuilder<X, C, T>
Request the direction for a stream
The default is Direction::Output
sourcepub fn set_input(self) -> AudioStreamBuilder<Input, C, T>
pub fn set_input(self) -> AudioStreamBuilder<Input, C, T>
Request input direction for a stream
sourcepub fn set_output(self) -> AudioStreamBuilder<Output, C, T>
pub fn set_output(self) -> AudioStreamBuilder<Output, C, T>
Request output direction for a stream
It is optional because th stream builder already configured as output by default.
sourcepub fn set_sample_rate(self, sample_rate: i32) -> Self
pub fn set_sample_rate(self, sample_rate: i32) -> Self
Request a specific sample rate in Hz.
Default is kUnspecified. If the value is unspecified then the application should query for the actual value after the stream is opened.
Technically, this should be called the frame rate or frames per second, because it refers to the number of complete frames transferred per second. But it is traditionally called sample rate. Se we use that term.
sourcepub fn set_frames_per_callback(self, frames_per_callback: i32) -> Self
pub fn set_frames_per_callback(self, frames_per_callback: i32) -> Self
Request a specific number of frames for the data callback.
Default is kUnspecified. If the value is unspecified then the actual number may vary from callback to callback.
If an application can handle a varying number of frames then we recommend leaving this unspecified. This allow the underlying API to optimize the callbacks. But if your application is, for example, doing FFTs or other block oriented operations, then call this function to get the sizes you need.
sourcepub fn set_format<X: IsFormat>(self) -> AudioStreamBuilder<D, C, X>
pub fn set_format<X: IsFormat>(self) -> AudioStreamBuilder<D, C, X>
Request a sample data format, for example f32
.
Default is unspecified. If the value is unspecified then the application should query for the actual value after the stream is opened.
pub fn set_i16(self) -> AudioStreamBuilder<D, C, i16>
pub fn set_f32(self) -> AudioStreamBuilder<D, C, f32>
sourcepub fn set_buffer_capacity_in_frames(
self,
buffer_capacity_in_frames: i32
) -> Self
pub fn set_buffer_capacity_in_frames( self, buffer_capacity_in_frames: i32 ) -> Self
Set the requested buffer capacity in frames. Buffer capacity in frames is the maximum possible buffer size in frames.
The final stream capacity may differ. For AAudio it should be at least this big. For OpenSL ES, it could be smaller.
Default is unspecified.
sourcepub fn get_audio_api(&self) -> AudioApi
pub fn get_audio_api(&self) -> AudioApi
Get the audio API which will be requested when opening the stream. No guarantees that this is the API which will actually be used. Query the stream itself to find out the API which is being used.
If you do not specify the API, then AAudio will be used if isAAudioRecommended() returns true. Otherwise OpenSL ES will be used.
sourcepub fn set_audio_api(self, audio_api: AudioApi) -> Self
pub fn set_audio_api(self, audio_api: AudioApi) -> Self
If you leave this unspecified then Oboe will choose the best API for the device and SDK version at runtime.
This should almost always be left unspecified, except for debugging purposes. Specifying AAudio will force Oboe to use AAudio on 8.0, which is extremely risky. Specifying OpenSL ES should mainly be used to test legacy performance/functionality.
If the caller requests AAudio and it is supported then AAudio will be used.
sourcepub fn is_aaudio_supported() -> bool
pub fn is_aaudio_supported() -> bool
Is the AAudio API supported on this device?
AAudio was introduced in the Oreo 8.0 release.
sourcepub fn is_aaudio_recommended() -> bool
pub fn is_aaudio_recommended() -> bool
Is the AAudio API recommended this device?
AAudio may be supported but not recommended because of version specific issues. AAudio is not recommended for Android 8.0 or earlier versions.
sourcepub fn set_sharing_mode(self, sharing_mode: SharingMode) -> Self
pub fn set_sharing_mode(self, sharing_mode: SharingMode) -> Self
Request a mode for sharing the device. The requested sharing mode may not be available. So the application should query for the actual mode after the stream is opened.
Request a shared mode for the device
sourcepub fn set_exclusive(self) -> Self
pub fn set_exclusive(self) -> Self
Request an exclusive mode for the device
sourcepub fn set_performance_mode(self, performance_mode: PerformanceMode) -> Self
pub fn set_performance_mode(self, performance_mode: PerformanceMode) -> Self
Request a performance level for the stream. This will determine the latency, the power consumption, and the level of protection from glitches.
sourcepub fn set_usage(self, usage: Usage) -> Self
pub fn set_usage(self, usage: Usage) -> Self
Set the intended use case for the stream.
The 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.
Added in API level 28.
sourcepub fn set_content_type(self, content_type: ContentType) -> Self
pub fn set_content_type(self, content_type: ContentType) -> Self
Set the type of audio data that the stream will carry.
The 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
.
Added in API level 28.
sourcepub fn set_input_preset(self, input_preset: InputPreset) -> Self
pub fn set_input_preset(self, input_preset: InputPreset) -> Self
Set the input (capture) preset for the stream.
The 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 VoiceRecognition is the preset with the lowest latency on many platforms.
Added in API level 28.
sourcepub fn set_session_id(self, session_id: SessionId) -> Self
pub fn set_session_id(self, session_id: SessionId) -> Self
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 SessionId::None
.
If set to SessionId::Allocate
then a session ID will be allocated
when the stream is opened.
The allocated session ID can be obtained by calling AudioStream::getSessionId() and then used with this function when opening another stream. This allows effects to be shared between streams.
Session IDs from Oboe can be used the Android Java APIs and vice versa. So a session ID from an Oboe stream can be passed to Java and effects applied using the Java AudioEffect API.
Allocated session IDs will always be positive and nonzero.
Added in API level 28.
sourcepub fn set_device_id(self, device_id: i32) -> Self
pub fn set_device_id(self, device_id: i32) -> Self
Request a stream to a specific audio input/output device given an audio device ID.
In most cases, the primary device will be the appropriate device to use, and the device ID can be left unspecified.
On Android, for example, the ID could be obtained from the Java AudioManager. AudioManager.getDevices() returns an array of AudioDeviceInfo[], which contains a getId() method (as well as other type information), that should be passed to this method.
When java-interface
feature is used you can call AudioDeviceInfo::request
for listing devices info.
Note that when using OpenSL ES, this will be ignored and the created stream will have device ID unspecified.
sourcepub fn set_channel_conversion_allowed(self, allowed: bool) -> Self
pub fn set_channel_conversion_allowed(self, allowed: bool) -> Self
If true then Oboe might convert channel counts to achieve optimal results. On some versions of Android for example, stereo streams could not use a FAST track. So a mono stream might be used instead and duplicated to two channels. On some devices, mono streams might be broken, so a stereo stream might be opened and converted to mono.
Default is true.
sourcepub fn set_format_conversion_allowed(self, allowed: bool) -> Self
pub fn set_format_conversion_allowed(self, allowed: bool) -> Self
If true then Oboe might convert data formats to achieve optimal results. On some versions of Android, for example, a float stream could not get a low latency data path. So an I16 stream might be opened and converted to float.
Default is true.
sourcepub fn set_sample_rate_conversion_quality(
self,
quality: SampleRateConversionQuality
) -> Self
pub fn set_sample_rate_conversion_quality( self, quality: SampleRateConversionQuality ) -> Self
Specify the quality of the sample rate converter in Oboe.
If set to None then Oboe will not do sample rate conversion. But the underlying APIs might still do sample rate conversion if you specify a sample rate. That can prevent you from getting a low latency stream.
If you do the conversion in Oboe then you might still get a low latency stream.
Default is SampleRateConversionQuality::None
sourcepub fn will_use_aaudio(&self) -> bool
pub fn will_use_aaudio(&self) -> bool
Returns true if AAudio will be used based on the current settings.
source§impl<D: IsDirection, C: IsChannelCount, T: IsFormat> AudioStreamBuilder<D, C, T>
impl<D: IsDirection, C: IsChannelCount, T: IsFormat> AudioStreamBuilder<D, C, T>
sourcepub fn open_stream(self) -> Result<AudioStreamSync<D, (T, C)>>
pub fn open_stream(self) -> Result<AudioStreamSync<D, (T, C)>>
Create and open a synchronous (blocking) stream based on the current settings.
source§impl<C: IsChannelCount, T: IsFormat> AudioStreamBuilder<Input, C, T>
impl<C: IsChannelCount, T: IsFormat> AudioStreamBuilder<Input, C, T>
sourcepub fn set_callback<F>(
self,
stream_callback: F
) -> AudioStreamBuilderAsync<Input, F>
pub fn set_callback<F>( self, stream_callback: F ) -> AudioStreamBuilderAsync<Input, F>
Specifies an object to handle data or error related callbacks from the underlying API.
Important: See AudioStreamCallback for restrictions on what may be called from the callback methods.
When an error callback occurs, the associated stream will be stopped and closed in a separate thread.
A note on why the streamCallback parameter is a raw pointer rather than a smart pointer:
The caller should retain ownership of the object streamCallback points to. At first glance weak_ptr may seem like a good candidate for streamCallback as this implies temporary ownership. However, a weak_ptr can only be created from a shared_ptr. A shared_ptr incurs some performance overhead. The callback object is likely to be accessed every few milliseconds when the stream requires new data so this overhead is something we want to avoid.
This leaves a raw pointer as the logical type choice. The only caveat being that the caller must not destroy the callback before the stream has been closed.
source§impl<C: IsChannelCount, T: IsFormat> AudioStreamBuilder<Output, C, T>
impl<C: IsChannelCount, T: IsFormat> AudioStreamBuilder<Output, C, T>
sourcepub fn set_callback<F>(
self,
stream_callback: F
) -> AudioStreamBuilderAsync<Output, F>
pub fn set_callback<F>( self, stream_callback: F ) -> AudioStreamBuilderAsync<Output, F>
Specifies an object to handle data or error related callbacks from the underlying API.
Important: See AudioStreamCallback for restrictions on what may be called from the callback methods.
When an error callback occurs, the associated stream will be stopped and closed in a separate thread.
A note on why the streamCallback parameter is a raw pointer rather than a smart pointer:
The caller should retain ownership of the object streamCallback points to. At first glance weak_ptr may seem like a good candidate for streamCallback as this implies temporary ownership. However, a weak_ptr can only be created from a shared_ptr. A shared_ptr incurs some performance overhead. The callback object is likely to be accessed every few milliseconds when the stream requires new data so this overhead is something we want to avoid.
This leaves a raw pointer as the logical type choice. The only caveat being that the caller must not destroy the callback before the stream has been closed.