1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef OBOE_DEFINITIONS_H 18 #define OBOE_DEFINITIONS_H 19 20 21 #include <cstdint> 22 #include <type_traits> 23 24 // Oboe needs to be able to build on old NDKs so we use hard coded constants. 25 // The correctness of these constants is verified in "aaudio/AAudioLoader.cpp". 26 27 namespace oboe { 28 29 /** 30 * Represents any attribute, property or value which hasn't been specified. 31 */ 32 constexpr int32_t kUnspecified = 0; 33 34 // TODO: Investigate using std::chrono 35 /** 36 * The number of nanoseconds in a microsecond. 1,000. 37 */ 38 constexpr int64_t kNanosPerMicrosecond = 1000; 39 40 /** 41 * The number of nanoseconds in a millisecond. 1,000,000. 42 */ 43 constexpr int64_t kNanosPerMillisecond = kNanosPerMicrosecond * 1000; 44 45 /** 46 * The number of milliseconds in a second. 1,000. 47 */ 48 constexpr int64_t kMillisPerSecond = 1000; 49 50 /** 51 * The number of nanoseconds in a second. 1,000,000,000. 52 */ 53 constexpr int64_t kNanosPerSecond = kNanosPerMillisecond * kMillisPerSecond; 54 55 /** 56 * The state of the audio stream. 57 */ 58 enum class StreamState : int32_t { // aaudio_stream_state_t 59 Uninitialized = 0, // AAUDIO_STREAM_STATE_UNINITIALIZED, 60 Unknown = 1, // AAUDIO_STREAM_STATE_UNKNOWN, 61 Open = 2, // AAUDIO_STREAM_STATE_OPEN, 62 Starting = 3, // AAUDIO_STREAM_STATE_STARTING, 63 Started = 4, // AAUDIO_STREAM_STATE_STARTED, 64 Pausing = 5, // AAUDIO_STREAM_STATE_PAUSING, 65 Paused = 6, // AAUDIO_STREAM_STATE_PAUSED, 66 Flushing = 7, // AAUDIO_STREAM_STATE_FLUSHING, 67 Flushed = 8, // AAUDIO_STREAM_STATE_FLUSHED, 68 Stopping = 9, // AAUDIO_STREAM_STATE_STOPPING, 69 Stopped = 10, // AAUDIO_STREAM_STATE_STOPPED, 70 Closing = 11, // AAUDIO_STREAM_STATE_CLOSING, 71 Closed = 12, // AAUDIO_STREAM_STATE_CLOSED, 72 Disconnected = 13, // AAUDIO_STREAM_STATE_DISCONNECTED, 73 }; 74 75 /** 76 * The direction of the stream. 77 */ 78 enum class Direction : int32_t { // aaudio_direction_t 79 80 /** 81 * Used for playback. 82 */ 83 Output = 0, // AAUDIO_DIRECTION_OUTPUT, 84 85 /** 86 * Used for recording. 87 */ 88 Input = 1, // AAUDIO_DIRECTION_INPUT, 89 }; 90 91 /** 92 * The format of audio samples. 93 */ 94 enum class AudioFormat : int32_t { // aaudio_format_t 95 /** 96 * Invalid format. 97 */ 98 Invalid = -1, // AAUDIO_FORMAT_INVALID, 99 100 /** 101 * Unspecified format. Format will be decided by Oboe. 102 */ 103 Unspecified = 0, // AAUDIO_FORMAT_UNSPECIFIED, 104 105 /** 106 * Signed 16-bit integers. 107 */ 108 I16 = 1, // AAUDIO_FORMAT_PCM_I16, 109 110 /** 111 * Single precision floating points. 112 */ 113 Float = 2, // AAUDIO_FORMAT_PCM_FLOAT, 114 }; 115 116 /** 117 * The result of an audio callback. 118 */ 119 enum class DataCallbackResult : int32_t { // aaudio_data_callback_result_t 120 // Indicates to the caller that the callbacks should continue. 121 Continue = 0, // AAUDIO_CALLBACK_RESULT_CONTINUE, 122 123 // Indicates to the caller that the callbacks should stop immediately. 124 Stop = 1, // AAUDIO_CALLBACK_RESULT_STOP, 125 }; 126 127 /** 128 * The result of an operation. All except the `OK` result indicates that an error occurred. 129 * The `Result` can be converted into a human readable string using `convertToText`. 130 */ 131 enum class Result : int32_t { // aaudio_result_t 132 OK = 0, // AAUDIO_OK 133 ErrorBase = -900, // AAUDIO_ERROR_BASE, 134 ErrorDisconnected = -899, // AAUDIO_ERROR_DISCONNECTED, 135 ErrorIllegalArgument = -898, // AAUDIO_ERROR_ILLEGAL_ARGUMENT, 136 ErrorInternal = -896, // AAUDIO_ERROR_INTERNAL, 137 ErrorInvalidState = -895, // AAUDIO_ERROR_INVALID_STATE, 138 ErrorInvalidHandle = -892, // AAUDIO_ERROR_INVALID_HANDLE, 139 ErrorUnimplemented = -890, // AAUDIO_ERROR_UNIMPLEMENTED, 140 ErrorUnavailable = -889, // AAUDIO_ERROR_UNAVAILABLE, 141 ErrorNoFreeHandles = -888, // AAUDIO_ERROR_NO_FREE_HANDLES, 142 ErrorNoMemory = -887, // AAUDIO_ERROR_NO_MEMORY, 143 ErrorNull = -886, // AAUDIO_ERROR_NULL, 144 ErrorTimeout = -885, // AAUDIO_ERROR_TIMEOUT, 145 ErrorWouldBlock = -884, // AAUDIO_ERROR_WOULD_BLOCK, 146 ErrorInvalidFormat = -883, // AAUDIO_ERROR_INVALID_FORMAT, 147 ErrorOutOfRange = -882, // AAUDIO_ERROR_OUT_OF_RANGE, 148 ErrorNoService = -881, // AAUDIO_ERROR_NO_SERVICE, 149 ErrorInvalidRate = -880, // AAUDIO_ERROR_INVALID_RATE, 150 // Reserved for future AAudio result types 151 Reserved1, 152 Reserved2, 153 Reserved3, 154 Reserved4, 155 Reserved5, 156 Reserved6, 157 Reserved7, 158 Reserved8, 159 Reserved9, 160 Reserved10, 161 ErrorClosed, 162 }; 163 164 /** 165 * The sharing mode of the audio stream. 166 */ 167 enum class SharingMode : int32_t { // aaudio_sharing_mode_t 168 169 /** 170 * This will be the only stream using a particular source or sink. 171 * This mode will provide the lowest possible latency. 172 * You should close EXCLUSIVE streams immediately when you are not using them. 173 * 174 * If you do not need the lowest possible latency then we recommend using Shared, 175 * which is the default. 176 */ 177 Exclusive = 0, // AAUDIO_SHARING_MODE_EXCLUSIVE, 178 179 /** 180 * Multiple applications can share the same device. 181 * The data from output streams will be mixed by the audio service. 182 * The data for input streams will be distributed by the audio service. 183 * 184 * This will have higher latency than the EXCLUSIVE mode. 185 */ 186 Shared = 1, // AAUDIO_SHARING_MODE_SHARED, 187 }; 188 189 /** 190 * The performance mode of the audio stream. 191 */ 192 enum class PerformanceMode : int32_t { // aaudio_performance_mode_t 193 194 /** 195 * No particular performance needs. Default. 196 */ 197 None = 10, // AAUDIO_PERFORMANCE_MODE_NONE, 198 199 /** 200 * Extending battery life is most important. 201 */ 202 PowerSaving = 11, // AAUDIO_PERFORMANCE_MODE_POWER_SAVING, 203 204 /** 205 * Reducing latency is most important. 206 */ 207 LowLatency = 12, // AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 208 }; 209 210 /** 211 * The underlying audio API used by the audio stream. 212 */ 213 enum class AudioApi : int32_t { 214 /** 215 * Try to use AAudio. If not available then use OpenSL ES. 216 */ 217 Unspecified = kUnspecified, 218 219 /** 220 * Use OpenSL ES. 221 */ 222 OpenSLES, 223 224 /** 225 * Try to use AAudio. Fail if unavailable. 226 */ 227 AAudio 228 }; 229 230 /** 231 * Specifies the quality of the sample rate conversion performed by Oboe. 232 * Higher quality will require more CPU load. 233 * Higher quality conversion will probably be implemented using a sinc based resampler. 234 */ 235 enum class SampleRateConversionQuality : int32_t { 236 /** 237 * No conversion by Oboe. Underlying APIs may still do conversion. 238 */ 239 None, 240 /** 241 * Fastest conversion but may not sound great. 242 * This may be implemented using bilinear interpolation. 243 */ 244 Fastest, 245 Low, 246 Medium, 247 High, 248 /** 249 * Highest quality conversion, which may be expensive in terms of CPU. 250 */ 251 Best, 252 }; 253 254 /** 255 * The Usage attribute expresses *why* you are playing a sound, what is this sound used for. 256 * This information is used by certain platforms or routing policies 257 * to make more refined volume or routing decisions. 258 * 259 * Note that these match the equivalent values in AudioAttributes in the Android Java API. 260 * 261 * This attribute only has an effect on Android API 28+. 262 */ 263 enum class Usage : int32_t { // aaudio_usage_t 264 /** 265 * Use this for streaming media, music performance, video, podcasts, etcetera. 266 */ 267 Media = 1, // AAUDIO_USAGE_MEDIA 268 269 /** 270 * Use this for voice over IP, telephony, etcetera. 271 */ 272 VoiceCommunication = 2, // AAUDIO_USAGE_VOICE_COMMUNICATION 273 274 /** 275 * Use this for sounds associated with telephony such as busy tones, DTMF, etcetera. 276 */ 277 VoiceCommunicationSignalling = 3, // AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING 278 279 /** 280 * Use this to demand the users attention. 281 */ 282 Alarm = 4, // AAUDIO_USAGE_ALARM 283 284 /** 285 * Use this for notifying the user when a message has arrived or some 286 * other background event has occured. 287 */ 288 Notification = 5, // AAUDIO_USAGE_NOTIFICATION 289 290 /** 291 * Use this when the phone rings. 292 */ 293 NotificationRingtone = 6, // AAUDIO_USAGE_NOTIFICATION_RINGTONE 294 295 /** 296 * Use this to attract the users attention when, for example, the battery is low. 297 */ 298 NotificationEvent = 10, // AAUDIO_USAGE_NOTIFICATION_EVENT 299 300 /** 301 * Use this for screen readers, etcetera. 302 */ 303 AssistanceAccessibility = 11, // AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY 304 305 /** 306 * Use this for driving or navigation directions. 307 */ 308 AssistanceNavigationGuidance = 12, // AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE 309 310 /** 311 * Use this for user interface sounds, beeps, etcetera. 312 */ 313 AssistanceSonification = 13, // AAUDIO_USAGE_ASSISTANCE_SONIFICATION 314 315 /** 316 * Use this for game audio and sound effects. 317 */ 318 Game = 14, // AAUDIO_USAGE_GAME 319 320 /** 321 * Use this for audio responses to user queries, audio instructions or help utterances. 322 */ 323 Assistant = 16, // AAUDIO_USAGE_ASSISTANT 324 }; 325 326 327 /** 328 * The ContentType attribute describes *what* you are playing. 329 * It expresses the general category of the content. This information is optional. 330 * But in case it is known (for instance {@link Movie} for a 331 * movie streaming service or {@link Speech} for 332 * an audio book application) this information might be used by the audio framework to 333 * enforce audio focus. 334 * 335 * Note that these match the equivalent values in AudioAttributes in the Android Java API. 336 * 337 * This attribute only has an effect on Android API 28+. 338 */ 339 enum ContentType : int32_t { // aaudio_content_type_t 340 341 /** 342 * Use this for spoken voice, audio books, etcetera. 343 */ 344 Speech = 1, // AAUDIO_CONTENT_TYPE_SPEECH 345 346 /** 347 * Use this for pre-recorded or live music. 348 */ 349 Music = 2, // AAUDIO_CONTENT_TYPE_MUSIC 350 351 /** 352 * Use this for a movie or video soundtrack. 353 */ 354 Movie = 3, // AAUDIO_CONTENT_TYPE_MOVIE 355 356 /** 357 * Use this for sound is designed to accompany a user action, 358 * such as a click or beep sound made when the user presses a button. 359 */ 360 Sonification = 4, // AAUDIO_CONTENT_TYPE_SONIFICATION 361 }; 362 363 /** 364 * Defines the audio source. 365 * An audio source defines both a default physical source of audio signal, and a recording 366 * configuration. 367 * 368 * Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API. 369 * 370 * This attribute only has an effect on Android API 28+. 371 */ 372 enum InputPreset : int32_t { // aaudio_input_preset_t 373 /** 374 * Use this preset when other presets do not apply. 375 */ 376 Generic = 1, // AAUDIO_INPUT_PRESET_GENERIC 377 378 /** 379 * Use this preset when recording video. 380 */ 381 Camcorder = 5, // AAUDIO_INPUT_PRESET_CAMCORDER 382 383 /** 384 * Use this preset when doing speech recognition. 385 */ 386 VoiceRecognition = 6, // AAUDIO_INPUT_PRESET_VOICE_RECOGNITION 387 388 /** 389 * Use this preset when doing telephony or voice messaging. 390 */ 391 VoiceCommunication = 7, // AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION 392 393 /** 394 * Use this preset to obtain an input with no effects. 395 * Note that this input will not have automatic gain control 396 * so the recorded volume may be very low. 397 */ 398 Unprocessed = 9, // AAUDIO_INPUT_PRESET_UNPROCESSED 399 400 /** 401 * Use this preset for capturing audio meant to be processed in real time 402 * and played back for live performance (e.g karaoke). 403 * The capture path will minimize latency and coupling with playback path. 404 */ 405 VoicePerformance = 10, // AAUDIO_INPUT_PRESET_VOICE_PERFORMANCE 406 407 }; 408 409 /** 410 * This attribute can be used to allocate a session ID to the audio stream. 411 * 412 * This attribute only has an effect on Android API 28+. 413 */ 414 enum SessionId { 415 /** 416 * Do not allocate a session ID. 417 * Effects cannot be used with this stream. 418 * Default. 419 */ 420 None = -1, // AAUDIO_SESSION_ID_NONE 421 422 /** 423 * Allocate a session ID that can be used to attach and control 424 * effects using the Java AudioEffects API. 425 * Note that the use of this flag may result in higher latency. 426 * 427 * Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE. 428 */ 429 Allocate = 0, // AAUDIO_SESSION_ID_ALLOCATE 430 }; 431 432 /** 433 * The channel count of the audio stream. The underlying type is `int32_t`. 434 * Use of this enum is convenient to avoid "magic" 435 * numbers when specifying the channel count. 436 * 437 * For example, you can write 438 * `builder.setChannelCount(ChannelCount::Stereo)` 439 * rather than `builder.setChannelCount(2)` 440 * 441 */ 442 enum ChannelCount : int32_t { 443 /** 444 * Audio channel count definition, use Mono or Stereo 445 */ 446 Unspecified = kUnspecified, 447 448 /** 449 * Use this for mono audio 450 */ 451 Mono = 1, 452 453 /** 454 * Use this for stereo audio. 455 */ 456 Stereo = 2, 457 }; 458 459 /** 460 * On API 16 to 26 OpenSL ES will be used. When using OpenSL ES the optimal values for sampleRate and 461 * framesPerBurst are not known by the native code. 462 * On API 17+ these values should be obtained from the AudioManager using this code: 463 * 464 * <pre><code> 465 * // Note that this technique only works for built-in speakers and headphones. 466 * AudioManager myAudioMgr = (AudioManager) getSystemService(Context.AUDIO_SERVICE); 467 * String sampleRateStr = myAudioMgr.getProperty(AudioManager.PROPERTY_OUTPUT_SAMPLE_RATE); 468 * int defaultSampleRate = Integer.parseInt(sampleRateStr); 469 * String framesPerBurstStr = myAudioMgr.getProperty(AudioManager.PROPERTY_OUTPUT_FRAMES_PER_BUFFER); 470 * int defaultFramesPerBurst = Integer.parseInt(framesPerBurstStr); 471 * </code></pre> 472 * 473 * It can then be passed down to Oboe through JNI. 474 * 475 * AAudio will get the optimal framesPerBurst from the HAL and will ignore this value. 476 */ 477 class DefaultStreamValues { 478 479 public: 480 481 /** The default sample rate to use when opening new audio streams */ 482 static int32_t SampleRate; 483 /** The default frames per burst to use when opening new audio streams */ 484 static int32_t FramesPerBurst; 485 /** The default channel count to use when opening new audio streams */ 486 static int32_t ChannelCount; 487 488 }; 489 490 /** 491 * The time at which the frame at `position` was presented 492 */ 493 struct FrameTimestamp { 494 int64_t position; // in frames 495 int64_t timestamp; // in nanoseconds 496 }; 497 498 class OboeGlobals { 499 public: 500 areWorkaroundsEnabled()501 static bool areWorkaroundsEnabled() { 502 return mWorkaroundsEnabled; 503 } 504 505 /** 506 * Disable this when writing tests to reproduce bugs in AAudio or OpenSL ES 507 * that have workarounds in Oboe. 508 * @param enabled 509 */ setWorkaroundsEnabled(bool enabled)510 static void setWorkaroundsEnabled(bool enabled) { 511 mWorkaroundsEnabled = enabled; 512 } 513 514 private: 515 static bool mWorkaroundsEnabled; 516 }; 517 } // namespace oboe 518 519 #endif // OBOE_DEFINITIONS_H 520