Oboe
A library for creating real-time audio apps on Android
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | List of all members
oboe::AudioStreamBuilder Class Reference

#include <AudioStreamBuilder.h>

Inheritance diagram for oboe::AudioStreamBuilder:
oboe::AudioStreamBase

Public Member Functions

 AudioStreamBuilder (const AudioStreamBase &audioStreamBase)
 
AudioStreamBuildersetChannelCount (int channelCount)
 
AudioStreamBuildersetChannelMask (ChannelMask channelMask)
 
AudioStreamBuildersetDirection (Direction direction)
 
AudioStreamBuildersetSampleRate (int32_t sampleRate)
 
AudioStreamBuildersetFramesPerCallback (int framesPerCallback)
 
AudioStreamBuildersetFramesPerDataCallback (int framesPerCallback)
 
AudioStreamBuildersetFormat (AudioFormat format)
 
AudioStreamBuildersetBufferCapacityInFrames (int32_t bufferCapacityInFrames)
 
AudioApi getAudioApi () const
 
AudioStreamBuildersetAudioApi (AudioApi audioApi)
 
AudioStreamBuildersetSharingMode (SharingMode sharingMode)
 
AudioStreamBuildersetPerformanceMode (PerformanceMode performanceMode)
 
AudioStreamBuildersetUsage (Usage usage)
 
AudioStreamBuildersetContentType (ContentType contentType)
 
AudioStreamBuildersetInputPreset (InputPreset inputPreset)
 
AudioStreamBuildersetSessionId (SessionId sessionId)
 
AudioStreamBuildersetDeviceId (int32_t deviceId)
 
AudioStreamBuildersetDataCallback (std::shared_ptr< AudioStreamDataCallback > sharedDataCallback)
 
AudioStreamBuildersetDataCallback (AudioStreamDataCallback *dataCallback)
 
AudioStreamBuildersetErrorCallback (std::shared_ptr< AudioStreamErrorCallback > sharedErrorCallback)
 
AudioStreamBuildersetErrorCallback (AudioStreamErrorCallback *errorCallback)
 
AudioStreamBuildersetCallback (AudioStreamCallback *streamCallback)
 
AudioStreamBuildersetChannelConversionAllowed (bool allowed)
 
AudioStreamBuildersetFormatConversionAllowed (bool allowed)
 
AudioStreamBuildersetSampleRateConversionQuality (SampleRateConversionQuality quality)
 
AudioStreamBuildersetPackageName (std::string packageName)
 
AudioStreamBuildersetAttributionTag (std::string attributionTag)
 
bool willUseAAudio () const
 
Result openStream (AudioStream **stream)
 
Result openStream (std::shared_ptr< oboe::AudioStream > &stream)
 
Result openManagedStream (ManagedStream &stream)
 
- Public Member Functions inherited from oboe::AudioStreamBase
 AudioStreamBase (const AudioStreamBase &)=default
 
AudioStreamBaseoperator= (const AudioStreamBase &)=default
 
int32_t getChannelCount () const
 
Direction getDirection () const
 
int32_t getSampleRate () const
 
int32_t getFramesPerCallback () const
 
int32_t getFramesPerDataCallback () const
 
AudioFormat getFormat () const
 
virtual int32_t getBufferSizeInFrames ()
 
virtual int32_t getBufferCapacityInFrames () const
 
SharingMode getSharingMode () const
 
PerformanceMode getPerformanceMode () const
 
int32_t getDeviceId () const
 
AudioStreamDataCallbackgetDataCallback () const
 
AudioStreamErrorCallbackgetErrorCallback () const
 
bool isDataCallbackSpecified () const
 
bool isErrorCallbackSpecified () const
 
Usage getUsage () const
 
ContentType getContentType () const
 
InputPreset getInputPreset () const
 
SessionId getSessionId () const
 
bool isChannelConversionAllowed () const
 
bool isFormatConversionAllowed () const
 
SampleRateConversionQuality getSampleRateConversionQuality () const
 
ChannelMask getChannelMask () const
 

Static Public Member Functions

static bool isAAudioSupported ()
 
static bool isAAudioRecommended ()
 

Additional Inherited Members

- Protected Member Functions inherited from oboe::AudioStreamBase
virtual Result isValidConfig ()
 
- Protected Attributes inherited from oboe::AudioStreamBase
AudioStreamDataCallbackmDataCallback = nullptr
 
std::shared_ptr< AudioStreamDataCallbackmSharedDataCallback
 
AudioStreamErrorCallbackmErrorCallback = nullptr
 
std::shared_ptr< AudioStreamErrorCallbackmSharedErrorCallback
 
int32_t mFramesPerCallback = kUnspecified
 
int32_t mChannelCount = kUnspecified
 
int32_t mSampleRate = kUnspecified
 
int32_t mDeviceId = kUnspecified
 
int32_t mBufferCapacityInFrames = kUnspecified
 
int32_t mBufferSizeInFrames = kUnspecified
 
ChannelMask mChannelMask = ChannelMask::Unspecified
 
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
 
std::string mPackageName
 
std::string mAttributionTag
 
bool mChannelConversionAllowed = false
 
bool mFormatConversionAllowed = false
 
SampleRateConversionQuality mSampleRateConversionQuality = SampleRateConversionQuality::None
 

Detailed Description

Factory class for an audio Stream.

Member Function Documentation

◆ getAudioApi()

AudioApi oboe::AudioStreamBuilder::getAudioApi ( ) const
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.

Returns
the requested audio API

◆ isAAudioRecommended()

static bool oboe::AudioStreamBuilder::isAAudioRecommended ( )
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.

Returns
true if recommended

◆ isAAudioSupported()

static bool oboe::AudioStreamBuilder::isAAudioSupported ( )
static

Is the AAudio API supported on this device?

AAudio was introduced in the Oreo 8.0 release.

Returns
true if supported

◆ openManagedStream()

Result oboe::AudioStreamBuilder::openManagedStream ( ManagedStream &  stream)

Create and open a ManagedStream object based on the current builder state.

The caller must create a unique ptr, and pass by reference so it can be modified to point to an opened stream. The caller owns the unique ptr, and it will be automatically closed and deleted when going out of scope.

Deprecated:
Use openStream(std::shared_ptr<oboe::AudioStream> &stream) instead.
Parameters
streamReference to the ManagedStream (uniqueptr) used to keep track of stream
Returns
OBOE_OK if successful or a negative error code.

◆ openStream() [1/2]

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 and must delete it when finished.

Deprecated:
Use openStream(std::shared_ptr<oboe::AudioStream> &stream) instead.
Parameters
streampointer to a variable to receive the stream address
Returns
OBOE_OK if successful or a negative error code

◆ openStream() [2/2]

Result oboe::AudioStreamBuilder::openStream ( std::shared_ptr< oboe::AudioStream > &  stream)

Create and open a stream object based on the current settings.

The caller shares the pointer to the AudioStream object. The shared_ptr is used internally by Oboe to prevent the stream from being deleted while it is being used by callbacks.

Parameters
streamreference to a shared_ptr to receive the stream address
Returns
OBOE_OK if successful or a negative error code

◆ setAttributionTag()

AudioStreamBuilder * oboe::AudioStreamBuilder::setAttributionTag ( std::string  attributionTag)
inline

Declare the attribution tag of the context creating the stream.

This is usually Context#getAttributionTag().

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

Available since API level 31.

Parameters
attributionTagattributionTag of the calling context.

◆ setAudioApi()

AudioStreamBuilder * oboe::AudioStreamBuilder::setAudioApi ( AudioApi  audioApi)
inline

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 OpenSLES should mainly be used to test legacy performance/functionality.

If the caller requests AAudio and it is supported then AAudio will be used.

Parameters
audioApiMust be AudioApi::Unspecified, AudioApi::OpenSLES or AudioApi::AAudio.
Returns
pointer to the builder so calls can be chained

◆ setBufferCapacityInFrames()

AudioStreamBuilder * oboe::AudioStreamBuilder::setBufferCapacityInFrames ( int32_t  bufferCapacityInFrames)
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.

Parameters
bufferCapacityInFramesthe desired buffer capacity in frames or kUnspecified
Returns
pointer to the builder so calls can be chained

◆ setCallback()

AudioStreamBuilder * oboe::AudioStreamBuilder::setCallback ( AudioStreamCallback streamCallback)
inline

Specifies an object to handle data or error related callbacks from the underlying API.

This is the equivalent of calling both setDataCallback() and setErrorCallback().

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.

Parameters
streamCallback
Returns
pointer to the builder so calls can be chained

◆ setChannelConversionAllowed()

AudioStreamBuilder * oboe::AudioStreamBuilder::setChannelConversionAllowed ( bool  allowed)
inline

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

◆ setChannelCount()

AudioStreamBuilder * oboe::AudioStreamBuilder::setChannelCount ( int  channelCount)
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.

As the channel count here may be different from the corresponding channel count of provided channel mask used in setChannelMask(). The last called will be respected if this function and setChannelMask() are called.

◆ setChannelMask()

AudioStreamBuilder * oboe::AudioStreamBuilder::setChannelMask ( ChannelMask  channelMask)
inline

Request a specific channel mask.

Default is kUnspecified. If the value is unspecified then the application should query for the actual value after the stream is opened.

As the corresponding channel count of provided channel mask here may be different from the channel count used in setChannelCount(). The last called will be respected if this function and setChannelCount() are called.

As the setChannelMask API is available on Android 32+, this call will only take effects on Android 32+.

◆ setContentType()

AudioStreamBuilder * oboe::AudioStreamBuilder::setContentType ( ContentType  contentType)
inline

Set the type of audio data that an output 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 contentType is ignored for input streams.

The default, if you do not call this function, is ContentType::Music.

Added in API level 28.

Parameters
contentTypethe type of audio data, eg. ContentType::Speech

◆ setDataCallback() [1/2]

AudioStreamBuilder * oboe::AudioStreamBuilder::setDataCallback ( AudioStreamDataCallback dataCallback)
inline

Pass a raw pointer to a data callback. This is not recommended because the dataCallback object might get deleted by the app while it is being used.

Deprecated:
Call setDataCallback(std::shared_ptr<AudioStreamDataCallback>) instead.
Parameters
dataCallback
Returns
pointer to the builder so calls can be chained

◆ setDataCallback() [2/2]

AudioStreamBuilder * oboe::AudioStreamBuilder::setDataCallback ( std::shared_ptr< AudioStreamDataCallback sharedDataCallback)
inline

Specifies an object to handle data related callbacks from the underlying API.

Important: See AudioStreamCallback for restrictions on what may be called from the callback methods.

We pass a shared_ptr so that the sharedDataCallback object cannot be deleted before the stream is deleted.

Parameters
dataCallback
Returns
pointer to the builder so calls can be chained

◆ setDeviceId()

AudioStreamBuilder * oboe::AudioStreamBuilder::setDeviceId ( int32_t  deviceId)
inline

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 deviceId can be left kUnspecified.

The ID could be obtained from the Java AudioManager. AudioManager.getDevices() returns an array of AudioDeviceInfo, which contains a getId() method. That ID can be passed to this function.

It is possible that you may not get the device that you requested. So if it is important to you, you should call stream->getDeviceId() after the stream is opened to verify the actual ID.

Note that when using OpenSL ES, this will be ignored and the created stream will have deviceId kUnspecified.

Parameters
deviceIddevice identifier or kUnspecified
Returns
pointer to the builder so calls can be chained

◆ setDirection()

AudioStreamBuilder * oboe::AudioStreamBuilder::setDirection ( Direction  direction)
inline

Request the direction for a stream. The default is Direction::Output.

Parameters
directionDirection::Output or Direction::Input

◆ setErrorCallback() [1/2]

AudioStreamBuilder * oboe::AudioStreamBuilder::setErrorCallback ( AudioStreamErrorCallback errorCallback)
inline

Pass a raw pointer to an error callback. This is not recommended because the errorCallback object might get deleted by the app while it is being used.

Deprecated:
Call setErrorCallback(std::shared_ptr<AudioStreamErrorCallback>) instead.
Parameters
errorCallback
Returns
pointer to the builder so calls can be chained

◆ setErrorCallback() [2/2]

AudioStreamBuilder * oboe::AudioStreamBuilder::setErrorCallback ( std::shared_ptr< AudioStreamErrorCallback sharedErrorCallback)
inline

Specifies an object to handle error related callbacks from the underlying API. This can occur when a stream is disconnected because a headset is plugged in or unplugged. It can also occur if the audio service fails or if an exclusive stream is stolen by another stream.

Important: See AudioStreamCallback for restrictions on what may be called from the callback methods.

When an error callback occurs, the associated stream must be stopped and closed in a separate thread.

We pass a shared_ptr so that the errorCallback object cannot be deleted before the stream is deleted. If the stream was created using a shared_ptr then the stream cannot be deleted before the error callback has finished running.

Parameters
sharedErrorCallback
Returns
pointer to the builder so calls can be chained

◆ setFormat()

AudioStreamBuilder * oboe::AudioStreamBuilder::setFormat ( AudioFormat  format)
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.

◆ setFormatConversionAllowed()

AudioStreamBuilder * oboe::AudioStreamBuilder::setFormatConversionAllowed ( bool  allowed)
inline

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

◆ setFramesPerCallback()

AudioStreamBuilder * oboe::AudioStreamBuilder::setFramesPerCallback ( int  framesPerCallback)
inline
Deprecated:
use setFramesPerDataCallback instead.

◆ setFramesPerDataCallback()

AudioStreamBuilder * oboe::AudioStreamBuilder::setFramesPerDataCallback ( int  framesPerCallback)
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.

Calling setFramesPerDataCallback() does not guarantee anything about timing. This just collects the data into a the number of frames that your app requires. We encourage leaving this unspecified in most cases.

If this number is larger than the burst size, some bursts will not receive a callback. If this number is smaller than the burst size, there may be multiple callbacks in a single burst.

Parameters
framesPerCallback
Returns
pointer to the builder so calls can be chained

◆ setInputPreset()

AudioStreamBuilder * oboe::AudioStreamBuilder::setInputPreset ( InputPreset  inputPreset)
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.

Parameters
inputPresetthe desired configuration for recording

◆ setPackageName()

AudioStreamBuilder * oboe::AudioStreamBuilder::setPackageName ( std::string  packageName)
inline

Declare the name of the package creating the stream.

This is usually Context#getPackageName().

The default, if you do not call this function, is a random package in the calling uid. The vast majority of apps have only one package per calling UID. If an invalid package name is set, input streams may not be given permission to record when started.

The package name is usually the applicationId in your app's build.gradle file.

Available since API level 31.

Parameters
packageNamepackageName of the calling app.

◆ setPerformanceMode()

AudioStreamBuilder * oboe::AudioStreamBuilder::setPerformanceMode ( PerformanceMode  performanceMode)
inline

Request a performance level for the stream. This will determine the latency, the power consumption, and the level of protection from glitches.

Parameters
performanceModefor example, PerformanceMode::LowLatency
Returns
pointer to the builder so calls can be chained

◆ setSampleRate()

AudioStreamBuilder * oboe::AudioStreamBuilder::setSampleRate ( int32_t  sampleRate)
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.

◆ setSampleRateConversionQuality()

AudioStreamBuilder * oboe::AudioStreamBuilder::setSampleRateConversionQuality ( SampleRateConversionQuality  quality)
inline

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

◆ setSessionId()

AudioStreamBuilder * oboe::AudioStreamBuilder::setSessionId ( SessionId  sessionId)
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.

Parameters
sessionIdan allocated sessionID or SessionId::Allocate

◆ setSharingMode()

AudioStreamBuilder * oboe::AudioStreamBuilder::setSharingMode ( SharingMode  sharingMode)
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.

Parameters
sharingModeSharingMode::Shared or SharingMode::Exclusive
Returns
pointer to the builder so calls can be chained

◆ setUsage()

AudioStreamBuilder * oboe::AudioStreamBuilder::setUsage ( Usage  usage)
inline

Set the intended use case for an output 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 usage is ignored for input streams.

The default, if you do not call this function, is Usage::Media.

Added in API level 28.

Parameters
usagethe desired usage, eg. Usage::Game

◆ willUseAAudio()

bool oboe::AudioStreamBuilder::willUseAAudio ( ) const
inline
Returns
true if AAudio will be used based on the current settings.

The documentation for this class was generated from the following file: