Oboe
1.2
A library for creating real-time audio apps on Android
|
#include <AudioStreamBuilder.h>
Static Public Member Functions | |
static bool | isAAudioSupported () |
static bool | isAAudioRecommended () |
Additional Inherited Members | |
![]() | |
AudioStreamCallback * | mStreamCallback = nullptr |
int32_t | mFramesPerCallback = kUnspecified |
int32_t | mChannelCount = kUnspecified |
int32_t | mSampleRate = kUnspecified |
int32_t | mDeviceId = kUnspecified |
int32_t | mBufferCapacityInFrames = kUnspecified |
int32_t | mBufferSizeInFrames = kUnspecified |
int32_t | mFramesPerBurst = kUnspecified |
SharingMode | mSharingMode = SharingMode::Shared |
AudioFormat | mFormat = AudioFormat::Unspecified |
Direction | mDirection = Direction::Output |
PerformanceMode | mPerformanceMode = PerformanceMode::None |
Usage | mUsage = Usage::Media |
ContentType | mContentType = ContentType::Music |
InputPreset | mInputPreset = InputPreset::VoiceRecognition |
SessionId | mSessionId = SessionId::None |
Factory class for an audio Stream.
|
inline |
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.
|
static |
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.
|
static |
Is the AAudio API supported on this device?
AAudio was introduced in the Oreo 8.0 release.
Result oboe::AudioStreamBuilder::openStream | ( | AudioStream ** | stream | ) |
Create and open a stream object based on the current settings.
The caller owns the pointer to the AudioStream object.
stream | pointer to a variable to receive the stream address |
|
inline |
If you leave this unspecified then Oboe will choose the best API for the device and SDK version at runtime.
If the caller requests AAudio and it is supported then AAudio will be used.
audioApi | Must be AudioApi::Unspecified, AudioApi::OpenSLES or AudioApi::AAudio. |
|
inline |
Set the requested buffer capacity in frames. BufferCapacityInFrames is the maximum possible BufferSizeInFrames.
The final stream capacity may differ. For AAudio it should be at least this big. For OpenSL ES, it could be smaller.
Default is kUnspecified.
bufferCapacityInFrames | the desired buffer capacity in frames or kUnspecified |
|
inline |
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.
streamCallback |
|
inline |
Request a specific number of channels.
Default is kUnspecified. If the value is unspecified then the application should query for the actual value after the stream is opened.
|
inline |
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.
contentType | the type of audio data, eg. ContentType::Speech |
|
inline |
Request an audio device identified device using an ID. On Android, for example, the ID could be obtained from the Java AudioManager.
By default, the primary device will be used.
Note that when using OpenSL ES, this will be ignored and the created stream will have deviceId kUnspecified.
deviceId | device identifier or kUnspecified |
|
inline |
Request the direction for a stream. The default is Direction::Output.
direction | Direction::Output or Direction::Input |
|
inline |
Request a sample data format, for example Format::Float.
Default is Format::Unspecified. If the value is unspecified then the application should query for the actual value after the stream is opened.
|
inline |
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.
framesPerCallback |
|
inline |
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.
inputPreset | the desired configuration for recording |
|
inline |
Request a performance level for the stream. This will determine the latency, the power consumption, and the level of protection from glitches.
performanceMode | for example, PerformanceMode::LowLatency |
|
inline |
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.
|
inline |
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.
sessionId | an allocated sessionID or SessionId::Allocate |
|
inline |
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.
sharingMode | SharingMode::Shared or SharingMode::Exclusive |
|
inline |
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.
usage | the desired usage, eg. Usage::Game |