#include <AudioStream.h>

Inheritance diagram for oboe::AudioStream:

Public Member Functions
	AudioStream (const AudioStreamBuilder &builder)

virtual Result	open ()

virtual Result	release ()

virtual Result	close ()

virtual Result	start (int64_t timeoutNanoseconds=kDefaultTimeoutNanos)

virtual Result	pause (int64_t timeoutNanoseconds=kDefaultTimeoutNanos)

virtual Result	flush (int64_t timeoutNanoseconds=kDefaultTimeoutNanos)

virtual Result	stop (int64_t timeoutNanoseconds=kDefaultTimeoutNanos)

virtual Result	requestStart ()=0

virtual Result	requestPause ()=0

virtual Result	requestFlush ()=0

virtual Result	requestStop ()=0

virtual StreamState	getState ()=0

virtual Result	waitForStateChange (StreamState inputState, StreamState *nextState, int64_t timeoutNanoseconds)=0

virtual ResultWithValue< int32_t >	setBufferSizeInFrames (int32_t)

virtual ResultWithValue< int32_t >	getXRunCount ()

virtual bool	isXRunCountSupported () const =0

int32_t	getFramesPerBurst () const

int32_t	getBytesPerFrame () const

int32_t	getBytesPerSample () const

virtual int64_t	getFramesWritten ()

virtual int64_t	getFramesRead ()

virtual ResultWithValue< double >	calculateLatencyMillis ()

virtual Result	getTimestamp (clockid_t, int64_t , int64_t )

virtual ResultWithValue< FrameTimestamp >	getTimestamp (clockid_t)

virtual ResultWithValue< int32_t >	write (const void *, int32_t, int64_t)

virtual ResultWithValue< int32_t >	read (void *, int32_t, int64_t)

virtual AudioApi	getAudioApi () const =0

bool	usesAAudio () const

virtual void *	getUnderlyingStream () const

virtual void	updateFramesWritten ()=0

virtual void	updateFramesRead ()=0

AudioStreamDataCallback *	swapDataCallback (AudioStreamDataCallback *dataCallback)

AudioStreamPartialDataCallback *	swapPartialDataCallback (AudioStreamPartialDataCallback *partialDataCallback)

AudioStreamErrorCallback *	swapErrorCallback (AudioStreamErrorCallback *errorCallback)

ResultWithValue< int32_t >	getAvailableFrames ()

ResultWithValue< int32_t >	waitForAvailableFrames (int32_t numFrames, int64_t timeoutNanoseconds)

virtual oboe::Result	getLastErrorCallbackResult () const

int32_t	getDelayBeforeCloseMillis () const

void	setDelayBeforeCloseMillis (int32_t delayBeforeCloseMillis)

void	setPerformanceHintEnabled (bool enabled)

bool	isPerformanceHintEnabled ()

virtual oboe::Result	reportWorkload (int32_t appWorkload)

virtual oboe::Result	notifyWorkloadIncrease (bool cpu, bool gpu, const char *debugName)

virtual oboe::Result	notifyWorkloadReset (bool cpu, bool gpu, const char *debugName)

virtual oboe::Result	notifyWorkloadSpike (bool cpu, bool gpu, const char *debugName)

virtual oboe::Result	setOffloadDelayPadding (int32_t delayInFrames, int32_t paddingInFrames)

virtual ResultWithValue< int32_t >	getOffloadDelay ()

virtual ResultWithValue< int32_t >	getOffloadPadding ()

virtual oboe::Result	setOffloadEndOfStream ()

virtual ResultWithValue< int64_t >	flushFromFrame (FlushFromAccuracy accuracy, int64_t positionInFrames)

virtual oboe::Result	setPlaybackParameters (const PlaybackParameters &parameters)

virtual ResultWithValue< PlaybackParameters >	getPlaybackParameters ()

Public Member Functions inherited from oboe::AudioStreamBase
	AudioStreamBase (const AudioStreamBase &)=default

AudioStreamBase &	operator= (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

std::vector< int32_t >	getDeviceIds () const

AudioStreamDataCallback *	getDataCallback () const

AudioStreamPartialDataCallback *	getPartialDataCallback () const

AudioStreamErrorCallback *	getErrorCallback () const

std::shared_ptr< AudioStreamPresentationCallback >	getPresentationCallback () const

bool	isDataCallbackSpecified () const

bool	isPartialDataCallbackSpecified () const

bool	anyDataCallbackSpecified () const

bool	isErrorCallbackSpecified () const

bool	isPresentationCallbackSpecified () const

Usage	getUsage () const

ContentType	getContentType () const

InputPreset	getInputPreset () const

SessionId	getSessionId () const

bool	isContentSpatialized () const

SpatializationBehavior	getSpatializationBehavior () const

AllowedCapturePolicy	getAllowedCapturePolicy () const

PrivacySensitiveMode	getPrivacySensitiveMode () const

std::string	getPackageName () const

std::string	getAttributionTag () const

bool	isChannelConversionAllowed () const

bool	isFormatConversionAllowed () const

SampleRateConversionQuality	getSampleRateConversionQuality () const

ChannelMask	getChannelMask () const

int32_t	getHardwareChannelCount () const

int32_t	getHardwareSampleRate () const

AudioFormat	getHardwareFormat () const

Protected Member Functions
bool	wasErrorCallbackCalled ()

virtual Result	waitForStateTransition (StreamState startingState, StreamState endingState, int64_t timeoutNanoseconds)

virtual DataCallbackResult	onDefaultCallback (void *, int)

virtual DataCallbackResult	fireDataCallback (void *audioData, int numFrames)

virtual int32_t	firePartialDataCallback (void *audioData, int numFrames)

bool	isDataCallbackEnabled ()

void	setDataCallbackEnabled (bool enabled)

void	calculateDefaultDelayBeforeCloseMillis ()

void	sleepBeforeClose ()

virtual void	beginPerformanceHintInCallback ()

virtual void	endPerformanceHintInCallback (int32_t)

virtual void	closePerformanceHint ()

void	setWeakThis (std::shared_ptr< oboe::AudioStream > &sharedStream)

std::shared_ptr< oboe::AudioStream >	lockWeakThis ()

Protected Member Functions inherited from oboe::AudioStreamBase
virtual Result	isValidConfig ()

Protected Attributes
std::weak_ptr< AudioStream >	mWeakThis

std::atomic< int64_t >	mFramesWritten {}

std::atomic< int64_t >	mFramesRead {}

std::mutex	mLock

oboe::Result	mErrorCallbackResult = oboe::Result::OK

int32_t	mFramesPerBurst = kUnspecified

int32_t	mDelayBeforeCloseMillis = kMinDelayBeforeCloseMillis

Protected Attributes inherited from oboe::AudioStreamBase
AudioStreamDataCallback *	mDataCallback = nullptr

std::shared_ptr< AudioStreamDataCallback >	mSharedDataCallback

AudioStreamPartialDataCallback *	mPartialDataCallback = nullptr

std::shared_ptr< AudioStreamPartialDataCallback >	mSharedPartialDataCallback

AudioStreamErrorCallback *	mErrorCallback = nullptr

std::shared_ptr< AudioStreamErrorCallback >	mSharedErrorCallback

std::shared_ptr< AudioStreamPresentationCallback >	mSharedPresentationCallback

int32_t	mFramesPerCallback = kUnspecified

int32_t	mChannelCount = kUnspecified

int32_t	mSampleRate = 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

AllowedCapturePolicy	mAllowedCapturePolicy = AllowedCapturePolicy::Unspecified

PrivacySensitiveMode	mPrivacySensitiveMode = PrivacySensitiveMode::Unspecified

std::string	mPackageName

std::string	mAttributionTag

bool	mIsContentSpatialized = false

SpatializationBehavior	mSpatializationBehavior = SpatializationBehavior::Unspecified

int32_t	mHardwareChannelCount = kUnspecified

int32_t	mHardwareSampleRate = kUnspecified

AudioFormat	mHardwareFormat = AudioFormat::Unspecified

bool	mChannelConversionAllowed = false

bool	mFormatConversionAllowed = false

SampleRateConversionQuality	mSampleRateConversionQuality = SampleRateConversionQuality::Medium

std::vector< int32_t >	mDeviceIds

Static Protected Attributes
static constexpr int	kMinDelayBeforeCloseMillis = 10

static constexpr int	kMaxDelayBeforeCloseMillis = 100

Friends
class	AudioStreamBuilder

Detailed Description

Base class for Oboe C++ audio stream.

Constructor & Destructor Documentation

◆ AudioStream()

oboe::AudioStream::AudioStream ( const AudioStreamBuilder & builder )

explicit

Construct an AudioStream using the given AudioStreamBuilder

Parameters

builder containing all the stream's attributes

Member Function Documentation

◆ beginPerformanceHintInCallback()

virtual void oboe::AudioStream::beginPerformanceHintInCallback ( )

inlineprotectedvirtual

This may be called internally at the beginning of a callback.

◆ calculateDefaultDelayBeforeCloseMillis()

void oboe::AudioStream::calculateDefaultDelayBeforeCloseMillis ( )

protected

This should only be called as a stream is being opened. Otherwise we might override setDelayBeforeCloseMillis().

◆ calculateLatencyMillis()

virtual ResultWithValue< double > oboe::AudioStream::calculateLatencyMillis ( )

inlinevirtual

Calculate the latency of a stream based on getTimestamp().

Output latency is the time it takes for a given frame to travel from the app to some type of digital-to-analog converter. If the DAC is external, for example in a USB interface or a TV connected by HDMI, then there may be additional latency that the Android device is unaware of.

Input latency is the time it takes to a given frame to travel from an analog-to-digital converter (ADC) to the app.

Note that the latency of an OUTPUT stream will increase abruptly when you write data to it and then decrease slowly over time as the data is consumed.

The latency of an INPUT stream will decrease abruptly when you read data from it and then increase slowly over time as more data arrives.

The latency of an OUTPUT stream is generally higher than the INPUT latency because an app generally tries to keep the OUTPUT buffer full and the INPUT buffer empty.

Note that due to issues in Android before R, we recommend NOT calling this method from a data callback. See this tech note for more details. https://github.com/google/oboe/wiki/TechNote_ReleaseBuffer

Returns: a ResultWithValue which has a result of Result::OK and a value containing the latency in milliseconds, or a result of Result::Error*.

◆ close()

virtual Result oboe::AudioStream::close ( )

virtual

Close the stream and deallocate any resources from the open() call.

◆ closePerformanceHint()

virtual void oboe::AudioStream::closePerformanceHint ( )

inlineprotectedvirtual

This will be called when the stream is closed just in case performance hints were enabled.

◆ endPerformanceHintInCallback()

virtual void oboe::AudioStream::endPerformanceHintInCallback ( int32_t )

inlineprotectedvirtual

This may be called internally at the end of a callback.

Parameters

numFrames passed to the callback

◆ fireDataCallback()

virtual DataCallbackResult oboe::AudioStream::fireDataCallback	(	void *	audioData,
		int	numFrames )

protectedvirtual

Override this to provide your own behaviour for the audio callback

Parameters

audioData	container array which audio frames will be written into or read from
numFrames	number of frames which were read/written

Returns: the result of the callback: stop or continue

◆ firePartialDataCallback()

virtual int32_t oboe::AudioStream::firePartialDataCallback	(	void *	audioData,
		int	numFrames )

protectedvirtual

Override this to provide your own behaviour for the parital audio callback

Parameters

audioData	container array which audio frames will be written into or read from
numFrames	number of frames which were read/written

Returns: the actual processed frames

◆ flush()

virtual Result oboe::AudioStream::flush ( int64_t timeoutNanoseconds = kDefaultTimeoutNanos )

virtual

Flush the stream. This will block until the stream has been flushed, an error occurs or timeoutNanoseconds has been reached.

◆ flushFromFrame()

virtual ResultWithValue< int64_t > oboe::AudioStream::flushFromFrame	(	FlushFromAccuracy	accuracy,
		int64_t	positionInFrames )

inlinevirtual

Flush all data from given position. If this operation returns successfully, the following data will be written from the returned position.

This method will only available when the performance mode is PerformanceMode::PowerSavingOffloaded.

The requested position must not be negative or greater than the written frames. The current written position can be known by querying getFramesWritten().

When clients request to flush from a certain position, the audio system will return the actual flushed position based on the requested position, playback latency, etc. The written position will be updated as the actual flush position. All data after actual flush position flushed. The client can provide data from actual flush position at next write operation or data callback request. When the stream is flushed, the stream end will be reset. The client must not write any data before this function returns. Otherwise, the data will be corrupted. When the method returns successfully and the stream is active, the client must write data immediately if little audio data remains. Otherwise, the stream will underrun.

This was introduced in Android API Level 37.

Parameters

accuracy	the accuracy requirement when flushing. The value must be one of the valid FlushFromAccuracy value.
position	the start point in frames to flush the stream.

Returns: a result which the error code indicates if the stream is successfully flush or not and value as the successfully flushed position or suggested flushed position. Result::OK if the stream is successfully flushed. The value is the actual flushed position. Result::ErrorUnimplemented if it is not supported by the device. The value is the requested position. Result::ErrorIllegalArgument if the stream is not an output offload stream or the accuracy is not one of valid FlushFromAccuracy values. The value is the requested position. Result::ErrorOutOfRange if the provided position is negative or is greater than the frames written or the stream cannot flush from the requested position and FlushFromAccuracy::Accurate is requested. The value is suggested flushed position. Result::ErrorDisconnected if the stream is disconnected. The value is the requested position. Result::ErrorClosed if the stream is closed. The value is the requested position.

◆ getAudioApi()

virtual AudioApi oboe::AudioStream::getAudioApi ( ) const

pure virtual

Get the underlying audio API which the stream uses.

Returns: the API that this stream uses.

◆ getAvailableFrames()

ResultWithValue< int32_t > oboe::AudioStream::getAvailableFrames ( )

Returns: number of frames of data currently in the buffer

◆ getBytesPerFrame()

int32_t oboe::AudioStream::getBytesPerFrame ( ) const

inline

Get the number of bytes in each audio frame. This is calculated using the channel count and the sample format. For example, a 2 channel floating point stream will have 2 * 4 = 8 bytes per frame.

Note for compressed formats, bytes per frames is treated as 1 by convention.

Returns: number of bytes in each audio frame.

◆ getBytesPerSample()

int32_t oboe::AudioStream::getBytesPerSample ( ) const

Get the number of bytes per sample. This is calculated using the sample format. For example, a stream using 16-bit integer samples will have 2 bytes per sample.

Note for compressed formats, they may not have a fixed bytes per sample. In that case, this method will return 0 for compressed format.

Returns: the number of bytes per sample.

◆ getFramesPerBurst()

int32_t oboe::AudioStream::getFramesPerBurst ( ) const

inline

Query the number of frames that are read or written by the endpoint at one time.

Returns: burst size

◆ getFramesRead()

virtual int64_t oboe::AudioStream::getFramesRead ( )

virtual

The number of audio frames read from the stream. This monotonic counter will never get reset.

Returns: the number of frames read so far

◆ getFramesWritten()

virtual int64_t oboe::AudioStream::getFramesWritten ( )

virtual

The number of audio frames written into the stream. This monotonic counter will never get reset.

Returns: the number of frames written so far

◆ getLastErrorCallbackResult()

virtual oboe::Result oboe::AudioStream::getLastErrorCallbackResult ( ) const

inlinevirtual

Returns: last result passed from an error callback

◆ getPlaybackParameters()

virtual ResultWithValue< PlaybackParameters > oboe::AudioStream::getPlaybackParameters ( )

inlinevirtual

Get current playback parameters for the given stream.

This was introduced in Android API Level 37.

Returns: a ResultWithValue which has a result of Result::OK and a value containing the playback parameters, or a result of Result::Error*.

◆ getState()

virtual StreamState oboe::AudioStream::getState ( )

pure virtual

Query the current state, eg. StreamState::Pausing

Returns: state or a negative error.

◆ getTimestamp() [1/2]

virtual ResultWithValue< FrameTimestamp > oboe::AudioStream::getTimestamp ( clockid_t )

virtual

Get the estimated time that the frame at framePosition entered or left the audio processing pipeline.

This can be used to coordinate events and interactions with the external environment, and to estimate the latency of an audio stream. An example of usage can be found in the hello-oboe sample (search for "calculateCurrentOutputLatencyMillis").

The time is based on the implementation's best effort, using whatever knowledge is available to the system, but cannot account for any delay unknown to the implementation.

Note that due to issues in Android before R, we recommend NOT calling this method from a data callback. See this tech note for more details. https://github.com/google/oboe/wiki/TechNote_ReleaseBuffer

See

Parameters

clockId the type of clock to use e.g. CLOCK_MONOTONIC

Returns: a FrameTimestamp containing the position and time at which a particular audio frame entered or left the audio processing pipeline, or an error if the operation failed.

◆ getTimestamp() [2/2]

virtual Result oboe::AudioStream::getTimestamp	(	clockid_t	,
		int64_t *	,
		int64_t *	)

inlinevirtual

Get the estimated time that the frame at framePosition entered or left the audio processing pipeline.

This can be used to coordinate events and interactions with the external environment, and to estimate the latency of an audio stream. An example of usage can be found in the hello-oboe sample (search for "calculateCurrentOutputLatencyMillis").

The time is based on the implementation's best effort, using whatever knowledge is available to the system, but cannot account for any delay unknown to the implementation.

Note that due to issues in Android before R, we recommend NOT calling this method from a data callback. See this tech note for more details. https://github.com/google/oboe/wiki/TechNote_ReleaseBuffer

Deprecated: since 1.0, use AudioStream::getTimestamp(clockid_t clockId) instead, which returns ResultWithValue

Parameters

clockId	the type of clock to use e.g. CLOCK_MONOTONIC
framePosition	the frame number to query
timeNanoseconds	an output parameter which will contain the presentation timestamp

◆ getUnderlyingStream()

virtual void * oboe::AudioStream::getUnderlyingStream ( ) const

inlinevirtual

Only for debugging. Do not use in production. If you need to call this method something is wrong. If you think you need it for production then please let us know so we can modify Oboe so that you don't need this.

Returns: nullptr or a pointer to a stream from the system API

◆ getXRunCount()

virtual ResultWithValue< int32_t > oboe::AudioStream::getXRunCount ( )

inlinevirtual

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

Returns: a result which is either Result::OK with the xRun count as the value, or a Result::Error* code

◆ isDataCallbackEnabled()

bool oboe::AudioStream::isDataCallbackEnabled ( )

inlineprotected

Returns: true if callbacks may be called

◆ isPerformanceHintEnabled()

bool oboe::AudioStream::isPerformanceHintEnabled ( )

inline

This only tells you if the feature has been requested. It does not tell you if the PerformanceHint feature is implemented or active on the device.

Returns: true if set using setPerformanceHintEnabled().

◆ isXRunCountSupported()

virtual bool oboe::AudioStream::isXRunCountSupported ( ) const

pure virtual

Returns: true if XRun counts are supported on the stream

◆ notifyWorkloadIncrease()

virtual oboe::Result oboe::AudioStream::notifyWorkloadIncrease	(	bool	cpu,
		bool	gpu,
		const char *	debugName )

inlinevirtual

Informs the framework of an upcoming increase in the workload of an audio callback bound to this session. The user can specify whether the increase is expected to be on the CPU, GPU, or both.

Sending hints for both CPU and GPU counts as two separate hints for the purposes of the rate limiter.

Parameters

cpu	Indicates if the workload increase is expected to affect the CPU.
gpu	Indicates if the workload increase is expected to affect the GPU.
debugName	A required string used to identify this specific hint during tracing. This debug string will only be held for the duration of the method, and can be safely discarded after.

This was introduced in Android API Level 36

Returns: Result::OK on success. Result::ErrorInvalidState if the PerformanceHint was not enabled. Result::ErrorClosed if AdpfWrapper::open() was not called. Result::ErrorUnimplemented if the API is not supported. Result::ErrorInvalidHandle if no hints were requested. Result::ErrorInvalidRate if the hint was rate limited. Result::ErrorNoService if communication with the system service has failed. Result::ErrorUnavailable if the hint is not supported.

◆ notifyWorkloadReset()

virtual oboe::Result oboe::AudioStream::notifyWorkloadReset	(	bool	cpu,
		bool	gpu,
		const char *	debugName )

inlinevirtual

Informs the framework of an upcoming reset in the workload of an audio callback bound to this session, or the imminent start of a new workload. The user can specify whether the reset is expected to affect the CPU, GPU, or both.

Sending hints for both CPU and GPU counts as two separate hints for the purposes of the this load tracking.

Parameters

cpu	Indicates if the workload reset is expected to affect the CPU.
gpu	Indicates if the workload reset is expected to affect the GPU.
debugName	A required string used to identify this specific hint during tracing. This debug string will only be held for the duration of the method, and can be safely discarded after.

This was introduced in Android API Level 36

Returns: Result::OK on success. Result::ErrorInvalidState if the PerformanceHint was not enabled. Result::ErrorClosed if AdpfWrapper::open() was not called. Result::ErrorUnimplemented if the API is not supported. Result::ErrorInvalidHandle if no hints were requested. Result::ErrorInvalidRate if the hint was rate limited. Result::ErrorNoService if communication with the system service has failed. Result::ErrorUnavailable if the hint is not supported.

◆ notifyWorkloadSpike()

virtual oboe::Result oboe::AudioStream::notifyWorkloadSpike	(	bool	cpu,
		bool	gpu,
		const char *	debugName )

inlinevirtual

Informs the framework of an upcoming one-off expensive frame for an audio callback bound to this session. This frame will be treated as not representative of the workload as a whole, and it will be discarded the purposes of load tracking. The user can specify whether the workload spike is expected to be on the CPU, GPU, or both.

Sending hints for both CPU and GPU counts as two separate hints for the purposes of the rate limiter.

This was introduced in Android API Level 36

Parameters

cpu	Indicates if the workload spike is expected to affect the CPU.
gpu	Indicates if the workload spike is expected to affect the GPU.
debugName	A required string used to identify this specific hint during tracing. This debug string will only be held for the duration of the method, and can be safely discarded after.

Returns: Result::OK on success. Result::ErrorInvalidState if the PerformanceHint was not enabled. Result::ErrorClosed if AdpfWrapper::open() was not called. Result::ErrorUnimplemented if the API is not supported. Result::ErrorInvalidHandle if no hints were requested. Result::ErrorInvalidRate if the hint was rate limited. Result::ErrorNoService if communication with the system service has failed. Result::ErrorUnavailable if the hint is not supported.

◆ onDefaultCallback()

virtual DataCallbackResult oboe::AudioStream::onDefaultCallback	(	void *	,
		int	)

inlineprotectedvirtual

Override this to provide a default for when the application did not specify a callback.

Parameters

audioData
numFrames

Returns: result

◆ open()

virtual Result oboe::AudioStream::open ( )

inlinevirtual

Open a stream based on the current settings.

Note that we do not recommend re-opening a stream that has been closed. TODO Should we prevent re-opening?

Returns

◆ pause()

virtual Result oboe::AudioStream::pause ( int64_t timeoutNanoseconds = kDefaultTimeoutNanos )

virtual

Pause the stream. This will block until the stream has been paused, an error occurs or timeoutNanoseconds has been reached.

◆ read()

virtual ResultWithValue< int32_t > oboe::AudioStream::read	(	void *	,
		int32_t	,
		int64_t	)

inlinevirtual

Read data into the supplied buffer from the stream. This method will block until the read is complete or it runs out of time.

If timeoutNanoseconds is zero then this call will not wait.

Parameters

buffer	The address of the first sample.
numFrames	Number of frames to read. Only complete frames will be read.
timeoutNanoseconds	Maximum number of nanoseconds to wait for completion.

Returns: a ResultWithValue which has a result of Result::OK and a value containing the number of frames actually read, or result of Result::Error*.

◆ release()

virtual Result oboe::AudioStream::release ( )

inlinevirtual

Free the audio resources associated with a stream created by AAudioStreamBuilder_openStream().

AAudioStream_close() should be called at some point after calling this function.

After this call, the stream will be in AAUDIO_STREAM_STATE_CLOSING

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.

NOTE: This function is only fully implemented for MMAP streams, which are low latency streams supported by some devices. On other "Legacy" streams some audio resources will still be in use and some callbacks may still be in process after this call.

Available in AAudio since API level 30. Returns Result::ErrorUnimplemented otherwise.

Returns
either Result::OK or an error.

◆ reportWorkload()

virtual oboe::Result oboe::AudioStream::reportWorkload ( int32_t appWorkload )

inlinevirtual

Use this to give the performance manager more information about your workload. You can call this at the beginning of the callback when you figure out what your workload will be.

Call this if (1) you have called setPerformanceHintEnabled(true), and (2) you have a varying workload, and (3) you hear glitches when your workload suddenly increases.

This might happen when you go from a single note to a big chord on a synthesizer.

The workload can be in your own units. If you are synthesizing music then the workload could be the number of active voices. If your app is a game then it could be the number of sound effects. The units are arbitrary. They just have to be proportional to the estimated computational load. For example, if some of your voices take 20% more computation than a basic voice then assign 6 units to the complex voice and 5 units to the basic voice.

The performance hint code can use this as an advance warning that the callback duration will probably increase. Rather than wait for the long duration and possibly under-run, we can boost the CPU immediately before we start doing the calculations.

Parameters

appWorkload workload in application units, such as number of voices

Returns: OK or an error such as ErrorInvalidState if the PerformanceHint was not enabled.

◆ requestFlush()

virtual Result oboe::AudioStream::requestFlush ( )

pure virtual

Flush the stream asynchronously. Returns immediately (does not block). Equivalent to calling flush(0).

◆ requestPause()

virtual Result oboe::AudioStream::requestPause ( )

pure virtual

Pause the stream asynchronously. Returns immediately (does not block). Equivalent to calling pause(0).

◆ requestStart()

virtual Result oboe::AudioStream::requestStart ( )

pure virtual

Start the stream asynchronously. Returns immediately (does not block). Equivalent to calling start(0).

◆ requestStop()

virtual Result oboe::AudioStream::requestStop ( )

pure virtual

Stop the stream asynchronously. Returns immediately (does not block). Equivalent to calling stop(0).

◆ setBufferSizeInFrames()

virtual ResultWithValue< int32_t > oboe::AudioStream::setBufferSizeInFrames ( int32_t )

inlinevirtual

This can be used to adjust the latency of the buffer by changing the threshold where blocking will occur. By combining this with getXRunCount(), the latency can be tuned at run-time for each device.

This cannot be set higher than getBufferCapacity().

This should only be used with Output streams. It will be ignored for Input streams because they are generally kept as empty as possible.

For OpenSL ES, this method only has an effect on output stream that do NOT use a callback. The blocking writes goes into a buffer in Oboe and the size of that buffer is controlled by this method.

Parameters

requestedFrames requested number of frames that can be filled without blocking

Returns: the resulting buffer size in frames (obtained using value()) or an error (obtained using error())

◆ setDataCallbackEnabled()

void oboe::AudioStream::setDataCallbackEnabled ( bool enabled )

inlineprotected

This can be set false internally to prevent callbacks after DataCallbackResult::Stop has been returned.

◆ setDelayBeforeCloseMillis()

void oboe::AudioStream::setDelayBeforeCloseMillis ( int32_t delayBeforeCloseMillis )

inline

Set the time to sleep before closing the internal stream.

Sometimes a callback can occur shortly after a stream has been stopped and even after a close! If the stream has been closed then the callback might access memory that has been freed, which could cause a crash. This seems to be more likely in Android P or earlier. But it can also occur in later versions. By sleeping, we give time for the callback threads to finish.

Note that this only has an effect when OboeGlobals::areWorkaroundsEnabled() is true.

Parameters

delayBeforeCloseMillis time to sleep before close.

◆ setPerformanceHintEnabled()

void oboe::AudioStream::setPerformanceHintEnabled ( bool enabled )

inline

Enable or disable a device specific CPU performance hint. Runtime benchmarks such as the callback duration may be used to speed up the CPU and improve real-time performance.

Note that this feature is device specific and may not be implemented. Also the benefits may vary by device.

The flag will be checked in the Oboe data callback. If it transitions from false to true then the PerformanceHint feature will be started. This only needs to be called once for each stream.

You may want to enable this if you have a dynamically changing workload and you notice that you are getting under-runs and glitches when your workload increases. This might happen, for example, if you suddenly go from playing one note to ten notes on a synthesizer.

Try the "CPU Load" test in OboeTester if you would like to experiment with this interactively.

On some devices, this may be implemented using the "ADPF" library.

Parameters

enabled true if you would like a performance boost, default is false

◆ setPlaybackParameters()

virtual oboe::Result oboe::AudioStream::setPlaybackParameters ( const PlaybackParameters & parameters )

inlinevirtual

Set playback parameters for the given stream.

This was introduced in Android API Level 37.

Parameters

parameters a pointer of PlaybackParameters where current playback parameters will be written to on success.

Returns: Result::OK if the playback parameters are set successfully. Result::ErrorIllegalArgument if the given stream is not an output stream or the requested parameters are invalid. Result::ErrorUnimplemented if the device or the stream doesn't support setting playback parameters. Result::ErrorInvalidState if the stream is not initialized successfully.

◆ sleepBeforeClose()

void oboe::AudioStream::sleepBeforeClose ( )

inlineprotected

Try to avoid a race condition when closing.

◆ start()

virtual Result oboe::AudioStream::start ( int64_t timeoutNanoseconds = kDefaultTimeoutNanos )

virtual

Start the stream. This will block until the stream has been started, an error occurs or timeoutNanoseconds has been reached.

◆ stop()

virtual Result oboe::AudioStream::stop ( int64_t timeoutNanoseconds = kDefaultTimeoutNanos )

virtual

Stop the stream. This will block until the stream has been stopped, an error occurs or timeoutNanoseconds has been reached.

◆ updateFramesRead()

virtual void oboe::AudioStream::updateFramesRead ( )

pure virtual

Update mFramesRead. For internal use only.

◆ updateFramesWritten()

virtual void oboe::AudioStream::updateFramesWritten ( )

pure virtual

Update mFramesWritten. For internal use only.

◆ usesAAudio()

bool oboe::AudioStream::usesAAudio ( ) const

inline

Returns true if the underlying audio API is AAudio.

Returns: true if this stream is implemented using the AAudio API.

◆ waitForAvailableFrames()

ResultWithValue< int32_t > oboe::AudioStream::waitForAvailableFrames	(	int32_t	numFrames,
		int64_t	timeoutNanoseconds )

Wait until the stream has a minimum amount of data available in its buffer. This can be used with an EXCLUSIVE MMAP input stream to avoid reading data too close to the DSP write position, which may cause glitches.

Starting with Oboe 1.7.1, the numFrames will be clipped internally against the BufferCapacity minus BurstSize. This is to prevent trying to wait for more frames than could possibly be available. In this case, the return value may be less than numFrames. Note that there may still be glitching if numFrames is too high.

Parameters

numFrames	requested minimum frames available
timeoutNanoseconds

Returns: number of frames available, ErrorTimeout

◆ waitForStateChange()

virtual Result oboe::AudioStream::waitForStateChange	(	StreamState	inputState,
		StreamState *	nextState,
		int64_t	timeoutNanoseconds )

pure virtual

Wait until the stream's current state no longer matches the input state. The input state is passed to avoid race conditions caused by the state changing between calls.

Note that generally applications do not need to call this. It is considered an advanced technique and is mostly used for testing.


int64_t timeoutNanos = 500 * kNanosPerMillisecond; // arbitrary 1/2 second
StreamState currentState = stream->getState();
StreamState nextState = StreamState::Unknown;
while (result == Result::OK && currentState != StreamState::Paused) {
    result = stream->waitForStateChange(
                                  currentState, &nextState, timeoutNanos);
    currentState = nextState;
}

If the state does not change within the timeout period then it will return ErrorTimeout. This is true even if timeoutNanoseconds is zero.

Parameters

inputState	The state we want to change away from.
nextState	Pointer to a variable that will be set to the new state.
timeoutNanoseconds	The maximum time to wait in nanoseconds.

Returns: Result::OK or a Result::Error.

◆ waitForStateTransition()

virtual Result oboe::AudioStream::waitForStateTransition	(	StreamState	startingState,
		StreamState	endingState,
		int64_t	timeoutNanoseconds )

protectedvirtual

Wait for a transition from one state to another.

Returns: OK if the endingState was observed, or ErrorUnexpectedState if any state that was not the startingState or endingState was observed or ErrorTimeout.

◆ wasErrorCallbackCalled()

bool oboe::AudioStream::wasErrorCallbackCalled ( )

inlineprotected

This is used to detect more than one error callback from a stream. These were bugs in some versions of Android that caused multiple error callbacks. Internal bug b/63087953

Calling this sets an atomic<bool> true and returns the previous value.

Returns: false on first call, true on subsequent calls

◆ write()

virtual ResultWithValue< int32_t > oboe::AudioStream::write	(	const void *	,
		int32_t	,
		int64_t	)

inlinevirtual

Write data from the supplied buffer into the stream. This method will block until the write is complete or it runs out of time.

If timeoutNanoseconds is zero then this call will not wait.

Parameters

buffer	The address of the first sample.
numFrames	Number of frames to write. Only complete frames will be written.
timeoutNanoseconds	Maximum number of nanoseconds to wait for completion.

Returns: a ResultWithValue which has a result of Result::OK and a value containing the number of frames actually written, or result of Result::Error*.

Member Data Documentation

◆ mFramesPerBurst

int32_t oboe::AudioStream::mFramesPerBurst = kUnspecified

protected

Number of frames which will be copied to/from the audio device in a single read/write operation

◆ mFramesRead

std::atomic<int64_t> oboe::AudioStream::mFramesRead {}

protected

Number of frames which have been read from the stream.

This is signed integer to match the counters in AAudio. At audio rates, the counter will overflow in about six million years.

◆ mFramesWritten

std::atomic<int64_t> oboe::AudioStream::mFramesWritten {}

protected

Number of frames which have been written into the stream

This is signed integer to match the counters in AAudio. At audio rates, the counter will overflow in about six million years.

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

include/oboe/AudioStream.h

Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ AudioStream()

Member Function Documentation

◆ beginPerformanceHintInCallback()

◆ calculateDefaultDelayBeforeCloseMillis()

◆ calculateLatencyMillis()

◆ close()

◆ closePerformanceHint()

◆ endPerformanceHintInCallback()

◆ fireDataCallback()

◆ firePartialDataCallback()

◆ flush()

◆ flushFromFrame()

◆ getAudioApi()

◆ getAvailableFrames()

◆ getBytesPerFrame()

◆ getBytesPerSample()

◆ getFramesPerBurst()

◆ getFramesRead()

◆ getFramesWritten()

◆ getLastErrorCallbackResult()

◆ getPlaybackParameters()

◆ getState()

◆ getTimestamp() [1/2]

◆ getTimestamp() [2/2]

◆ getUnderlyingStream()

◆ getXRunCount()

◆ isDataCallbackEnabled()

◆ isPerformanceHintEnabled()

◆ isXRunCountSupported()

◆ notifyWorkloadIncrease()

◆ notifyWorkloadReset()

◆ notifyWorkloadSpike()

◆ onDefaultCallback()

◆ open()

◆ pause()

◆ read()

◆ release()

◆ reportWorkload()

◆ requestFlush()

◆ requestPause()

◆ requestStart()

◆ requestStop()

◆ setBufferSizeInFrames()

◆ setDataCallbackEnabled()

◆ setDelayBeforeCloseMillis()

◆ setPerformanceHintEnabled()

◆ setPlaybackParameters()

◆ sleepBeforeClose()

◆ start()

◆ stop()

◆ updateFramesRead()

◆ updateFramesWritten()

◆ usesAAudio()

◆ waitForAvailableFrames()

◆ waitForStateChange()

◆ waitForStateTransition()

◆ wasErrorCallbackCalled()

◆ write()

Member Data Documentation

◆ mFramesPerBurst

◆ mFramesRead

◆ mFramesWritten