1 /* 2 * Copyright 2015 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_STREAM_BASE_H_ 18 #define OBOE_STREAM_BASE_H_ 19 20 #include <memory> 21 #include <string> 22 #include "oboe/AudioStreamCallback.h" 23 #include "oboe/Definitions.h" 24 25 namespace oboe { 26 27 /** 28 * Base class containing parameters for audio streams and builders. 29 **/ 30 class AudioStreamBase { 31 32 public: 33 AudioStreamBase()34 AudioStreamBase() {} 35 36 virtual ~AudioStreamBase() = default; 37 38 // This class only contains primitives so we can use default constructor and copy methods. 39 40 /** 41 * Default copy constructor 42 */ 43 AudioStreamBase(const AudioStreamBase&) = default; 44 45 /** 46 * Default assignment operator 47 */ 48 AudioStreamBase& operator=(const AudioStreamBase&) = default; 49 50 /** 51 * @return number of channels, for example 2 for stereo, or kUnspecified 52 */ getChannelCount()53 int32_t getChannelCount() const { return mChannelCount; } 54 55 /** 56 * @return Direction::Input or Direction::Output 57 */ getDirection()58 Direction getDirection() const { return mDirection; } 59 60 /** 61 * @return sample rate for the stream or kUnspecified 62 */ getSampleRate()63 int32_t getSampleRate() const { return mSampleRate; } 64 65 /** 66 * @deprecated use `getFramesPerDataCallback` instead. 67 */ getFramesPerCallback()68 int32_t getFramesPerCallback() const { return getFramesPerDataCallback(); } 69 70 /** 71 * @return the number of frames in each data callback or kUnspecified. 72 */ getFramesPerDataCallback()73 int32_t getFramesPerDataCallback() const { return mFramesPerCallback; } 74 75 /** 76 * @return the audio sample format (e.g. Float or I16) 77 */ getFormat()78 AudioFormat getFormat() const { return mFormat; } 79 80 /** 81 * Query the maximum number of frames that can be filled without blocking. 82 * If the stream has been closed the last known value will be returned. 83 * 84 * @return buffer size 85 */ getBufferSizeInFrames()86 virtual int32_t getBufferSizeInFrames() { return mBufferSizeInFrames; } 87 88 /** 89 * @return capacityInFrames or kUnspecified 90 */ getBufferCapacityInFrames()91 virtual int32_t getBufferCapacityInFrames() const { return mBufferCapacityInFrames; } 92 93 /** 94 * @return the sharing mode of the stream. 95 */ getSharingMode()96 SharingMode getSharingMode() const { return mSharingMode; } 97 98 /** 99 * @return the performance mode of the stream. 100 */ getPerformanceMode()101 PerformanceMode getPerformanceMode() const { return mPerformanceMode; } 102 103 /** 104 * @return the device ID of the stream. 105 */ getDeviceId()106 int32_t getDeviceId() const { return mDeviceId; } 107 108 /** 109 * For internal use only. 110 * @return the data callback object for this stream, if set. 111 */ getDataCallback()112 AudioStreamDataCallback *getDataCallback() const { 113 return mDataCallback; 114 } 115 116 /** 117 * For internal use only. 118 * @return the error callback object for this stream, if set. 119 */ getErrorCallback()120 AudioStreamErrorCallback *getErrorCallback() const { 121 return mErrorCallback; 122 } 123 124 /** 125 * For internal use only. 126 * @return the presentation callback object for this stream, if set. 127 */ getPresentationCallback()128 std::shared_ptr<AudioStreamPresentationCallback> getPresentationCallback() const { 129 return mSharedPresentationCallback; 130 } 131 132 /** 133 * @return true if a data callback was set for this stream 134 */ isDataCallbackSpecified()135 bool isDataCallbackSpecified() const { 136 return mDataCallback != nullptr; 137 } 138 139 /** 140 * Note that if the app does not set an error callback then a 141 * default one may be provided. 142 * @return true if an error callback was set for this stream 143 */ isErrorCallbackSpecified()144 bool isErrorCallbackSpecified() const { 145 return mErrorCallback != nullptr; 146 } 147 148 /** 149 * @return true if a presentation callback was set for this stream 150 */ isPresentationCallbackSpecified()151 bool isPresentationCallbackSpecified() const { 152 return mSharedPresentationCallback != nullptr; 153 } 154 155 /** 156 * @return the usage for this stream. 157 */ getUsage()158 Usage getUsage() const { return mUsage; } 159 160 /** 161 * @return the stream's content type. 162 */ getContentType()163 ContentType getContentType() const { return mContentType; } 164 165 /** 166 * @return the stream's input preset. 167 */ getInputPreset()168 InputPreset getInputPreset() const { return mInputPreset; } 169 170 /** 171 * @return the stream's session ID allocation strategy (None or Allocate). 172 */ getSessionId()173 SessionId getSessionId() const { return mSessionId; } 174 175 /** 176 * @return whether the content of the stream is spatialized. 177 */ isContentSpatialized()178 bool isContentSpatialized() const { return mIsContentSpatialized; } 179 180 /** 181 * @return the spatialization behavior for the stream. 182 */ getSpatializationBehavior()183 SpatializationBehavior getSpatializationBehavior() const { return mSpatializationBehavior; } 184 185 /** 186 * Return the policy that determines whether the audio may or may not be captured 187 * by other apps or the system. 188 * 189 * See AudioStreamBuilder_setAllowedCapturePolicy(). 190 * 191 * Added in API level 29 to AAudio. 192 * 193 * @return the allowed capture policy, for example AllowedCapturePolicy::All 194 */ getAllowedCapturePolicy()195 AllowedCapturePolicy getAllowedCapturePolicy() const { return mAllowedCapturePolicy; } 196 197 /** 198 * Return whether this input stream is marked as privacy sensitive. 199 * 200 * See AudioStreamBuilder_setPrivacySensitiveMode(). 201 * 202 * Added in API level 30 to AAudio. 203 * 204 * @return PrivacySensitiveMode::Enabled if privacy sensitive, 205 * PrivacySensitiveMode::Disabled if not privacy sensitive, and 206 * PrivacySensitiveMode::Unspecified if API is not supported. 207 */ getPrivacySensitiveMode()208 PrivacySensitiveMode getPrivacySensitiveMode() const { return mPrivacySensitiveMode; } 209 210 /** 211 * @return true if Oboe can convert channel counts to achieve optimal results. 212 */ isChannelConversionAllowed()213 bool isChannelConversionAllowed() const { 214 return mChannelConversionAllowed; 215 } 216 217 /** 218 * @return true if Oboe can convert data formats to achieve optimal results. 219 */ isFormatConversionAllowed()220 bool isFormatConversionAllowed() const { 221 return mFormatConversionAllowed; 222 } 223 224 /** 225 * @return whether and how Oboe can convert sample rates to achieve optimal results. 226 */ getSampleRateConversionQuality()227 SampleRateConversionQuality getSampleRateConversionQuality() const { 228 return mSampleRateConversionQuality; 229 } 230 231 /** 232 * @return the stream's channel mask. 233 */ getChannelMask()234 ChannelMask getChannelMask() const { 235 return mChannelMask; 236 } 237 238 /** 239 * @return number of channels for the hardware, for example 2 for stereo, or kUnspecified. 240 */ getHardwareChannelCount()241 int32_t getHardwareChannelCount() const { return mHardwareChannelCount; } 242 243 /** 244 * @return hardware sample rate for the stream or kUnspecified 245 */ getHardwareSampleRate()246 int32_t getHardwareSampleRate() const { return mHardwareSampleRate; } 247 248 /** 249 * @return the audio sample format of the hardware (e.g. Float or I16) 250 */ getHardwareFormat()251 AudioFormat getHardwareFormat() const { return mHardwareFormat; } 252 253 protected: 254 /** The callback which will be fired when new data is ready to be read/written. **/ 255 AudioStreamDataCallback *mDataCallback = nullptr; 256 std::shared_ptr<AudioStreamDataCallback> mSharedDataCallback; 257 258 /** The callback which will be fired when an error or a disconnect occurs. **/ 259 AudioStreamErrorCallback *mErrorCallback = nullptr; 260 std::shared_ptr<AudioStreamErrorCallback> mSharedErrorCallback; 261 262 std::shared_ptr<AudioStreamPresentationCallback> mSharedPresentationCallback; 263 264 /** Number of audio frames which will be requested in each callback */ 265 int32_t mFramesPerCallback = kUnspecified; 266 /** Stream channel count */ 267 int32_t mChannelCount = kUnspecified; 268 /** Stream sample rate */ 269 int32_t mSampleRate = kUnspecified; 270 /** Stream audio device ID */ 271 int32_t mDeviceId = kUnspecified; 272 /** Stream buffer capacity specified as a number of audio frames */ 273 int32_t mBufferCapacityInFrames = kUnspecified; 274 /** Stream buffer size specified as a number of audio frames */ 275 int32_t mBufferSizeInFrames = kUnspecified; 276 /** Stream channel mask. Only active on Android 32+ */ 277 ChannelMask mChannelMask = ChannelMask::Unspecified; 278 279 /** Stream sharing mode */ 280 SharingMode mSharingMode = SharingMode::Shared; 281 /** Format of audio frames */ 282 AudioFormat mFormat = AudioFormat::Unspecified; 283 /** Stream direction */ 284 Direction mDirection = Direction::Output; 285 /** Stream performance mode */ 286 PerformanceMode mPerformanceMode = PerformanceMode::None; 287 288 /** Stream usage. Only active on Android 28+ */ 289 Usage mUsage = Usage::Media; 290 /** Stream content type. Only active on Android 28+ */ 291 ContentType mContentType = ContentType::Music; 292 /** Stream input preset. Only active on Android 28+ 293 * TODO InputPreset::Unspecified should be considered as a possible default alternative. 294 */ 295 InputPreset mInputPreset = InputPreset::VoiceRecognition; 296 /** Stream session ID allocation strategy. Only active on Android 28+ */ 297 SessionId mSessionId = SessionId::None; 298 299 /** Allowed Capture Policy. Only active on Android 29+ */ 300 AllowedCapturePolicy mAllowedCapturePolicy = AllowedCapturePolicy::Unspecified; 301 302 /** Privacy Sensitive Mode. Only active on Android 30+ */ 303 PrivacySensitiveMode mPrivacySensitiveMode = PrivacySensitiveMode::Unspecified; 304 305 /** Control the name of the package creating the stream. Only active on Android 31+ */ 306 std::string mPackageName; 307 /** Control the attribution tag of the context creating the stream. Only active on Android 31+ */ 308 std::string mAttributionTag; 309 310 /** Whether the content is already spatialized. Only used on Android 32+ */ 311 bool mIsContentSpatialized = false; 312 /** Spatialization Behavior. Only active on Android 32+ */ 313 SpatializationBehavior mSpatializationBehavior = SpatializationBehavior::Unspecified; 314 315 /** Hardware channel count. Only specified on Android 34+ AAudio streams */ 316 int32_t mHardwareChannelCount = kUnspecified; 317 /** Hardware sample rate. Only specified on Android 34+ AAudio streams */ 318 int32_t mHardwareSampleRate = kUnspecified; 319 /** Hardware format. Only specified on Android 34+ AAudio streams */ 320 AudioFormat mHardwareFormat = AudioFormat::Unspecified; 321 322 // Control whether Oboe can convert channel counts to achieve optimal results. 323 bool mChannelConversionAllowed = false; 324 // Control whether Oboe can convert data formats to achieve optimal results. 325 bool mFormatConversionAllowed = false; 326 // Control whether and how Oboe can convert sample rates to achieve optimal results. 327 SampleRateConversionQuality mSampleRateConversionQuality = SampleRateConversionQuality::Medium; 328 329 /** Validate stream parameters that might not be checked in lower layers */ isValidConfig()330 virtual Result isValidConfig() { 331 switch (mFormat) { 332 case AudioFormat::Unspecified: 333 case AudioFormat::I16: 334 case AudioFormat::Float: 335 case AudioFormat::I24: 336 case AudioFormat::I32: 337 case AudioFormat::IEC61937: 338 break; 339 340 default: 341 return Result::ErrorInvalidFormat; 342 } 343 344 switch (mSampleRateConversionQuality) { 345 case SampleRateConversionQuality::None: 346 case SampleRateConversionQuality::Fastest: 347 case SampleRateConversionQuality::Low: 348 case SampleRateConversionQuality::Medium: 349 case SampleRateConversionQuality::High: 350 case SampleRateConversionQuality::Best: 351 return Result::OK; 352 default: 353 return Result::ErrorIllegalArgument; 354 } 355 } 356 }; 357 358 } // namespace oboe 359 360 #endif /* OBOE_STREAM_BASE_H_ */ 361