Oboe
A library for creating real-time audio apps on Android
Loading...
Searching...
No Matches
Classes | Typedefs | Enumerations | Functions | Variables
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  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
}
 
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
}
 

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 ()
 
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

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

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

◆ 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

Enumerator
Unspecified 

Audio channel mask is not specified.

FrontLeft 

Channel position masks. Use the combinations of the channel position masks defined below instead of using those values directly.

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

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

Best 

Highest quality conversion, which may be expensive in terms of CPU.

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

◆ 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
sourcethe input array.
destinationthe output array.
numSamplesthe 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
sourcethe input array.
destinationthe output array.
numSamplesthe 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
inputobject 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

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