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 * @return true if a data callback was set for this stream 126 */ isDataCallbackSpecified()127 bool isDataCallbackSpecified() const { 128 return mDataCallback != nullptr; 129 } 130 131 /** 132 * Note that if the app does not set an error callback then a 133 * default one may be provided. 134 * @return true if an error callback was set for this stream 135 */ isErrorCallbackSpecified()136 bool isErrorCallbackSpecified() const { 137 return mErrorCallback != nullptr; 138 } 139 140 /** 141 * @return the usage for this stream. 142 */ getUsage()143 Usage getUsage() const { return mUsage; } 144 145 /** 146 * @return the stream's content type. 147 */ getContentType()148 ContentType getContentType() const { return mContentType; } 149 150 /** 151 * @return the stream's input preset. 152 */ getInputPreset()153 InputPreset getInputPreset() const { return mInputPreset; } 154 155 /** 156 * @return the stream's session ID allocation strategy (None or Allocate). 157 */ getSessionId()158 SessionId getSessionId() const { return mSessionId; } 159 160 /** 161 * @return whether the content of the stream is spatialized. 162 */ isContentSpatialized()163 bool isContentSpatialized() const { return mIsContentSpatialized; } 164 165 /** 166 * @return the spatialization behavior for the stream. 167 */ getSpatializationBehavior()168 SpatializationBehavior getSpatializationBehavior() const { return mSpatializationBehavior; } 169 170 /** 171 * Return the policy that determines whether the audio may or may not be captured 172 * by other apps or the system. 173 * 174 * See AudioStreamBuilder_setAllowedCapturePolicy(). 175 * 176 * Added in API level 29 to AAudio. 177 * 178 * @return the allowed capture policy, for example AllowedCapturePolicy::All 179 */ getAllowedCapturePolicy()180 AllowedCapturePolicy getAllowedCapturePolicy() const { return mAllowedCapturePolicy; } 181 182 /** 183 * Return whether this input stream is marked as privacy sensitive. 184 * 185 * See AudioStreamBuilder_setPrivacySensitiveMode(). 186 * 187 * Added in API level 30 to AAudio. 188 * 189 * @return PrivacySensitiveMode::Enabled if privacy sensitive, 190 * PrivacySensitiveMode::Disabled if not privacy sensitive, and 191 * PrivacySensitiveMode::Unspecified if API is not supported. 192 */ getPrivacySensitiveMode()193 PrivacySensitiveMode getPrivacySensitiveMode() const { return mPrivacySensitiveMode; } 194 195 /** 196 * @return true if Oboe can convert channel counts to achieve optimal results. 197 */ isChannelConversionAllowed()198 bool isChannelConversionAllowed() const { 199 return mChannelConversionAllowed; 200 } 201 202 /** 203 * @return true if Oboe can convert data formats to achieve optimal results. 204 */ isFormatConversionAllowed()205 bool isFormatConversionAllowed() const { 206 return mFormatConversionAllowed; 207 } 208 209 /** 210 * @return whether and how Oboe can convert sample rates to achieve optimal results. 211 */ getSampleRateConversionQuality()212 SampleRateConversionQuality getSampleRateConversionQuality() const { 213 return mSampleRateConversionQuality; 214 } 215 216 /** 217 * @return the stream's channel mask. 218 */ getChannelMask()219 ChannelMask getChannelMask() const { 220 return mChannelMask; 221 } 222 223 /** 224 * @return number of channels for the hardware, for example 2 for stereo, or kUnspecified. 225 */ getHardwareChannelCount()226 int32_t getHardwareChannelCount() const { return mHardwareChannelCount; } 227 228 /** 229 * @return hardware sample rate for the stream or kUnspecified 230 */ getHardwareSampleRate()231 int32_t getHardwareSampleRate() const { return mHardwareSampleRate; } 232 233 /** 234 * @return the audio sample format of the hardware (e.g. Float or I16) 235 */ getHardwareFormat()236 AudioFormat getHardwareFormat() const { return mHardwareFormat; } 237 238 protected: 239 /** The callback which will be fired when new data is ready to be read/written. **/ 240 AudioStreamDataCallback *mDataCallback = nullptr; 241 std::shared_ptr<AudioStreamDataCallback> mSharedDataCallback; 242 243 /** The callback which will be fired when an error or a disconnect occurs. **/ 244 AudioStreamErrorCallback *mErrorCallback = nullptr; 245 std::shared_ptr<AudioStreamErrorCallback> mSharedErrorCallback; 246 247 /** Number of audio frames which will be requested in each callback */ 248 int32_t mFramesPerCallback = kUnspecified; 249 /** Stream channel count */ 250 int32_t mChannelCount = kUnspecified; 251 /** Stream sample rate */ 252 int32_t mSampleRate = kUnspecified; 253 /** Stream audio device ID */ 254 int32_t mDeviceId = kUnspecified; 255 /** Stream buffer capacity specified as a number of audio frames */ 256 int32_t mBufferCapacityInFrames = kUnspecified; 257 /** Stream buffer size specified as a number of audio frames */ 258 int32_t mBufferSizeInFrames = kUnspecified; 259 /** Stream channel mask. Only active on Android 32+ */ 260 ChannelMask mChannelMask = ChannelMask::Unspecified; 261 262 /** Stream sharing mode */ 263 SharingMode mSharingMode = SharingMode::Shared; 264 /** Format of audio frames */ 265 AudioFormat mFormat = AudioFormat::Unspecified; 266 /** Stream direction */ 267 Direction mDirection = Direction::Output; 268 /** Stream performance mode */ 269 PerformanceMode mPerformanceMode = PerformanceMode::None; 270 271 /** Stream usage. Only active on Android 28+ */ 272 Usage mUsage = Usage::Media; 273 /** Stream content type. Only active on Android 28+ */ 274 ContentType mContentType = ContentType::Music; 275 /** Stream input preset. Only active on Android 28+ 276 * TODO InputPreset::Unspecified should be considered as a possible default alternative. 277 */ 278 InputPreset mInputPreset = InputPreset::VoiceRecognition; 279 /** Stream session ID allocation strategy. Only active on Android 28+ */ 280 SessionId mSessionId = SessionId::None; 281 282 /** Allowed Capture Policy. Only active on Android 29+ */ 283 AllowedCapturePolicy mAllowedCapturePolicy = AllowedCapturePolicy::Unspecified; 284 285 /** Privacy Sensitive Mode. Only active on Android 30+ */ 286 PrivacySensitiveMode mPrivacySensitiveMode = PrivacySensitiveMode::Unspecified; 287 288 /** Control the name of the package creating the stream. Only active on Android 31+ */ 289 std::string mPackageName; 290 /** Control the attribution tag of the context creating the stream. Only active on Android 31+ */ 291 std::string mAttributionTag; 292 293 /** Whether the content is already spatialized. Only used on Android 32+ */ 294 bool mIsContentSpatialized = false; 295 /** Spatialization Behavior. Only active on Android 32+ */ 296 SpatializationBehavior mSpatializationBehavior = SpatializationBehavior::Unspecified; 297 298 /** Hardware channel count. Only specified on Android 34+ AAudio streams */ 299 int32_t mHardwareChannelCount = kUnspecified; 300 /** Hardware sample rate. Only specified on Android 34+ AAudio streams */ 301 int32_t mHardwareSampleRate = kUnspecified; 302 /** Hardware format. Only specified on Android 34+ AAudio streams */ 303 AudioFormat mHardwareFormat = AudioFormat::Unspecified; 304 305 // Control whether Oboe can convert channel counts to achieve optimal results. 306 bool mChannelConversionAllowed = false; 307 // Control whether Oboe can convert data formats to achieve optimal results. 308 bool mFormatConversionAllowed = false; 309 // Control whether and how Oboe can convert sample rates to achieve optimal results. 310 SampleRateConversionQuality mSampleRateConversionQuality = SampleRateConversionQuality::None; 311 312 /** Validate stream parameters that might not be checked in lower layers */ isValidConfig()313 virtual Result isValidConfig() { 314 switch (mFormat) { 315 case AudioFormat::Unspecified: 316 case AudioFormat::I16: 317 case AudioFormat::Float: 318 case AudioFormat::I24: 319 case AudioFormat::I32: 320 case AudioFormat::IEC61937: 321 break; 322 323 default: 324 return Result::ErrorInvalidFormat; 325 } 326 327 switch (mSampleRateConversionQuality) { 328 case SampleRateConversionQuality::None: 329 case SampleRateConversionQuality::Fastest: 330 case SampleRateConversionQuality::Low: 331 case SampleRateConversionQuality::Medium: 332 case SampleRateConversionQuality::High: 333 case SampleRateConversionQuality::Best: 334 return Result::OK; 335 default: 336 return Result::ErrorIllegalArgument; 337 } 338 } 339 }; 340 341 } // namespace oboe 342 343 #endif /* OBOE_STREAM_BASE_H_ */ 344