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 "oboe/AudioStreamCallback.h" 22 #include "oboe/Definitions.h" 23 24 namespace oboe { 25 26 /** 27 * Base class containing parameters for audio streams and builders. 28 **/ 29 class AudioStreamBase { 30 31 public: 32 AudioStreamBase()33 AudioStreamBase() {} 34 35 virtual ~AudioStreamBase() = default; 36 37 // This class only contains primitives so we can use default constructor and copy methods. 38 39 /** 40 * Default copy constructor 41 */ 42 AudioStreamBase(const AudioStreamBase&) = default; 43 44 /** 45 * Default assignment operator 46 */ 47 AudioStreamBase& operator=(const AudioStreamBase&) = default; 48 49 /** 50 * @return number of channels, for example 2 for stereo, or kUnspecified 51 */ getChannelCount()52 int32_t getChannelCount() const { return mChannelCount; } 53 54 /** 55 * @return Direction::Input or Direction::Output 56 */ getDirection()57 Direction getDirection() const { return mDirection; } 58 59 /** 60 * @return sample rate for the stream or kUnspecified 61 */ getSampleRate()62 int32_t getSampleRate() const { return mSampleRate; } 63 64 /** 65 * @deprecated use `getFramesPerDataCallback` instead. 66 */ getFramesPerCallback()67 int32_t getFramesPerCallback() const { return getFramesPerDataCallback(); } 68 69 /** 70 * @return the number of frames in each data callback or kUnspecified. 71 */ getFramesPerDataCallback()72 int32_t getFramesPerDataCallback() const { return mFramesPerCallback; } 73 74 /** 75 * @return the audio sample format (e.g. Float or I16) 76 */ getFormat()77 AudioFormat getFormat() const { return mFormat; } 78 79 /** 80 * Query the maximum number of frames that can be filled without blocking. 81 * If the stream has been closed the last known value will be returned. 82 * 83 * @return buffer size 84 */ getBufferSizeInFrames()85 virtual int32_t getBufferSizeInFrames() { return mBufferSizeInFrames; } 86 87 /** 88 * @return capacityInFrames or kUnspecified 89 */ getBufferCapacityInFrames()90 virtual int32_t getBufferCapacityInFrames() const { return mBufferCapacityInFrames; } 91 92 /** 93 * @return the sharing mode of the stream. 94 */ getSharingMode()95 SharingMode getSharingMode() const { return mSharingMode; } 96 97 /** 98 * @return the performance mode of the stream. 99 */ getPerformanceMode()100 PerformanceMode getPerformanceMode() const { return mPerformanceMode; } 101 102 /** 103 * @return the device ID of the stream. 104 */ getDeviceId()105 int32_t getDeviceId() const { return mDeviceId; } 106 107 /** 108 * For internal use only. 109 * @return the data callback object for this stream, if set. 110 */ getDataCallback()111 AudioStreamDataCallback *getDataCallback() const { 112 return mDataCallback; 113 } 114 115 /** 116 * For internal use only. 117 * @return the error callback object for this stream, if set. 118 */ getErrorCallback()119 AudioStreamErrorCallback *getErrorCallback() const { 120 return mErrorCallback; 121 } 122 123 /** 124 * @return true if a data callback was set for this stream 125 */ isDataCallbackSpecified()126 bool isDataCallbackSpecified() const { 127 return mDataCallback != nullptr; 128 } 129 130 /** 131 * Note that if the app does not set an error callback then a 132 * default one may be provided. 133 * @return true if an error callback was set for this stream 134 */ isErrorCallbackSpecified()135 bool isErrorCallbackSpecified() const { 136 return mErrorCallback != nullptr; 137 } 138 139 /** 140 * @return the usage for this stream. 141 */ getUsage()142 Usage getUsage() const { return mUsage; } 143 144 /** 145 * @return the stream's content type. 146 */ getContentType()147 ContentType getContentType() const { return mContentType; } 148 149 /** 150 * @return the stream's input preset. 151 */ getInputPreset()152 InputPreset getInputPreset() const { return mInputPreset; } 153 154 /** 155 * @return the stream's session ID allocation strategy (None or Allocate). 156 */ getSessionId()157 SessionId getSessionId() const { return mSessionId; } 158 159 /** 160 * @return true if Oboe can convert channel counts to achieve optimal results. 161 */ isChannelConversionAllowed()162 bool isChannelConversionAllowed() const { 163 return mChannelConversionAllowed; 164 } 165 166 /** 167 * @return true if Oboe can convert data formats to achieve optimal results. 168 */ isFormatConversionAllowed()169 bool isFormatConversionAllowed() const { 170 return mFormatConversionAllowed; 171 } 172 173 /** 174 * @return whether and how Oboe can convert sample rates to achieve optimal results. 175 */ getSampleRateConversionQuality()176 SampleRateConversionQuality getSampleRateConversionQuality() const { 177 return mSampleRateConversionQuality; 178 } 179 180 protected: 181 /** The callback which will be fired when new data is ready to be read/written. **/ 182 AudioStreamDataCallback *mDataCallback = nullptr; 183 184 /** The callback which will be fired when an error or a disconnect occurs. **/ 185 AudioStreamErrorCallback *mErrorCallback = nullptr; 186 187 /** Number of audio frames which will be requested in each callback */ 188 int32_t mFramesPerCallback = kUnspecified; 189 /** Stream channel count */ 190 int32_t mChannelCount = kUnspecified; 191 /** Stream sample rate */ 192 int32_t mSampleRate = kUnspecified; 193 /** Stream audio device ID */ 194 int32_t mDeviceId = kUnspecified; 195 /** Stream buffer capacity specified as a number of audio frames */ 196 int32_t mBufferCapacityInFrames = kUnspecified; 197 /** Stream buffer size specified as a number of audio frames */ 198 int32_t mBufferSizeInFrames = kUnspecified; 199 /** 200 * Number of frames which will be copied to/from the audio device in a single read/write 201 * operation 202 */ 203 int32_t mFramesPerBurst = kUnspecified; 204 205 /** Stream sharing mode */ 206 SharingMode mSharingMode = SharingMode::Shared; 207 /** Format of audio frames */ 208 AudioFormat mFormat = AudioFormat::Unspecified; 209 /** Stream direction */ 210 Direction mDirection = Direction::Output; 211 /** Stream performance mode */ 212 PerformanceMode mPerformanceMode = PerformanceMode::None; 213 214 /** Stream usage. Only active on Android 28+ */ 215 Usage mUsage = Usage::Media; 216 /** Stream content type. Only active on Android 28+ */ 217 ContentType mContentType = ContentType::Music; 218 /** Stream input preset. Only active on Android 28+ 219 * TODO InputPreset::Unspecified should be considered as a possible default alternative. 220 */ 221 InputPreset mInputPreset = InputPreset::VoiceRecognition; 222 /** Stream session ID allocation strategy. Only active on Android 28+ */ 223 SessionId mSessionId = SessionId::None; 224 225 // Control whether Oboe can convert channel counts to achieve optimal results. 226 bool mChannelConversionAllowed = false; 227 // Control whether Oboe can convert data formats to achieve optimal results. 228 bool mFormatConversionAllowed = false; 229 // Control whether and how Oboe can convert sample rates to achieve optimal results. 230 SampleRateConversionQuality mSampleRateConversionQuality = SampleRateConversionQuality::None; 231 232 /** Validate stream parameters that might not be checked in lower layers */ isValidConfig()233 virtual Result isValidConfig() { 234 switch (mFormat) { 235 case AudioFormat::Unspecified: 236 case AudioFormat::I16: 237 case AudioFormat::Float: 238 break; 239 240 default: 241 return Result::ErrorInvalidFormat; 242 } 243 244 switch (mSampleRateConversionQuality) { 245 case SampleRateConversionQuality::None: 246 case SampleRateConversionQuality::Fastest: 247 case SampleRateConversionQuality::Low: 248 case SampleRateConversionQuality::Medium: 249 case SampleRateConversionQuality::High: 250 case SampleRateConversionQuality::Best: 251 return Result::OK; 252 default: 253 return Result::ErrorIllegalArgument; 254 } 255 } 256 }; 257 258 } // namespace oboe 259 260 #endif /* OBOE_STREAM_BASE_H_ */ 261