Oboe 1.5 A library for creating real-time audio apps on Android

Classes | Typedefs | Enumerations | Functions | Variables
oboe Namespace Reference

## Classes
class | AudioStream
class | AudioStreamBase
class | AudioStreamBuilder
class | AudioStreamCallback
class | AudioStreamDataCallback
class | AudioStreamErrorCallback
class | DefaultStreamValues
struct | FrameTimestamp
class | LatencyTuner
class | OboeGlobals
class | ResultWithValue
class | StabilizedCallback
struct | StreamDeleterFunctor
struct | Version

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

## Enumerations
enum | 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 | Direction : int32_t { Direction::Output = 0, Direction::Input = 1 }
enum | AudioFormat : int32_t { AudioFormat::Invalid = -1, Unspecified = 0, AudioFormat::I16 = 1, AudioFormat::Float = 2 }
enum | DataCallbackResult : int32_t { Continue = 0, Stop = 1 }
enum | 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 }
enum | SharingMode : int32_t { SharingMode::Exclusive = 0, SharingMode::Shared = 1 }
enum | PerformanceMode : int32_t { None = 10, PerformanceMode::PowerSaving = 11, PerformanceMode::LowLatency = 12 }
enum | AudioApi : int32_t { Unspecified = kUnspecified, AudioApi::OpenSLES, AudioApi::AAudio }
enum | SampleRateConversionQuality : int32_t { None, SampleRateConversionQuality::Fastest, Low, Medium, High, SampleRateConversionQuality::Best }
enum | Usage : int32_t { Usage::Media = 1, VoiceCommunication = 2, Usage::VoiceCommunicationSignalling = 3, Usage::Alarm = 4, Usage::Notification = 5, Usage::NotificationRingtone = 6, Usage::NotificationEvent = 10, Usage::AssistanceAccessibility = 11, Usage::AssistanceNavigationGuidance = 12, Usage::AssistanceSonification = 13, Usage::Game = 14, Usage::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, VoiceCommunication = 2, Unprocessed = 9, VoicePerformance = 10 }
enum | SessionId { None = -1, None = 10, None, Allocate = 0 }
enum | ChannelCount : int32_t { Unspecified = kUnspecified, Unspecified = 0, Unspecified = kUnspecified, Mono = 1, Stereo = 2 }

## 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 ()
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 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.
AAudio | Try to use AAudio. Fail if unavailable.

## ◆ AudioFormat

enum 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 points.

## ◆ 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
Unspecified | Unspecified format. Format will be decided by Oboe.
Unspecified | Try to use AAudio. If not available then use OpenSL ES.
Mono | Use this for mono audio
Stereo | Use this for stereo audio.

## ◆ 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 oboe::DataCallbackResult : int32_t
| strong

The result of an audio callback.

## ◆ Direction

enum 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.
VoiceCommunication | Use this for voice over IP, telephony, etcetera.
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 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 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 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

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.
None | No particular performance needs. Default.
None | No conversion by Oboe. Underlying APIs may still do conversion.
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 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 oboe::StreamState : int32_t
| strong

The state of the audio stream.

## ◆ Usage

enum 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

## ◆ 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)

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

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

## ◆ kNanosPerMicrosecond

constexpr int64_t oboe::kNanosPerMicrosecond = 1000

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

## ◆ kNanosPerMillisecond

constexpr int64_t oboe::kNanosPerMillisecond = kNanosPerMicrosecond * 1000

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

## ◆ kNanosPerSecond

constexpr int64_t oboe::kNanosPerSecond = kNanosPerMillisecond * kMillisPerSecond

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

## ◆ kUnspecified

constexpr int32_t oboe::kUnspecified = 0

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