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 true if Oboe can convert channel counts to achieve optimal results. 162 */ isChannelConversionAllowed()163 bool isChannelConversionAllowed() const { 164 return mChannelConversionAllowed; 165 } 166 167 /** 168 * @return true if Oboe can convert data formats to achieve optimal results. 169 */ isFormatConversionAllowed()170 bool isFormatConversionAllowed() const { 171 return mFormatConversionAllowed; 172 } 173 174 /** 175 * @return whether and how Oboe can convert sample rates to achieve optimal results. 176 */ getSampleRateConversionQuality()177 SampleRateConversionQuality getSampleRateConversionQuality() const { 178 return mSampleRateConversionQuality; 179 } 180 181 /** 182 * @return the stream's channel mask. 183 */ getChannelMask()184 ChannelMask getChannelMask() const { 185 return mChannelMask; 186 } 187 188 protected: 189 /** The callback which will be fired when new data is ready to be read/written. **/ 190 AudioStreamDataCallback *mDataCallback = nullptr; 191 std::shared_ptr<AudioStreamDataCallback> mSharedDataCallback; 192 193 /** The callback which will be fired when an error or a disconnect occurs. **/ 194 AudioStreamErrorCallback *mErrorCallback = nullptr; 195 std::shared_ptr<AudioStreamErrorCallback> mSharedErrorCallback; 196 197 /** Number of audio frames which will be requested in each callback */ 198 int32_t mFramesPerCallback = kUnspecified; 199 /** Stream channel count */ 200 int32_t mChannelCount = kUnspecified; 201 /** Stream sample rate */ 202 int32_t mSampleRate = kUnspecified; 203 /** Stream audio device ID */ 204 int32_t mDeviceId = kUnspecified; 205 /** Stream buffer capacity specified as a number of audio frames */ 206 int32_t mBufferCapacityInFrames = kUnspecified; 207 /** Stream buffer size specified as a number of audio frames */ 208 int32_t mBufferSizeInFrames = kUnspecified; 209 /** Stream channel mask. Only active on Android 32+ */ 210 ChannelMask mChannelMask = ChannelMask::Unspecified; 211 212 /** Stream sharing mode */ 213 SharingMode mSharingMode = SharingMode::Shared; 214 /** Format of audio frames */ 215 AudioFormat mFormat = AudioFormat::Unspecified; 216 /** Stream direction */ 217 Direction mDirection = Direction::Output; 218 /** Stream performance mode */ 219 PerformanceMode mPerformanceMode = PerformanceMode::None; 220 221 /** Stream usage. Only active on Android 28+ */ 222 Usage mUsage = Usage::Media; 223 /** Stream content type. Only active on Android 28+ */ 224 ContentType mContentType = ContentType::Music; 225 /** Stream input preset. Only active on Android 28+ 226 * TODO InputPreset::Unspecified should be considered as a possible default alternative. 227 */ 228 InputPreset mInputPreset = InputPreset::VoiceRecognition; 229 /** Stream session ID allocation strategy. Only active on Android 28+ */ 230 SessionId mSessionId = SessionId::None; 231 232 /** Control the name of the package creating the stream. Only active on Android 31+ */ 233 std::string mPackageName; 234 /** Control the attribution tag of the context creating the stream. Only active on Android 31+ */ 235 std::string mAttributionTag; 236 237 // Control whether Oboe can convert channel counts to achieve optimal results. 238 bool mChannelConversionAllowed = false; 239 // Control whether Oboe can convert data formats to achieve optimal results. 240 bool mFormatConversionAllowed = false; 241 // Control whether and how Oboe can convert sample rates to achieve optimal results. 242 SampleRateConversionQuality mSampleRateConversionQuality = SampleRateConversionQuality::None; 243 244 /** Validate stream parameters that might not be checked in lower layers */ isValidConfig()245 virtual Result isValidConfig() { 246 switch (mFormat) { 247 case AudioFormat::Unspecified: 248 case AudioFormat::I16: 249 case AudioFormat::Float: 250 case AudioFormat::I24: 251 case AudioFormat::I32: 252 break; 253 254 default: 255 return Result::ErrorInvalidFormat; 256 } 257 258 switch (mSampleRateConversionQuality) { 259 case SampleRateConversionQuality::None: 260 case SampleRateConversionQuality::Fastest: 261 case SampleRateConversionQuality::Low: 262 case SampleRateConversionQuality::Medium: 263 case SampleRateConversionQuality::High: 264 case SampleRateConversionQuality::Best: 265 return Result::OK; 266 default: 267 return Result::ErrorIllegalArgument; 268 } 269 } 270 }; 271 272 } // namespace oboe 273 274 #endif /* OBOE_STREAM_BASE_H_ */ 275