oboe Namespace Reference

Classes
class	AudioStream
class	AudioStreamBase
class	AudioStreamBuilder
class	AudioStreamCallback
class	AudioStreamDataCallback
class	AudioStreamErrorCallback
class	DefaultStreamValues
class	FifoBuffer
class	FifoControllerBase
struct	FrameTimestamp
class	FullDuplexStream
class	LatencyTuner
class	OboeExtensions
class	OboeGlobals
class	ResultWithValue
class	StabilizedCallback
struct	StreamDeleterFunctor
struct	Version

Typedefs
using	ManagedStream = std::unique_ptr< AudioStream, StreamDeleterFunctor >

Enumerations
enum class	StreamState : int32_t {   Uninitialized = 0 , Unknown = 1 , Open = 2 , Starting = 3 ,   Started = 4 , Pausing = 5 , Paused = 6 , Flushing = 7 ,   Flushed = 8 , Stopping = 9 , Stopped = 10 , Closing = 11 ,   Closed = 12 , Disconnected = 13 }
enum class	Direction : int32_t { Output = 0 , Input = 1 }
enum class	AudioFormat : int32_t {   Invalid = -1 , Unspecified = 0 , I16 = 1 , Float = 2 ,   I24 = 3 , I32 = 4 , IEC61937 = 5 }
enum class	DataCallbackResult : int32_t { Continue = 0 , Stop = 1 }
enum class	Result : int32_t {   OK = 0 , ErrorBase = -900 , ErrorDisconnected = -899 , ErrorIllegalArgument = -898 ,   ErrorInternal = -896 , ErrorInvalidState = -895 , ErrorInvalidHandle = -892 , ErrorUnimplemented = -890 ,   ErrorUnavailable = -889 , ErrorNoFreeHandles = -888 , ErrorNoMemory = -887 , ErrorNull = -886 ,   ErrorTimeout = -885 , ErrorWouldBlock = -884 , ErrorInvalidFormat = -883 , ErrorOutOfRange = -882 ,   ErrorNoService = -881 , ErrorInvalidRate = -880 , Reserved1 , Reserved2 ,   Reserved3 , Reserved4 , Reserved5 , Reserved6 ,   Reserved7 , Reserved8 , Reserved9 , Reserved10 ,   ErrorClosed = -869 }
enum class	SharingMode : int32_t { Exclusive = 0 , Shared = 1 }
enum class	PerformanceMode : int32_t { None = 10 , PowerSaving = 11 , LowLatency = 12 }
enum class	AudioApi : int32_t { Unspecified = kUnspecified , OpenSLES , AAudio }
enum class	SampleRateConversionQuality : int32_t {   None , Fastest , Low , Medium ,   High , Best }
enum class	Usage : int32_t {   Media = 1 , VoiceCommunication = 2 , VoiceCommunicationSignalling = 3 , Alarm = 4 ,   Notification = 5 , NotificationRingtone = 6 , NotificationEvent = 10 , AssistanceAccessibility = 11 ,   AssistanceNavigationGuidance = 12 , AssistanceSonification = 13 , Game = 14 , Assistant = 16 }
enum	ContentType : int32_t { Speech = 1 , Music = 2 , Movie = 3 , Sonification = 4 }
enum	InputPreset : int32_t {   Generic = 1 , Camcorder = 5 , VoiceRecognition = 6 , VoiceCommunication = 7 ,   Unprocessed = 9 , VoicePerformance = 10 }
enum	SessionId { None = -1 , Allocate = 0 }
enum	ChannelCount : int32_t { Unspecified = kUnspecified , Mono = 1 , Stereo = 2 }
enum class	ChannelMask : uint32_t {   Unspecified = kUnspecified , FrontLeft = 1 << 0 , FrontRight = 1 << 1 , FrontCenter = 1 << 2 ,   LowFrequency = 1 << 3 , BackLeft = 1 << 4 , BackRight = 1 << 5 , FrontLeftOfCenter = 1 << 6 ,   FrontRightOfCenter = 1 << 7 , BackCenter = 1 << 8 , SideLeft = 1 << 9 , SideRight = 1 << 10 ,   TopCenter = 1 << 11 , TopFrontLeft = 1 << 12 , TopFrontCenter = 1 << 13 , TopFrontRight = 1 << 14 ,   TopBackLeft = 1 << 15 , TopBackCenter = 1 << 16 , TopBackRight = 1 << 17 , TopSideLeft = 1 << 18 ,   TopSideRight = 1 << 19 , BottomFrontLeft = 1 << 20 , BottomFrontCenter = 1 << 21 , BottomFrontRight = 1 << 22 ,   LowFrequency2 = 1 << 23 , FrontWideLeft = 1 << 24 , FrontWideRight = 1 << 25 , Mono = FrontLeft ,   Stereo , CM2Point1 , Tri , TriBack ,   CM3Point1 , CM2Point0Point2 , CM2Point1Point2 , CM3Point0Point2 ,   CM3Point1Point2 , Quad , QuadSide , Surround ,   Penta , CM5Point1 , CM5Point1Side , CM6Point1 ,   CM7Point1 , CM5Point1Point2 , CM5Point1Point4 , CM7Point1Point2 ,   CM7Point1Point4 , CM9Point1Point4 , CM9Point1Point6 , FrontBack }
enum class	SpatializationBehavior : int32_t { Unspecified = kUnspecified , Auto = 1 , Never = 2 }
enum class	PrivacySensitiveMode : int32_t { Unspecified = kUnspecified , Disabled = 1 , Enabled = 2 }
enum class	AllowedCapturePolicy : int32_t { Unspecified = kUnspecified , All = 1 , System = 2 , None = 3 }

Functions
template<typename T >
std::ostream &	operator<< (std::ostream &strm, const ResultWithValue< T > &result)
void	convertFloatToPcm16 (const float *source, int16_t *destination, int32_t numSamples)
void	convertPcm16ToFloat (const int16_t *source, float *destination, int32_t numSamples)
int32_t	convertFormatToSizeInBytes (AudioFormat format)
template<typename FromType >
const char *	convertToText (FromType input)
std::string	getPropertyString (const char *name)
int	getPropertyInteger (const char *name, int defaultValue)
int	getSdkVersion ()
bool	isAtLeastPreReleaseCodename (const std::string &codename)
int	getChannelCountFromChannelMask (ChannelMask channelMask)
const char *	getVersionText ()

Variables
constexpr int64_t	kDefaultTimeoutNanos = (2000 * kNanosPerMillisecond)
constexpr int32_t	kUnspecified = 0
constexpr int64_t	kNanosPerMicrosecond = 1000
constexpr int64_t	kNanosPerMillisecond = kNanosPerMicrosecond * 1000
constexpr int64_t	kMillisPerSecond = 1000
constexpr int64_t	kNanosPerSecond = kNanosPerMillisecond * kMillisPerSecond

Detailed Description

WARNING - UNDER CONSTRUCTION - THIS API WILL CHANGE.

Enumeration Type Documentation

AllowedCapturePolicy

enum class oboe::AllowedCapturePolicy : int32_t

strong

Specifies whether audio may or may not be captured by other apps or the system for an output stream.

Note that these match the equivalent values in AudioAttributes in the Android Java API.

Added in API level 29 for AAudio.

Enumerator
Unspecified	When not explicitly requested, set privacy sensitive mode according to the Usage. This should behave similarly to setting AllowedCapturePolicy::All.
All	Indicates that the audio may be captured by any app. For privacy, the following Usages can not be recorded: VoiceCommunication*, Notification*, Assistance* and Assistant. On Android Q, only Usage::Game and Usage::Media may be captured. See ALLOW_CAPTURE_BY_ALL in the AudioAttributes Java API.
System	Indicates that the audio may only be captured by system apps. System apps can capture for many purposes like accessibility, user guidance... but have strong restriction. See ALLOW_CAPTURE_BY_SYSTEM in the AudioAttributes Java API for what the system apps can do with the capture audio.
None	Indicates that the audio may not be recorded by any app, even if it is a system app. It is encouraged to use AllowedCapturePolicy::System instead of this value as system apps provide significant and useful features for the user (eg. accessibility). See ALLOW_CAPTURE_BY_NONE in the AudioAttributes Java API

AudioApi

enum class oboe::AudioApi : int32_t

strong

The underlying audio API used by the audio stream.

Enumerator
Unspecified	Try to use AAudio. If not available then use OpenSL ES.
OpenSLES	Use OpenSL ES. Note that OpenSL ES is deprecated in Android 13, API 30 and above.
AAudio	Try to use AAudio. Fail if unavailable. AAudio was first supported in Android 8, API 26 and above. It is only recommended for API 27 and above.

AudioFormat

enum class oboe::AudioFormat : int32_t

strong

The format of audio samples.

Enumerator
Invalid	Invalid format.
Unspecified	Unspecified format. Format will be decided by Oboe. When calling getHardwareFormat(), this will be returned if the API is not supported.
I16	Signed 16-bit integers.
Float	Single precision floating point. This is the recommended format for most applications. But note that the use of Float may prevent the opening of a low-latency input path on OpenSL ES or Legacy AAudio streams.
I24	Signed 24-bit integers, packed into 3 bytes. Note that the use of this format does not guarantee that the full precision will be provided. The underlying device may be using I16 format. Added in API 31 (S).
I32	Signed 32-bit integers. Note that the use of this format does not guarantee that the full precision will be provided. The underlying device may be using I16 format. Added in API 31 (S).
IEC61937	This format is used for compressed audio wrapped in IEC61937 for HDMI or S/PDIF passthrough. Unlike PCM playback, the Android framework is not able to do format conversion for IEC61937. In that case, when IEC61937 is requested, sampling rate and channel count or channel mask must be specified. Otherwise, it may fail when opening the stream. Apps are able to get the correct configuration for the playback by calling AudioManager::getDevices(int). Available since API 34 (U).

ChannelCount

enum oboe::ChannelCount : int32_t

The channel count of the audio stream. The underlying type is int32_t. Use of this enum is convenient to avoid "magic" numbers when specifying the channel count.

For example, you can write builder.setChannelCount(ChannelCount::Stereo) rather than builder.setChannelCount(2)

Enumerator
Unspecified	Audio channel count definition, use Mono or Stereo
Mono	Use this for mono audio
Stereo	Use this for stereo audio.

ChannelMask

enum class oboe::ChannelMask : uint32_t

strong

The channel mask of the audio stream. The underlying type is uint32_t. Use of this enum is convenient.

ChannelMask::Unspecified means this is not specified. The rest of the enums are channel position masks. Use the combinations of the channel position masks defined below instead of using those values directly.

Channel masks are for input only, output only, or both input and output. These channel masks are different than those defined in AudioFormat.java. If an app gets a channel mask from Java API and wants to use it in Oboe, conversion should be done by the app.

Enumerator
Mono	Supported for Input and Output
Stereo	Supported for Input and Output
CM2Point1	Supported for only Output
Tri	Supported for only Output
TriBack	Supported for only Output
CM3Point1	Supported for only Output
CM2Point0Point2	Supported for Input and Output
CM2Point1Point2	Supported for Input and Output
CM3Point0Point2	Supported for Input and Output
CM3Point1Point2	Supported for Input and Output
Quad	Supported for only Output
QuadSide	Supported for only Output
Surround	Supported for only Output
Penta	Supported for only Output
CM5Point1	Supported for Input and Output. aka 5Point1Back
CM5Point1Side	Supported for only Output
CM6Point1	Supported for only Output
CM7Point1	Supported for only Output
CM5Point1Point2	Supported for only Output
CM5Point1Point4	Supported for only Output
CM7Point1Point2	Supported for only Output
CM7Point1Point4	Supported for only Output
CM9Point1Point4	Supported for only Output
CM9Point1Point6	Supported for only Output
FrontBack	Supported for only Input

ContentType

enum oboe::ContentType : int32_t

The ContentType attribute describes what you are playing. It expresses the general category of the content. This information is optional. But in case it is known (for instance Movie for a movie streaming service or Speech for an audio book application) this information might be used by the audio framework to enforce audio focus.

Note that these match the equivalent values in AudioAttributes in the Android Java API.

This attribute only has an effect on Android API 28+.

Enumerator
Speech	Use this for spoken voice, audio books, etcetera.
Music	Use this for pre-recorded or live music.
Movie	Use this for a movie or video soundtrack.
Sonification	Use this for sound is designed to accompany a user action, such as a click or beep sound made when the user presses a button.

DataCallbackResult

enum class oboe::DataCallbackResult : int32_t

strong

The result of an audio callback.

Direction

enum class oboe::Direction : int32_t

strong

The direction of the stream.

Enumerator
Output	Used for playback.
Input	Used for recording.

InputPreset

enum oboe::InputPreset : int32_t

Defines the audio source. An audio source defines both a default physical source of audio signal, and a recording configuration.

Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API.

This attribute only has an effect on Android API 28+.

Enumerator
Generic	Use this preset when other presets do not apply.
Camcorder	Use this preset when recording video.
VoiceRecognition	Use this preset when doing speech recognition.
VoiceCommunication	Use this preset when doing telephony or voice messaging.
Unprocessed	Use this preset to obtain an input with no effects. Note that this input will not have automatic gain control so the recorded volume may be very low.
VoicePerformance	Use this preset for capturing audio meant to be processed in real time and played back for live performance (e.g karaoke). The capture path will minimize latency and coupling with playback path.

PerformanceMode

enum class oboe::PerformanceMode : int32_t

strong

The performance mode of the audio stream.

Enumerator
None	No particular performance needs. Default.
PowerSaving	Extending battery life is most important.
LowLatency	Reducing latency is most important.

PrivacySensitiveMode

enum class oboe::PrivacySensitiveMode : int32_t

strong

The PrivacySensitiveMode attribute determines whether an input stream can be shared with another privileged app, for example the Assistant.

This allows to override the default behavior tied to the audio source (e.g InputPreset::VoiceCommunication is private by default but InputPreset::Unprocessed is not).

Enumerator
Unspecified	When not explicitly requested, set privacy sensitive mode according to input preset: communication and camcorder captures are considered privacy sensitive by default.
Disabled	Privacy sensitive mode disabled.
Enabled	Privacy sensitive mode enabled.

Result

enum class oboe::Result : int32_t

strong

The result of an operation. All except the OK result indicates that an error occurred. The Result can be converted into a human readable string using convertToText.

SampleRateConversionQuality

enum class oboe::SampleRateConversionQuality : int32_t

strong

Specifies the quality of the sample rate conversion performed by Oboe. Higher quality will require more CPU load. Higher quality conversion will probably be implemented using a sinc based resampler.

Enumerator
None	No conversion by Oboe. Underlying APIs may still do conversion.
Fastest	Fastest conversion but may not sound great. This may be implemented using bilinear interpolation.
Low	Low quality conversion with 8 taps.
Medium	Medium quality conversion with 16 taps.
High	High quality conversion with 32 taps.
Best	Highest quality conversion, which may be expensive in terms of CPU.

SessionId

enum oboe::SessionId

This attribute can be used to allocate a session ID to the audio stream.

This attribute only has an effect on Android API 28+.

Enumerator
None	Do not allocate a session ID. Effects cannot be used with this stream. Default.
Allocate	Allocate a session ID that can be used to attach and control effects using the Java AudioEffects API. Note that the use of this flag may result in higher latency. Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE.

SharingMode

enum class oboe::SharingMode : int32_t

strong

The sharing mode of the audio stream.

Enumerator
Exclusive	This will be the only stream using a particular source or sink. This mode will provide the lowest possible latency. You should close EXCLUSIVE streams immediately when you are not using them. If you do not need the lowest possible latency then we recommend using Shared, which is the default.
Shared	Multiple applications can share the same device. The data from output streams will be mixed by the audio service. The data for input streams will be distributed by the audio service. This will have higher latency than the EXCLUSIVE mode.

SpatializationBehavior

enum class oboe::SpatializationBehavior : int32_t

strong

The spatialization behavior of the audio stream.

Enumerator
Unspecified	Constant indicating that the spatialization behavior is not specified.
Auto	Constant indicating the audio content associated with these attributes will follow the default platform behavior with regards to which content will be spatialized or not.
Never	Constant indicating the audio content associated with these attributes should never be spatialized.

StreamState

enum class oboe::StreamState : int32_t

strong

The state of the audio stream.

Usage

enum class oboe::Usage : int32_t

strong

The Usage attribute expresses why you are playing a sound, what is this sound used for. This information is used by certain platforms or routing policies to make more refined volume or routing decisions.

Note that these match the equivalent values in AudioAttributes in the Android Java API.

This attribute only has an effect on Android API 28+.

Enumerator
Media	Use this for streaming media, music performance, video, podcasts, etcetera.
VoiceCommunication	Use this for voice over IP, telephony, etcetera.
VoiceCommunicationSignalling	Use this for sounds associated with telephony such as busy tones, DTMF, etcetera.
Alarm	Use this to demand the users attention.
Notification	Use this for notifying the user when a message has arrived or some other background event has occured.
NotificationRingtone	Use this when the phone rings.
NotificationEvent	Use this to attract the users attention when, for example, the battery is low.
AssistanceAccessibility	Use this for screen readers, etcetera.
AssistanceNavigationGuidance	Use this for driving or navigation directions.
AssistanceSonification	Use this for user interface sounds, beeps, etcetera.
Game	Use this for game audio and sound effects.
Assistant	Use this for audio responses to user queries, audio instructions or help utterances.

Function Documentation

convertFloatToPcm16()

void oboe::convertFloatToPcm16	(	const float *	source,
		int16_t *	destination,
		int32_t	numSamples
	)

Convert an array of floats to an array of 16-bit integers.

Parameters

source	the input array.
destination	the output array.
numSamples	the number of values to convert.

convertFormatToSizeInBytes()

int32_t oboe::convertFormatToSizeInBytes

(

AudioFormat

format

)

Returns

the size of a sample of the given format in bytes or 0 if format is invalid

convertPcm16ToFloat()

void oboe::convertPcm16ToFloat	(	const int16_t *	source,
		float *	destination,
		int32_t	numSamples
	)

Convert an array of 16-bit integers to an array of floats.

Parameters

source	the input array.
destination	the output array.
numSamples	the number of values to convert.

convertToText()

template<typename FromType >

const char * oboe::convertToText

(

FromType

input

)

The text is the ASCII symbol corresponding to the supplied Oboe enum value, or an English message saying the value is unrecognized. This is intended for developers to use when debugging. It is not for displaying to users.

Parameters

input

object to convert from.

See also

common/Utilities.cpp for concrete implementations

Returns

text representation of an Oboe enum value. There is no need to call free on this.

getPropertyInteger()

int oboe::getPropertyInteger	(	const char *	name,
		int	defaultValue
	)

Parameters

name
defaultValue

Returns

integer value associated with a property or the default value

getPropertyString()

std::string oboe::getPropertyString

(

const char *

name

)

Parameters

name

Returns

the value of a named system property in a string or empty string

getSdkVersion()

int oboe::getSdkVersion

(

)

Return the version of the SDK that is currently running.

For example, on Android, this would return 27 for Oreo 8.1. If the version number cannot be determined then this will return -1.

Returns

version number or -1

isAtLeastPreReleaseCodename()

bool oboe::isAtLeastPreReleaseCodename

(

const std::string &

codename

)

Returns whether a device is on a pre-release SDK that is at least the specified codename version.

Parameters

codename

the code name to verify.

Returns

boolean of whether the device is on a pre-release SDK and is at least the specified codename

operator<<()

template<typename T >

std::ostream & oboe::operator<<	(	std::ostream &	strm,
		const ResultWithValue< T > &	result
	)

If the result is OK then return the value, otherwise return a human-readable error message.

Variable Documentation

kDefaultTimeoutNanos

constexpr int64_t oboe::kDefaultTimeoutNanos = (2000 * kNanosPerMillisecond)

constexpr

The default number of nanoseconds to wait for when performing state change operations on the stream, such as start and stop.

See also

oboe::AudioStream::start

kMillisPerSecond

constexpr int64_t oboe::kMillisPerSecond = 1000

constexpr

The number of milliseconds in a second. 1,000.

kNanosPerMicrosecond

constexpr int64_t oboe::kNanosPerMicrosecond = 1000

constexpr

The number of nanoseconds in a microsecond. 1,000.

kNanosPerMillisecond

constexpr int64_t oboe::kNanosPerMillisecond = kNanosPerMicrosecond * 1000

constexpr

The number of nanoseconds in a millisecond. 1,000,000.

kNanosPerSecond

constexpr int64_t oboe::kNanosPerSecond = kNanosPerMillisecond * kMillisPerSecond

constexpr

The number of nanoseconds in a second. 1,000,000,000.

kUnspecified

constexpr int32_t oboe::kUnspecified = 0

constexpr

Represents any attribute, property or value which hasn't been specified.