#include <AudioStream.h>
Protected Member Functions | |
| bool | wasErrorCallbackCalled () |
| virtual Result | waitForStateTransition (StreamState startingState, StreamState endingState, int64_t timeoutNanoseconds) |
| virtual DataCallbackResult | onDefaultCallback (void *, int) |
| DataCallbackResult | fireDataCallback (void *audioData, int numFrames) |
| bool | isDataCallbackEnabled () |
| void | setDataCallbackEnabled (bool enabled) |
| 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 |
| Protected Attributes inherited from oboe::AudioStreamBase | |
| AudioStreamDataCallback * | mDataCallback = nullptr |
| AudioStreamErrorCallback * | mErrorCallback = 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 |
| bool | mChannelConversionAllowed = false |
| bool | mFormatConversionAllowed = false |
| SampleRateConversionQuality | mSampleRateConversionQuality = SampleRateConversionQuality::None |
Friends | |
| class | AudioStreamBuilder |
Detailed Description
Base class for Oboe C++ audio stream.
Constructor & Destructor Documentation
◆ AudioStream()
|
explicit |
Construct an AudioStream using the given AudioStreamBuilder
- Parameters
-
builder containing all the stream's attributes
Member Function Documentation
◆ 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.
- 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 |
Close the stream and deallocate any resources from the open() call.
◆ fireDataCallback()
|
protected |
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
◆ flush()
|
virtual |
Flush the stream. This will block until the stream has been flushed, an error occurs or timeoutNanoseconds has been reached.
◆ getAudioApi()
|
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()
|
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.
- 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.
- Returns
- the number of bytes per sample.
◆ getFramesPerBurst()
|
pure virtual |
Query the number of frames that are read or written by the endpoint at one time.
- Returns
- burst size
◆ 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 |
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()
|
inlinevirtual |
- Returns
- last result passed from an error callback
◆ getState()
|
pure virtual |
Query the current state, eg. StreamState::Pausing
- Returns
- state or a negative error.
◆ getTimestamp() [1/2]
|
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.
- 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
◆ getTimestamp() [2/2]
|
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.
- 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.
◆ getUnderlyingStream()
|
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()
|
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()
|
inlineprotected |
- Returns
- true if callbacks may be called
◆ isXRunCountSupported()
|
pure virtual |
- Returns
- true if XRun counts are supported on the stream
◆ launchStopThread()
| void oboe::AudioStream::launchStopThread | ( | ) |
Launch a thread that will stop the stream.
◆ onDefaultCallback()
|
inlineprotectedvirtual |
Override this to provide a default for when the application did not specify a callback.
- Parameters
-
audioData numFrames
- Returns
- result
◆ 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 |
Pause the stream. This will block until the stream has been paused, an error occurs or timeoutNanoseconds has been reached.
◆ read()
|
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*.
◆ requestFlush()
|
pure virtual |
Flush the stream asynchronously. Returns immediately (does not block). Equivalent to calling flush(0).
◆ requestPause()
|
pure virtual |
Pause the stream asynchronously. Returns immediately (does not block). Equivalent to calling pause(0).
◆ requestStart()
|
pure virtual |
Start the stream asynchronously. Returns immediately (does not block). Equivalent to calling start(0).
◆ requestStop()
|
pure virtual |
Stop the stream asynchronously. Returns immediately (does not block). Equivalent to calling stop(0).
◆ setBufferSizeInFrames()
|
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().
- 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()
|
inlineprotected |
This can be set false internally to prevent callbacks after DataCallbackResult::Stop has been returned.
◆ start()
|
virtual |
Start the stream. This will block until the stream has been started, an error occurs or timeoutNanoseconds has been reached.
◆ stop()
|
virtual |
Stop the stream. This will block until the stream has been stopped, an error occurs or timeoutNanoseconds has been reached.
◆ updateFramesRead()
|
pure virtual |
Update mFramesRead. For internal use only.
◆ updateFramesWritten()
|
pure virtual |
Update mFramesWritten. For internal use only.
◆ usesAAudio()
|
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.
- Parameters
-
numFrames minimum frames available timeoutNanoseconds
- Returns
- number of frames available, ErrorTimeout
◆ waitForStateChange()
|
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()
|
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()
|
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()
|
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
◆ 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
|
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
